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 
39 namespace casacore { //# NAMESPACE CASACORE - BEGIN
40 
41 //# Forward Declarations
42 class Slicer;
43 class 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 {
143 public:
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 
214 private:
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);
251  static void getVecIntV (StManArrayFile&,
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);
316  static void putVecIntV (StManArrayFile&,
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.
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.
const IPosition & shape() const
Get the shape.
Definition: StIndArray.h:158
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)
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.
StIndArray & operator=(const StIndArray &)
Assignment.
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