casacore
StIndArray.h
Go to the documentation of this file.
1//# StIndArray.h: Read/write indirect arrays
2//# Copyright (C) 1994,1995,1996,1997,1999,2001
3//# Associated Universities, Inc. Washington DC, USA.
4//#
5//# This library is free software; you can redistribute it and/or modify it
6//# under the terms of the GNU Library General Public License as published by
7//# the Free Software Foundation; either version 2 of the License, or (at your
8//# option) any later version.
9//#
10//# This library is distributed in the hope that it will be useful, but WITHOUT
11//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13//# License for more details.
14//#
15//# You should have received a copy of the GNU Library General Public License
16//# along with this library; if not, write to the Free Software Foundation,
17//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18//#
19//# Correspondence concerning AIPS++ should be addressed as follows:
20//# Internet email: aips2-request@nrao.edu.
21//# Postal address: AIPS++ Project Office
22//# National Radio Astronomy Observatory
23//# 520 Edgemont Road
24//# Charlottesville, VA 22903-2475 USA
25//#
26//# $Id$
27
28#ifndef TABLES_STINDARRAY_H
29#define TABLES_STINDARRAY_H
30
31//# Includes
32#include <casacore/casa/aips.h>
33#include <casacore/tables/DataMan/StArrayFile.h>
34#include <casacore/casa/Utilities/DataType.h>
35#include <casacore/casa/Arrays/ArrayFwd.h>
36#include <casacore/casa/Arrays/IPosition.h>
37#include <casacore/casa/BasicSL/Complex.h>
38
39namespace casacore { //# NAMESPACE CASACORE - BEGIN
40
41//# Forward Declarations
42class Slicer;
43class ArrayBase;
44
45// <summary>
46// Read/write indirect arrays
47// </summary>
48
49// <use visibility=local>
50
51// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
52// </reviewed>
53
54// <prerequisite>
55//# Classes you should understand before using this one.
56// <li> StManArrayFile
57// </prerequisite>
58
59// <etymology>
60// StIndArray stores indirect arrays on behalf of a storage manager.
61// </etymology>
62
63// <synopsis>
64// StIndArray is a helper class for accessing indirect table arrays.
65// It is the interface between a storage manager like StManAipsIO
66// (in particular its indirect array column class
67// <linkto class="StManColumnIndArrayAipsIO:description">
68// StManColumnIndArrayAipsIO</linkto>)
69// and the data storage class
70// <linkto class="StManArrayFile:description">StManArrayFile</linkto>
71// which represents the file holding the shapes and data of the arrays.
72// This file holds the data in canonical format.
73//
74// StIndArray holds information about an array in the file.
75// <ol>
76// <li> Offset of the array in the file. This points to the array shape.
77// This is stored by storage managers and serves as the mapping between
78// row number and array.
79// <li> Array data offset, i.e. the length of the shape in the file.
80// Because the data is stored in canonical format, the length of the
81// shape in the file is not directly known but has to be supplied this way.
82// <li> The actual shape of the array
83// </ol>
84// The storage manager creates an StIndArray object for each row.
85// When an array is accessed for the first time,
86// the array data offset and the shape will be filled in by StIndArray.
87// In this way it serves as a cache for the array shape.
88//
89// StIndArray implements all necessary functions to get/put an array or
90// an array slice from/into file supplied by the given StManArrayFile object.
91// The StManArrayFile object itself has to be created by the storage manager
92// and given to the StIndArray functions.
93// </synopsis>
94
95// <motivation>
96// This helper class makes it possible to share equal functionality
97// between various storage managers handling indirect arrays.
98// At the moment it is used by the StManAipsIO, IncrementalStMan, and
99// StandardStMan storage managers, but it is not limited to them. It can
100// equally well be used by any other storage manager storing (indirect) arrays
101// via an StManArrayFile object.
102// </motivation>
103
104// <example>
105// Note that the following example is not really useful.
106// StIndArray is an internal class and should not be used by a casual user.
107// The example may however give a bit of insight.
108// <srcblock>
109// Array<Float> array(...);
110// // Create an StManArrayFile object to hold the arrays.
111// StManArrayFile stmanFile ("some.name", ByteIO::New);
112// // Create a still empty StIndArray object for an array.
113// StIndArray arrayRef(0);
114// // Define the shape and allocate a Float array.
115// // Put the array data.
116// arrayRef.setShape (stmanFile, TpFloat, array.shape());
117// arrayRef.putArrayfloatV (stmanFile, &array);
118// // Get the file offset of the array (for later use).
119// Int64 offset = arrayRef.fileOffset();
120// // Create an StIndArray object to read the array back.
121// // Of course, the same object could have been used for that purpose,
122// // but this shows how to create one for an existing file.
123// StIndArray arrayRef2(offset);
124// arrayRef2.getShape (stmanFile); // read shape
125// Array<float> array2(arrayRef2.shape()); // create with correct size
126// arrayRef2.getArrayfloatV (stmanFile, &array2);
127// </srcblock>
128// </example>
129
130// <todo asof="$DATE:$">
131//# A List of bugs, limitations, extensions or planned refinements.
132// <li> Reuse file storage when an array gets reshaped.
133// This could be done if the array does not grow.
134// It also requires a change in StManArrayFile.
135// <li> Be smarter when accessing slices by not accessing a vector
136// at a time, but by determining and accessing the largest
137// possible consecutive area.
138// </todo>
139
140
142{
143public:
144 // Construct the object with the given file offset.
145 // A zero file offset means that no array has been defined yet.
146 // That may be filled in later by setShape.
148
149 // Copy constructor.
151
152 // Assignment.
154
156
157 // Get the shape.
158 const IPosition& shape() const
159 {return shape_p;}
160
161 // Get the file offset.
163 {return fileOffset_p;}
164
165 // Set the shape and allocate the array in the file.
166 // This will define the array and fill in the file offset.
167 // If the shape is already defined and does not change,
168 // nothing is done and a False value is returned.
169 // If the shape changes, the old file space is lost.
170 Bool setShape (StManArrayFile&, int dataType, const IPosition& shape);
171
172 // Read the shape if not read yet.
174
175 // Get the reference count.
177
178 // Increment the reference count.
180
181 // Decrement the reference count.
183
184 // Copy the data from another array.
185 // An exception if thrown if the shapes do not match.
186 void copyData (StManArrayFile& ios, int dataType, const StIndArray& other);
187
188 // Get an array value from the file at the offset held in this object.
189 // The buffer pointed to by dataPtr has to have the correct length
190 // (which is guaranteed by the ArrayColumn get function).
192 DataType dtype);
193
194 // Put an array value into the file at the offset held in this object.
195 // The buffer pointed to by dataPtr has to have the correct length
196 // (which is guaranteed by the ArrayColumn put function).
197 void putArrayV (StManArrayFile& ios, const ArrayBase& arr,
198 DataType dtype);
199
200 // Get a section of the array from the file at the offset held in
201 // this object.
202 // The buffer pointed to by dataPtr has to have the correct length
203 // (which is guaranteed by the ArrayColumn getSlice function).
205 ArrayBase& dataPtr, DataType dtype);
206
207 // Put a section of the array into the file at the offset held in
208 // this object.
209 // The buffer pointed to by dataPtr has to have the correct length
210 // (which is guaranteed by the ArrayColumn putSlice function).
212 const ArrayBase& dataPtr, DataType dtype);
213
214private:
215 Int64 fileOffset_p; //# offset of shape in StManArrayFile
216 uInt arrOffset_p; //# extra offset to the array
217 //# 0 = arrOffset and shape not known yet
218 IPosition shape_p; //# shape of the array
219
220 // Get sliced data, i.e. get a section of an array.
221 // This function is used by getSliceXXXV to have common functionality
222 // in one function. It calls the given getVec function for each
223 // chunk of data. In this way the bulk of type-independent code
224 // is concentrated in getSliceData resulting in small
225 // type-dependent functions.
226 void getSliceData (StManArrayFile&, const Slicer& ns, void* value,
227 const IPosition& userArrayShape,
228 void (*getVec) (StManArrayFile&,
230 void* dataPtr));
231
232 // Get a (type-dependent) vector part of a slice.
233 // This function is called for each chunk by putSliceData.
234 // <group>
236 Int64 fileOffset, uInt64 arrayStart,
237 uInt64 length, uInt64 increment,
238 uInt64 valueIndex, void* value);
240 Int64 fileOffset, uInt64 arrayStart,
241 uInt64 length, uInt64 increment,
242 uInt64 valueIndex, void* value);
244 Int64 fileOffset, uInt64 arrayStart,
245 uInt64 length, uInt64 increment,
246 uInt64 valueIndex, void* value);
248 Int64 fileOffset, uInt64 arrayStart,
249 uInt64 length, uInt64 increment,
250 uInt64 valueIndex, void* value);
252 Int64 fileOffset, uInt64 arrayStart,
253 uInt64 length, uInt64 increment,
254 uInt64 valueIndex, void* value);
256 Int64 fileOffset, uInt64 arrayStart,
257 uInt64 length, uInt64 increment,
258 uInt64 valueIndex, void* value);
260 Int64 fileOffset, uInt64 arrayStart,
261 uInt64 length, uInt64 increment,
262 uInt64 valueIndex, void* value);
264 Int64 fileOffset, uInt64 arrayStart,
265 uInt64 length, uInt64 increment,
266 uInt64 valueIndex, void* value);
268 Int64 fileOffset, uInt64 arrayStart,
269 uInt64 length, uInt64 increment,
270 uInt64 valueIndex, void* value);
272 Int64 fileOffset, uInt64 arrayStart,
273 uInt64 length, uInt64 increment,
274 uInt64 valueIndex, void* value);
276 Int64 fileOffset, uInt64 arrayStart,
277 uInt64 length, uInt64 increment,
278 uInt64 valueIndex, void* value);
280 Int64 fileOffset, uInt64 arrayStart,
281 uInt64 length, uInt64 increment,
282 uInt64 valueIndex, void* value);
283 // </group>
284
285 // Put sliced data, i.e. put a section of an array.
286 // This function is used by putSlice to have common functionality
287 // in one function. It calls the given in putVec function for
288 // chunk of data. In this way the bulk of type-independent code
289 // is concentrated in putSliceData resulting in small
290 // type-dependent functions.
291 void putSliceData (StManArrayFile&, const Slicer& ns, const void* value,
292 const IPosition& userArrayShape,
293 void (*putVec) (StManArrayFile&,
295 const void* dataPtr));
296
297 // Put a (type-dependent) vector part of a slice.
298 // This function is called for each chunk by putSliceData.
299 // <group>
301 Int64 fileOffset, uInt64 arrayStart,
302 uInt64 length, uInt64 increment,
303 uInt64 valueIndex, const void* value);
305 Int64 fileOffset, uInt64 arrayStart,
306 uInt64 length, uInt64 increment,
307 uInt64 valueIndex, const void* value);
309 Int64 fileOffset, uInt64 arrayStart,
310 uInt64 length, uInt64 increment,
311 uInt64 valueIndex, const void* value);
313 Int64 fileOffset, uInt64 arrayStart,
314 uInt64 length, uInt64 increment,
315 uInt64 valueIndex, const void* value);
317 Int64 fileOffset, uInt64 arrayStart,
318 uInt64 length, uInt64 increment,
319 uInt64 valueIndex, const void* value);
321 Int64 fileOffset, uInt64 arrayStart,
322 uInt64 length, uInt64 increment,
323 uInt64 valueIndex, const void* value);
325 Int64 fileOffset, uInt64 arrayStart,
326 uInt64 length, uInt64 increment,
327 uInt64 valueIndex, const void* value);
329 Int64 fileOffset, uInt64 arrayStart,
330 uInt64 length, uInt64 increment,
331 uInt64 valueIndex, const void* value);
333 Int64 fileOffset, uInt64 arrayStart,
334 uInt64 length, uInt64 increment,
335 uInt64 valueIndex, const void* value);
337 Int64 fileOffset, uInt64 arrayStart,
338 uInt64 length, uInt64 increment,
339 uInt64 valueIndex, const void* value);
341 Int64 fileOffset, uInt64 arrayStart,
342 uInt64 length, uInt64 increment,
343 uInt64 valueIndex, const void* value);
345 Int64 fileOffset, uInt64 arrayStart,
346 uInt64 length, uInt64 increment,
347 uInt64 valueIndex, const void* value);
348 // </group>
349
350 // Throw an exception if the shape of the given array and the table
351 // array (slice) are not equal.
352 void checkShape (const IPosition& userArrayShape,
353 const IPosition& tableArrayShape) const;
354};
355
356
357
358
359} //# NAMESPACE CASACORE - END
360
361#endif
Non-templated base class for templated Array class.
Definition: ArrayBase.h:73
StIndArray(Int64 fileOffset)
Construct the object with the given file offset.
static void putVecuCharV(StManArrayFile &, Int64 fileOffset, uInt64 arrayStart, uInt64 length, uInt64 increment, uInt64 valueIndex, const void *value)
void putSliceV(StManArrayFile &, const Slicer &, const ArrayBase &dataPtr, DataType dtype)
Put a section of the array into the file at the offset held in this object.
void getSliceV(StManArrayFile &, const Slicer &, ArrayBase &dataPtr, DataType dtype)
Get a section of the array from the file at the offset held in this object.
void checkShape(const IPosition &userArrayShape, const IPosition &tableArrayShape) const
Throw an exception if the shape of the given array and the table array (slice) are not equal.
static void getVecBoolV(StManArrayFile &, Int64 fileOffset, uInt64 arrayStart, uInt64 length, uInt64 increment, uInt64 valueIndex, void *value)
Get a (type-dependent) vector part of a slice.
static void putVecIntV(StManArrayFile &, Int64 fileOffset, uInt64 arrayStart, uInt64 length, uInt64 increment, uInt64 valueIndex, const void *value)
uInt refCount(StManArrayFile &ios)
Get the reference count.
static void putVecfloatV(StManArrayFile &, Int64 fileOffset, uInt64 arrayStart, uInt64 length, uInt64 increment, uInt64 valueIndex, const void *value)
static void putVecInt64V(StManArrayFile &, Int64 fileOffset, uInt64 arrayStart, uInt64 length, uInt64 increment, uInt64 valueIndex, const void *value)
static void getVecComplexV(StManArrayFile &, Int64 fileOffset, uInt64 arrayStart, uInt64 length, uInt64 increment, uInt64 valueIndex, void *value)
void putArrayV(StManArrayFile &ios, const ArrayBase &arr, DataType dtype)
Put an array value into the file at the offset held in this object.
static void getVecuShortV(StManArrayFile &, Int64 fileOffset, uInt64 arrayStart, uInt64 length, uInt64 increment, uInt64 valueIndex, void *value)
static void getVecDComplexV(StManArrayFile &, Int64 fileOffset, uInt64 arrayStart, uInt64 length, uInt64 increment, uInt64 valueIndex, void *value)
static void getVecdoubleV(StManArrayFile &, Int64 fileOffset, uInt64 arrayStart, uInt64 length, uInt64 increment, uInt64 valueIndex, void *value)
static void putVecComplexV(StManArrayFile &, Int64 fileOffset, uInt64 arrayStart, uInt64 length, uInt64 increment, uInt64 valueIndex, const void *value)
static void putVecBoolV(StManArrayFile &, Int64 fileOffset, uInt64 arrayStart, uInt64 length, uInt64 increment, uInt64 valueIndex, const void *value)
Put a (type-dependent) vector part of a slice.
static void putVecStringV(StManArrayFile &, Int64 fileOffset, uInt64 arrayStart, uInt64 length, uInt64 increment, uInt64 valueIndex, const void *value)
StIndArray(const StIndArray &)
Copy constructor.
static void getVecStringV(StManArrayFile &, Int64 fileOffset, uInt64 arrayStart, uInt64 length, uInt64 increment, uInt64 valueIndex, void *value)
static void getVecInt64V(StManArrayFile &, Int64 fileOffset, uInt64 arrayStart, uInt64 length, uInt64 increment, uInt64 valueIndex, void *value)
void getShape(StManArrayFile &ios)
Read the shape if not read yet.
void decrementRefCount(StManArrayFile &ios)
Decrement the reference count.
const IPosition & shape() const
Get the shape.
Definition: StIndArray.h:158
static void getVecuIntV(StManArrayFile &, Int64 fileOffset, uInt64 arrayStart, uInt64 length, uInt64 increment, uInt64 valueIndex, void *value)
void getSliceData(StManArrayFile &, const Slicer &ns, void *value, const IPosition &userArrayShape, void(*getVec)(StManArrayFile &, Int64, uInt64, uInt64, uInt64, uInt64, void *dataPtr))
Get sliced data, i.e.
static void getVecfloatV(StManArrayFile &, Int64 fileOffset, uInt64 arrayStart, uInt64 length, uInt64 increment, uInt64 valueIndex, void *value)
static void putVecdoubleV(StManArrayFile &, Int64 fileOffset, uInt64 arrayStart, uInt64 length, uInt64 increment, uInt64 valueIndex, const void *value)
void getArrayV(StManArrayFile &ios, ArrayBase &arr, DataType dtype)
Get an array value from the file at the offset held in this object.
static void putVecuShortV(StManArrayFile &, Int64 fileOffset, uInt64 arrayStart, uInt64 length, uInt64 increment, uInt64 valueIndex, const void *value)
void putSliceData(StManArrayFile &, const Slicer &ns, const void *value, const IPosition &userArrayShape, void(*putVec)(StManArrayFile &, Int64, uInt64, uInt64, uInt64, uInt64, const void *dataPtr))
Put sliced data, i.e.
void copyData(StManArrayFile &ios, int dataType, const StIndArray &other)
Copy the data from another array.
static void getVecShortV(StManArrayFile &, Int64 fileOffset, uInt64 arrayStart, uInt64 length, uInt64 increment, uInt64 valueIndex, void *value)
static void getVecuCharV(StManArrayFile &, Int64 fileOffset, uInt64 arrayStart, uInt64 length, uInt64 increment, uInt64 valueIndex, void *value)
static void putVecuIntV(StManArrayFile &, Int64 fileOffset, uInt64 arrayStart, uInt64 length, uInt64 increment, uInt64 valueIndex, const void *value)
void incrementRefCount(StManArrayFile &ios)
Increment the reference count.
static void putVecShortV(StManArrayFile &, Int64 fileOffset, uInt64 arrayStart, uInt64 length, uInt64 increment, uInt64 valueIndex, const void *value)
StIndArray & operator=(const StIndArray &)
Assignment.
static void getVecIntV(StManArrayFile &, Int64 fileOffset, uInt64 arrayStart, uInt64 length, uInt64 increment, uInt64 valueIndex, void *value)
Bool setShape(StManArrayFile &, int dataType, const IPosition &shape)
Set the shape and allocate the array in the file.
static void putVecDComplexV(StManArrayFile &, Int64 fileOffset, uInt64 arrayStart, uInt64 length, uInt64 increment, uInt64 valueIndex, const void *value)
Int64 fileOffset() const
Get the file offset.
Definition: StIndArray.h:162
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
LatticeExprNode length(const LatticeExprNode &expr, const LatticeExprNode &axis)
2-argument function to get the length of an axis.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
unsigned long long uInt64
Definition: aipsxtype.h:39