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

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

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
/**
 * @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
 * 	getCopyValues
 *
 * 	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:
 * 	Char
 * 	Short
 * 	Int
 * 	Long
 * 	Float
 * 	Double
 * 	Unsigned Char
 * 	Unsigned Short
 * 	Unsigned Int
 */
Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
46
47
48
49
50
class XdmfArray : public XdmfItem {
public:

	XdmfNewMacro(XdmfArray);

51
	/**
52
	 * Copy values from an XdmfArray into this array.
53
	 *
54
55
	 * @param startIndex the index in this array to begin insertion.
	 * @param values a shared pointer to an XdmfArray to copy into this array.
56
	 * @param valuesStartIndex the index in the XdmfArray to begin copying.
57
58
59
	 * @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.
60
	 */
61
	void copyValues(const int startIndex, const boost::shared_ptr<const XdmfArray> values, const int valuesStartIndex= 0, const int numValues = 1, const int arrayStride = 1, const int valuesStride = 1);
62
63
64
65
66
67
68
69
70
71

	/**
	 * Copy values from an array into this array.
	 *
	 * @param startIndex the index in this array to begin insertion.
	 * @param valuesPointer a pointer to the values to copy into this array.
	 * @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 pointer between each copy.
	 */
72
	template<typename T>
73
	void copyValues(const int startIndex, const T * const valuesPointer, const int numValues = 1, const int arrayStride = 1, const int valuesStride = 1);
74
75

	/**
76
	 * Remove all values from this array
77
78
	 */
	virtual void clear();
79

Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
80
81
82
83
84
85
86
87
88
89
	/**
	 * Get the hdf5 data type of this array.
	 *
	 * @return a hid_t value containing the hdf5 data type for the array.
	 */
	virtual hid_t getHDF5Type() const;

	/**
	 * Get the precision, in bytes, of the data type of this array.
	 *
90
	 * @return an int containing the precision, in bytes, of the data type of this array.
Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
91
92
93
94
95
96
	 */
	virtual int getPrecision() const;

	/**
	 * Get the number of values stored in this array.
	 *
97
	 * @return an int containing the number of values stored in this array.
Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
98
99
100
	 */
	virtual int getSize() const;

101
	/**
102
103
104
105
106
	 * 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.
	 */
107
108
	virtual std::string getType() const;

Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
109
	/**
110
	 * 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
111
	 *
112
	 * @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
113
	 */
114
	template <typename T>
115
	boost::shared_ptr<std::vector<T> > getValues();
Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
116
117

	/**
118
	 * Get a smart 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
119
	 *
120
	 * @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
121
	 */
122
123
	//template <typename T>
	//const boost::shared_ptr<const std::vector<T> > getValues() const;
Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
124
125

	/**
126
	 * Get a pointer to the values stored in this array.
Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
127
128
129
130
131
	 *
	 * @return a void pointer to the first value stored in this array.
	 */
	virtual const void* const getValuesPointer() const;

132
133
134
135
136
137
138
	/**
	 * Get the values stored in this array as a string.
	 *
	 * @return a string containing the contents of the array.
	 */
	virtual std::string getValuesString() const;

139
140
	/**
	 * Initializes the array to contain an empty container of a particular type.
141
142
	 *
	 * @return a smart pointer to the internal vector of values initialized in this array.
143
144
	 */
	template <typename T>
145
	boost::shared_ptr<std::vector<T> > initialize();
146

147
148
	virtual std::string printSelf() const;

149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
	/**
	 * Releases all data held by this XdmfArray.
	 */
	void releaseData()
	{
		releaseArray();
		releaseArrayPointer();
	}

	/**
	 * 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>
	void setValues(const T * const arrayPointer, const int numValues, const bool transferOwnership = 0);

175
176
177
178
179
	/**
	 * 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.
180
	 * @param transferOwnership whether to transfer responsibility for deletion of the array to XdmfArray.
181
182
	 */
	template<typename T>
183
	void setValues(std::vector<T> & array, const bool transferOwnership = 0);
184

Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
185
	/**
186
187
	 * 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
188
	 *
189
	 * @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
190
	 */
191
192
	template<typename T>
	void setValues(boost::shared_ptr<std::vector<T> > array);
Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
193

194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
	/**
	 * 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>
	bool swap(boost::shared_ptr<std::vector<T> > array);

	/**
	 * 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.
	 */
217
	void swap(boost::shared_ptr<XdmfArray> array);
218
219
220
221

	/**
	 *
	 */
Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
222
223
224
225
226
227
228
229
230
	virtual void write(boost::shared_ptr<XdmfVisitor>) const;

protected:

	XdmfArray();
	virtual ~XdmfArray();

private:

231
232
233
234
235
236
237
238
239
240
241
242
243
	// Variant Visitor Operations
	class Clear;
	class CopyArrayValues;

	template<typename T>
	class CopyValues;

	class GetHDF5Type;
	class GetPrecision;
	class GetSize;
	class GetType;
	class GetValuesPointer;
	class GetValuesString;
244
	class InternalizeArrayPointer;
245
246
247
248
	class NewArray;

	struct NullDeleter;

249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
	/**
	 * 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();

267
268
269
270
271
272
273
274
275
276
277
	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;

278
279
280
281
282
283
284
285
286
287
288
	  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;

289
	ArrayVariant mArray;
290
291
292
293
	ArrayPointerVariant mArrayPointer;
	int mArrayPointerNumValues;
	bool mHaveArray;
	bool mHaveArrayPointer;
Ken Leiter (Civ ARL/CISD) kleiter's avatar
ENH:  
Ken Leiter (Civ ARL/CISD) kleiter committed
294
295
};

296
297
#include "XdmfArray.tpp"

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