XdmfArray.hpp 12.9 KB
Newer Older
Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
1 2 3
#ifndef XDMFARRAY_HPP_
#define XDMFARRAY_HPP_

4
// Forward Declarations
5
class XdmfArrayType;
6 7
class XdmfHDF5Controller;

Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
8 9
// Includes
#include "XdmfItem.hpp"
10
#include <boost/shared_array.hpp>
Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
11 12
#include <boost/variant.hpp>

13 14 15 16 17 18 19 20 21 22
/**
 * @brief Provides a single interface for storing a wide variety of data types.
 *
 * XdmfArray stores data values that are read in or will be written to heavy data on disk. The
 * data type stored is determined by the type initially inserted into the XdmfArray.  XdmfArray
 * allows for insertion and retrieval of data in two fundamental ways:
 *
 * By Copy:
 *
 *  copyValues
23
 * 	getValuesCopy
24 25 26 27 28 29 30 31 32 33 34 35 36 37
 *
 * 	XdmfArray stores its own copy of the data.  Modifications to the data stored in the XdmfArray will
 * 	not change values stored in the original array.
 *
 * By Shared Reference:
 *
 * 	setValues
 * 	getValues
 *
 * 	XdmfArray shares a reference to the data.  No copy is made. XdmfArray holds a shared pointer to the original
 * 	data.  Modifications to the data stored in the XdmfArray also causes modification to values stored in the original
 * 	array.
 *
 * Xdmf supports the following datatypes:
38 39 40 41 42 43 44 45 46
 * 	Int8
 * 	Int16
 * 	Int32
 * 	Int64
 * 	Float32
 * 	Float64
 * 	UInt8
 * 	UInt16
 * 	UInt32
47
 */
Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
48
class XdmfArray : public XdmfItem {
49

Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
50 51
public:

52 53 54 55 56
	/**
	 * Create a new XdmfArray.
	 *
	 * @return constructed XdmfArray.
	 */
57
	static boost::shared_ptr<XdmfArray> New();
58

59 60
	virtual ~XdmfArray();

61
	LOKI_DEFINE_VISITABLE(XdmfArray, XdmfItem)
62
	friend class XdmfHDF5Writer;
63
	static const std::string ItemTag;
64

65
	/**
66
	 * Copy values from an XdmfArray into this array.
67
	 *
68 69
	 * @param startIndex the index in this array to begin insertion.
	 * @param values a shared pointer to an XdmfArray to copy into this array.
70
	 * @param valuesStartIndex the index in the XdmfArray to begin copying.
71 72 73
	 * @param numValues the number of values to copy into this array.
	 * @param arrayStride number of values to stride in this array between each copy.
	 * @param valuesStride number of values to stride in the XdmfArray between each copy.
74
	 */
75
	void copyValues(const unsigned int startIndex, const boost::shared_ptr<const XdmfArray> values, const unsigned int valuesStartIndex= 0, const unsigned int numValues = 1, const unsigned int arrayStride = 1, const unsigned int valuesStride = 1);
76 77

	/**
78
	 * Copy values into this array.
79
	 *
80 81
	 * @param startIndex the index in this XdmfArray to begin insertion.
	 * @param valuesPointer a pointer to the values to copy into this XdmfArray.
82
	 * @param numValues the number of values to copy into this array.
83
	 * @param arrayStride number of values to stride in this XdmfArray between each copy.
84 85
	 * @param valuesStride number of values to stride in the pointer between each copy.
	 */
86
	template<typename T>
87
	void copyValues(const unsigned int startIndex, const T * const valuesPointer, const unsigned int numValues = 1, const unsigned int arrayStride = 1, const unsigned int valuesStride = 1);
88 89

	/**
90
	 * Remove all values from this array.
91
	 */
92
	void clear();
93

94 95 96 97 98
	/**
	 * Remove a value from this array.
	 */
	void erase(const unsigned int index);

99 100
	/**
	 * Get the capacity of this array (the number of values this array can store without reallocation).
101 102
	 *
	 * @return the capacity of this array.
103 104 105
	 */
	unsigned int getCapacity() const;

106 107
	std::map<std::string, std::string> getItemProperties() const;

108 109
	std::string getItemTag() const;

110 111 112 113 114 115 116 117 118 119 120 121
	/**
	 * Get the hdf5 controller attached to this XdmfArray.
	 *
	 * @return the hdf5 controller attached to this XdmfArray.
	 */
	boost::shared_ptr<XdmfHDF5Controller> getHDF5Controller();

	/**
	 * Get the hdf5 controller attached to this XdmfArray (const version).
	 *
	 * @return the hdf5 controller attached to this XdmfArray.
	 */
122
	boost::shared_ptr<const XdmfHDF5Controller> getHDF5Controller() const;
123

124 125 126 127 128 129 130
	/**
	 * Get the name of the array.
	 *
	 * @return a string containing the name of the array.
	 */
	std::string getName() const;

Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
131 132 133
	/**
	 * Get the number of values stored in this array.
	 *
134
	 * @return the number of values stored in this array.
Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
135
	 */
136
	unsigned int getSize() const;
Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
137

138
	/**
139 140 141 142 143
	 * Get the data type of this array.
	 *
	 * @return a string containing the Xdmf data type for the array, this is one of
	 *      Char, Short, Int, Float, UChar, UShort, UInt.
	 */
144
	boost::shared_ptr<const XdmfArrayType> getType() const;
145

146 147 148 149 150 151 152 153
	/**
	 * Get a copy of a single value stored in this array.
	 *
	 * @return the requested value.
	 */
	template <typename T>
	T getValueCopy(const unsigned int index) const;

Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
154
	/**
155
	 * Get a smart pointer to the values stored in this array.
Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
156
	 *
157
	 * @return a smart pointer to the internal vector of values stored in this array.
Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
158
	 */
159
	template <typename T>
160
	boost::shared_ptr<std::vector<T> > getValues();
Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
161

162 163 164 165 166 167 168 169 170 171
	/**
	 * Get a copy of the values stored in this array
	 *
	 * @param startIndex the index in this XdmfArray to begin copying from.
	 * @param valuesPointer a pointer to an array to copy into.
	 * @param numValues the number of values to copy.
	 * @param arrayStride number of values to stride in this XdmfArray between each copy.
	 * @param valuesStride number of values to stride in the pointer between each copy.
	 */
	template <typename T>
172
	void getValuesCopy(const unsigned int startIndex, T * const valuesPointer, const unsigned int numValues = 1, const unsigned int arrayStride = 1, const unsigned int valuesStride = 1) const;
173

174 175 176 177 178 179 180
	/**
	 * Get a pointer to the values stored in this array.
	 *
	 * @return a void pointer to the first value stored in this array.
	 */
	void * getValuesPointer();

Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
181
	/**
182
	 * Get a pointer to the values stored in this array (const version).
Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
183 184 185
	 *
	 * @return a void pointer to the first value stored in this array.
	 */
186
	const void * getValuesPointer() const;
Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
187

188 189 190 191 192
	/**
	 * Get the values stored in this array as a string.
	 *
	 * @return a string containing the contents of the array.
	 */
193
	std::string getValuesString() const;
194

195 196
	/**
	 * Initializes the array to contain an empty container of a particular type.
197 198
	 *
	 * @return a smart pointer to the internal vector of values initialized in this array.
199 200
	 */
	template <typename T>
201
	boost::shared_ptr<std::vector<T> > initialize();
202

203 204 205 206 207
	/**
	 * Initializes the array to contain an empty container of a particular XdmfArrayType.
	 */
	void initialize(const boost::shared_ptr<const XdmfArrayType> arrayType);

208 209 210
	/**
	 * Returns whether the array is initialized (contains values in memory).
	 */
211
	bool isInitialized() const;
212

213 214 215 216
	/**
	 * Copy a value to the back of this array
	 */
	template <typename T>
217
	void pushBack(const T & value);
218

219 220 221 222 223
	/**
	 * Read data from disk into memory.
	 */
	void read();

224
	/**
225
	 * Release all data currently held in memory.
226
	 */
227
	void release();
228

229 230 231 232 233 234 235
	/**
	 * Set the capacity of the XdmfArray to at least size.
	 *
	 * @param size the capacity to set this XdmfArray to.
	 */
	void reserve(const unsigned int size);

236
	/**
237
	 * Resizes the XdmfArray to contain numValues.  If numValues is larger than the current size, append values to the end equal
238 239 240
	 * to val.  If numValues is less than the current size, values at indices larger than numValues are removed.
	 *
	 * @param numValues the number of values to resize this array to.
241
	 * @param value the number to initialize newly created values to, if needed.
242 243
	 */
	template<typename T>
244
	void resize(const unsigned int numValues, const T & value = 0);
245

246 247 248 249 250
	/**
	 * Attach an hdf5 controller to this XdmfArray.
	 *
	 * @param hdf5Controller the hdf5 controller to attach to this XdmfArray.
	 */
251
	void setHDF5Controller(const boost::shared_ptr<XdmfHDF5Controller> hdf5Controller);
252

253 254 255 256 257 258 259
	/**
	 * Set the name of the array.
	 *
	 * @param name a string containing the name to set.
	 */
	void setName(const std::string & name);

260 261 262 263 264 265 266 267 268 269 270 271 272 273 274
	/**
	 * Sets the values of this array to the values stored in the arrayPointer array.  No copy is made.  Modifications to the array are
	 * not permitted through the XdmfArray API.  Any calls through the XdmfArray API to modify the array (i.e. any non-const function)
	 * will result in the array being copied into internal storage.  The internal copy is then modified.
	 * This prevents situations where a realloc of the pointer could cause other references to become invalid.
	 * The caller of this method can continue to modify the values stored in arrayPointer on its own.
	 * This function is meant for applications that have their own array data structures that merely use Xdmf to output the data,
	 * an operation that should not require a copy.  Other applications that use Xdmf for in memory data storage should avoid
	 * this function.
	 *
	 * @param arrayPointer a pointer to an array to store in this XdmfArray.
	 * @param numValues the number of values in the array.
	 * @param transferOwnership whether to transfer responsibility for deletion of the array to XdmfArray.
	 */
	template<typename T>
275
	void setValues(const T * const arrayPointer, const unsigned int numValues, const bool transferOwnership = 0);
276

277 278 279 280 281
	/**
	 * Sets the values of this array to the values stored in the vector.  No copy is made.  The caller of this method retains
	 * ownership of the data and must ensure that the array is still valid for the entire time Xdmf needs it.
	 *
	 * @param array a vector to store in this array.
282
	 * @param transferOwnership whether to transfer responsibility for deletion of the array to XdmfArray.
283 284
	 */
	template<typename T>
285
	void setValues(std::vector<T> & array, const bool transferOwnership = 0);
286

Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
287
	/**
288 289
	 * Sets the values of this array to the values stored in the vector.  No copy is made.  This array shares ownership with
	 * other references to the smart pointer.
Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
290
	 *
291
	 * @param array a smart pointer to a vector to store in this array.
Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
292
	 */
293
	template<typename T>
294
	void setValues(const boost::shared_ptr<std::vector<T> > array);
Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
295

296 297 298 299 300 301 302 303 304 305 306 307 308 309 310
	/**
	 * Exchange the contents of the vector with the contents of this XdmfArray.  No copy is made.  The internal arrays are swapped.
	 *
	 * @param array a vector to exchange values with.
	 * @return bool whether the swap was successful.
	 */
	template<typename T>
	bool swap(std::vector<T> & array);

	/**
	 * Exchange the contents of the vector with the contents of this XdmfArray.  No copy is made.  The internal arrays are swapped.
	 *
	 * @param array a smart pointer to a vector to exchange values with.
	 */
	template<typename T>
311
	bool swap(const boost::shared_ptr<std::vector<T> > array);
312 313 314 315 316 317 318

	/**
	 * Exchange the contents of an XdmfArray with the contents of this XdmfArray.  No copy is made.  The internal arrays are swapped.
	 *
	 * @param array a smart pointer to a vector to exchange values with.
	 * @return bool whether the swap was successful.
	 */
319
	void swap(const boost::shared_ptr<XdmfArray> array);
320

Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
321 322 323
protected:

	XdmfArray();
324
	virtual void populateItem(const std::map<std::string, std::string> & itemProperties, std::vector<boost::shared_ptr<XdmfItem> > & childItems);
Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
325 326 327

private:

328 329 330
	XdmfArray(const XdmfArray & array);  // Not implemented.
	void operator=(const XdmfArray & array);  // Not implemented.

331 332 333 334
	// Variant Visitor Operations
	class Clear;
	class CopyArrayValues;

335
	template <typename T>
336 337
	class CopyValues;

338
	class Erase;
339
	class GetCapacity;
340 341 342
	class GetHDF5Type;
	class GetSize;
	class GetType;
343

344
	template <typename T>
345 346
	class GetValuesCopy;

347 348
	class GetValuesPointer;
	class GetValuesString;
349
	class InternalizeArrayPointer;
350
	class NewArray;
351 352 353 354

	template <typename T>
	class PushBack;

355
	class Reserve;
356

357
	template <typename T>
358 359
	class Resize;

360 361
	struct NullDeleter;

362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379
	/**
	 * After setValues(const T * const array) is called, XdmfArray stores a pointer that is not allowed to be modified through
	 * the XdmfArray API.  If the user desires to modify the contents of the pointer, they must do so without calling any
	 * non-const functions of XdmfArray.  If they do call non-const functions of XdmfArray, we try to accommodate by copying
	 * the array pointer into internal data structures.
	 */
	void internalizeArrayPointer();

	/**
	 * Release references to internal data.
	 */
	void releaseArray();

	/**
	 * Release references to held array pointer internal data;
	 */
	void releaseArrayPointer();

380 381 382 383 384 385 386 387 388 389 390
	typedef boost::variant<
		boost::shared_ptr<std::vector<char> >,
		boost::shared_ptr<std::vector<short> >,
		boost::shared_ptr<std::vector<int> >,
		boost::shared_ptr<std::vector<long> >,
		boost::shared_ptr<std::vector<float> >,
		boost::shared_ptr<std::vector<double> >,
		boost::shared_ptr<std::vector<unsigned char> >,
		boost::shared_ptr<std::vector<unsigned short> >,
		boost::shared_ptr<std::vector<unsigned int> > > ArrayVariant;

391 392 393 394 395 396 397 398 399 400
	typedef boost::variant<
		boost::shared_array<const char>,
		boost::shared_array<const short>,
		boost::shared_array<const int>,
		boost::shared_array<const long>,
		boost::shared_array<const float>,
		boost::shared_array<const double>,
		boost::shared_array<const unsigned char>,
		boost::shared_array<const unsigned short>,
		boost::shared_array<const unsigned int> > ArrayPointerVariant;
401

402
	ArrayVariant mArray;
403
	ArrayPointerVariant mArrayPointer;
404
	unsigned int mArrayPointerNumValues;
405 406
	bool mHaveArray;
	bool mHaveArrayPointer;
407
	boost::shared_ptr<XdmfHDF5Controller> mHDF5Controller;
408
	std::string mName;
409
	unsigned int mTmpReserveSize;
Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
410 411
};

412 413
#include "XdmfArray.tpp"

Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
414
#endif /* XDMFARRAY_HPP_ */