casacore
ArrayColumnBase.h
Go to the documentation of this file.
1//# ArrayColumnBase.h: base class for access to an array table column
2//# Copyright (C) 2013
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: ArrayColumn.h 21298 2012-12-07 14:53:03Z gervandiepen $
27
28#ifndef TABLES_ARRAYCOLUMNBASE_H
29#define TABLES_ARRAYCOLUMNBASE_H
30
31
32//# Includes
33#include <casacore/casa/aips.h>
34#include <casacore/tables/Tables/TableColumn.h>
35#include <casacore/casa/Arrays/Vector.h>
36
37namespace casacore { //# NAMESPACE CASACORE - BEGIN
38
39//# Forward Declarations
40class BaseSlicesFunctor;
41class RefRows;
42class ColumnSlicer;
43class IPosition;
44class Slice;
45class Slicer;
46class String;
47
48
49// <summary>
50// Read and write access to an array table column with arbitrary data type
51// </summary>
52
53// <use visibility=export>
54
55// <reviewed reviewer="dschieb" date="1994/08/10" tests="none">
56// </reviewed>
57
58// <prerequisite>
59// <li> Table
60// <li> TableColumn
61// </prerequisite>
62
63// <etymology>
64// ArrayColumn<T> gives read and write access to an column in a table
65// containing an array with data type T.
66// </etymology>
67
68// <synopsis>
69// ArrayColumnBase is the base class of the templated class ArrayColumn
70// which allows readonly access to a column containing arrays with an
71// arbitrary data type. It can handle direct as well as indirect arrays.
72//
73// All get and put functions are implemented in this base class as
74// non-templated functions. Type-specific operations are done by means
75// of virtual functions in the Array classes.
76// </synopsis>
77
78// <example>
79// See module <linkto module="Tables#open">Tables</linkto>.
80// </example>
81
82
84 {
85 public:
86 // The default constructor creates a null object, i.e. it
87 // does not reference a table column.
89
90 // Construct for the given column in the given table.
91 ArrayColumnBase (const Table&, const String& columnName);
92
93 // Construct from the given table column.
94 // This constructor is useful if first a table column was constructed,
95 // its type is determined and thereafter used to construct the
96 // correct column object.
98
99 // Copy constructor (reference semantics).
101
103
104 // Assignment uses reference semantics, thus works the same
105 // as function reference.
107
108 // Change the reference to another column.
109 // This is in fact an assignment operator with reference semantics.
110 // It removes the reference to the current column and creates
111 // a reference to the column referenced in the other object.
112 // It will handle null objects correctly.
114
115 // Get the #dimensions of an array in a particular cell.
116 // If the cell does not contain an array, 0 is returned.
117 // Use the function isDefined to test if the cell contains an array.
118 uInt ndim (rownr_t rownr) const
119 { TABLECOLUMNCHECKROW(rownr); return baseColPtr_p->ndim (rownr); }
120
121 // Get the shape of an array in a particular cell.
122 // If the cell does not contain an array, a 0-dim shape is returned.
123 // Use the function isDefined to test if the cell contains an array.
124 IPosition shape (rownr_t rownr) const
125 { TABLECOLUMNCHECKROW(rownr); return baseColPtr_p->shape (rownr); }
126
127 // Counterparts of the acbGet() functions below not checking shapes, etc.
128 // They are faster and can be used for performance reasons if one
129 // knows for sure that the arguments are correct.
130 // E.g., they are used internally in virtual column engines.
131 // <group>
132 void baseGet (rownr_t rownr, ArrayBase& array) const
133 { baseColPtr_p->getArray (rownr, array); }
134 void baseGetSlice (rownr_t rownr, const Slicer& arraySection,
135 ArrayBase& array) const
136 { baseColPtr_p->getSlice (rownr, arraySection, array); }
137 // </group>
138
139 // Get the array value in a particular cell (i.e. table row).
140 // The row numbers count from 0 until #rows-1.
141 void acbGet (rownr_t rownr, ArrayBase& array, Bool resize) const;
142
143 // Get a slice of an N-dimensional array in a particular cell
144 // (i.e. table row).
145 // The row numbers count from 0 until #rows-1.
146 // The dimensionality of the slice must match the dimensionality
147 // of the table array and the slice definition should not exceed
148 // the shape of the table array.
149 void acbGetSlice (rownr_t rownr, const Slicer& arraySection, ArrayBase& array,
150 Bool resize) const;
151
152 // Get an irregular slice of an N-dimensional array in a particular cell
153 // (i.e. table row) as given by the vectors of Slice objects.
154 // The outer vector represents the array axes.
155 // A missing or empty axis means the entire axis.
156 // The inner vector represents the slices to take for each axis.
157 // For example, to get slices from 2-dim arrays:
158 // <srcblock>
159 // Vector<Vector<Slice> > slices(2); // 2-dim
160 // slices[1].resize (3); // 3 slices in 2nd dim
161 // slices[1][0] = Slice(100,20);
162 // slices[1][1] = Slice(200,18);
163 // slices[1][2] = Slice(538,30,2);
164 // // Get data. Vector of first axis is empty, thus entire axis is read.
165 // Array<Complex> data = dataCol.getColumn (slices);
166 // </srcblock>
167 // If the column contains n-dim arrays, the resulting array is (n+1)-dim.
168 // with the last dimension representing the number of rows and the
169 // other dimensions representing the shape of the slice.
170 // The arrays in the column must have the same shape in all cells.
171 void acbGetSlice (rownr_t rownr,
172 const Vector<Vector<Slice> >& arraySlices,
173 ArrayBase& arr, Bool resize) const;
174
175 // Get the array of all values in a column.
176 // If the column contains n-dim arrays, the resulting array is (n+1)-dim
177 // with the last dimension representing the number of rows.
178 // The arrays in the column must have the same shape in all cells.
179 void acbGetColumn (ArrayBase& array, Bool resize) const;
180
181 // Get regular slices from all arrays in the column.
182 // If the column contains n-dim arrays, the resulting array is (n+1)-dim.
183 // with the last dimension representing the number of rows and the
184 // other dimensions representing the shape of the slice.
185 // The arrays in the column must have the same shape in all cells.
186 void acbGetColumn (const Slicer& arraySection, ArrayBase& array,
187 Bool resize) const;
188
189 // Get irregular slices from all arrays in the column as given by the
190 // vectors of Slice objects. The outer vector represents the array axes.
191 // A missing or empty axis means the entire axis.
192 // The inner vector represents the slices to take for each axis.
193 // For example, to get slices from 2-dim arrays:
194 // <srcblock>
195 // Vector<Vector<Slice> > slices(2); // 2-dim
196 // slices[1].resize (3); // 3 slices in 2nd dim
197 // slices[1][0] = Slice(100,20);
198 // slices[1][1] = Slice(200,18);
199 // slices[1][2] = Slice(538,30,2);
200 // // Get data. Vector of first axis is empty, thus entire axis is read.
201 // Array<Complex> data = dataCol.getColumn (slices);
202 // </srcblock>
203 // If the column contains n-dim arrays, the resulting array is (n+1)-dim.
204 // with the last dimension representing the number of rows and the
205 // other dimensions representing the shape of the slice.
206 // The arrays in the column must have the same shape in all cells.
207 void acbGetColumn (const Vector<Vector<Slice> >& arraySection,
209 Bool resize) const;
210
211 // Get the array of some values in a column.
212 // The Slicer object can be used to specify start, end (or length),
213 // and stride of the rows to get.
214 // If the column contains n-dim arrays, the resulting array is (n+1)-dim
215 // with the last dimension representing the number of rows in the slicer.
216 // The arrays in the column must have the same shape in all those cells.
217 void acbGetColumnRange (const Slicer& rowRange, ArrayBase& arr,
218 Bool resize) const;
219 void acbGetColumnCells (const RefRows& rownrs, ArrayBase& arr,
220 Bool resize) const;
221
222 // Get slices from some arrays in a column.
223 // The first Slicer object can be used to specify start, end (or length),
224 // and stride of the rows to get. The second Slicer object can be
225 // used to specify the slice to take from each array.
226 // If the column contains n-dim arrays, the resulting array is (n+1)-dim
227 // with the last dimension representing the number of rows in the slicer.
228 // The arrays in the column must have the same shape in all those cells.
229 // <group>
230 void acbGetColumnRange (const Slicer& rowRange,
231 const Slicer& arraySection, ArrayBase& arr,
232 Bool resize) const;
233 void acbGetColumnCells (const RefRows& rownrs,
234 const Slicer& arraySection, ArrayBase& arr,
235 Bool resize) const;
236 // </group>
237
238 // Get various slices from the given rows.
239 void acbGetColumnCells (const RefRows& rows,
240 const ColumnSlicer& columnSlicer,
241 ArrayBase& destination,
242 Bool resize) const;
243
244 // Set the shape of the array in the given row.
245 // Setting the shape is needed if the array is put in slices,
246 // otherwise the table system would not know the shape.
247 // <group>
248 void setShape (rownr_t rownr, const IPosition& shape);
249
250 // Try to store the array in a tiled way using the given tile shape.
251 void setShape (rownr_t rownr, const IPosition& shape,
252 const IPosition& tileShape);
253 // </group>
254
255 // Counterparts of the acbPut() functions below not checking shapes, etc.
256 // They are faster and can be used for performance reasons if one
257 // knows for sure that the arguments are correct.
258 // E.g., they are used internally in virtual column engines.
259 // <group>
260 void basePut (rownr_t rownr, const ArrayBase& array)
261 { baseColPtr_p->putArray (rownr, array); }
262 void basePutSlice (rownr_t rownr, const Slicer& arraySection,
263 const ArrayBase& array)
264 { baseColPtr_p->putSlice (rownr, arraySection, array); }
265 // </group>
266
267 // Put the array in a particular cell (i.e. table row).
268 // The row numbers count from 0 until #rows-1.
269 // If the shape of the table array in that cell has not already been
270 // defined, it will be defined implicitly.
271 void acbPut (rownr_t rownr, const ArrayBase& array);
272
273 // Put into a slice of an N-dimensional array in a particular cell.
274 // The row numbers count from 0 until #rows-1.
275 // The shape of the table array must have been defined.
276 // The dimensionality of the slice must match the dimensionality
277 // of the table array and the slice definition should not exceed
278 // the shape of the table array.
279 void acbPutSlice (rownr_t rownr, const Slicer& arraySection,
280 const ArrayBase& array);
281
282 void acbPutSlice (rownr_t rownr, const Vector<Vector<Slice> >& arraySlices,
283 const ArrayBase& arr);
284
285 // Put the array of all values in the column.
286 // If the column contains n-dim arrays, the source array must be (n+1)-dim
287 // with the last dimension representing the number of rows.
289
290 // Put into subsections of the table arrays in the entire column.
291 // If the column contains n-dim arrays, the source array is (n+1)-dim
292 // with the last dimension representing the number of rows and
293 // other dimensions representing the shape of the slice.
294 // The dimensionality of the slice must match the dimensionality
295 // of the table array, thus must be n-dim. Also the slice definition
296 // should not exceed the shape of the table arrays.
297 void acbPutColumn (const Slicer& arraySection, const ArrayBase& array);
298
299 void acbPutColumn (const Vector<Vector<Slice> >& arraySlices,
300 const ArrayBase& arr);
301
302 // Put the array of some values in the column.
303 // The Slicer object can be used to specify start, end (or length),
304 // and stride of the rows to put.
305 // If the column contains n-dim arrays, the source array must be (n+1)-dim
306 // with the last dimension representing the number of rows in the slicer.
307 // <group>
308 void acbPutColumnRange (const Slicer& rowRange, const ArrayBase& arr);
309 void acbPutColumnCells (const RefRows& rownrs, const ArrayBase& arr);
310 // </group>
311
312 // Put into subsection of the table arrays in some rows of the column.
313 // The first Slicer object can be used to specify start, end (or length),
314 // and stride of the rows to put. The second Slicer object can be
315 // used to specify the slice to take from each array.
316 // If the column contains n-dim arrays, the source array must be (n+1)-dim
317 // with the last dimension representing the number of rows in the slicer.
318 // <group>
319 void acbPutColumnRange (const Slicer& rowRange,
320 const Slicer& arraySection, const ArrayBase& arr);
321 void acbPutColumnCells (const RefRows& rownrs,
322 const Slicer& arraySection, const ArrayBase& arr);
323 // </group>
324
325 // Put various slices in the given rows.
326 // <group>
327 void acbPutColumnCells (const RefRows& rows,
328 const Vector<Vector<Slice> >& arraySlices,
329 const ArrayBase& source);
330 void acbPutColumnCells (const RefRows& rows,
331 const ColumnSlicer& columnSlicer,
332 const ArrayBase& source);
333 // </group>
334
335 // Put the same value in all cells of the column.
337
338 // Put the contents of that column into this one.
339 void acbPutColumn (const ArrayColumnBase& that);
340
341 // Adapt the shape of the array if possible. If the array is empty or
342 // if <src>resize=True</src>, the array is resized if needed.
343 // Otherwise checkShape is used to throw an exception if not conforming.
344 void adaptShape (const IPosition& shp,
345 ArrayBase& arr, Bool resize,
346 Int64 rownr, const String& where) const;
347
348 // Throw an exception if the array does not have the expected shape.
349 // However, False is returned if noSlicing and canChangeShape_p are True
350 // (meaning no slices are put and the shape of a full row can change).
351 // The column name is made part of the error message, as well as the rownr
352 // if it is not negative (meaning a put of a column).
353 Bool checkShape (const IPosition& expShape, const IPosition& arrShape,
354 Bool noSlicing, Int64 rownr, const String& where) const;
355
356 // A common function used by all functions that can get or put irregular
357 // array slices. The functor performs the get or put operation.
358 void handleSlices (const Vector<Vector<Slice> >& slices,
359 BaseSlicesFunctor& functor,
360 const Slicer& slicer,
361 const ArrayBase& array) const;
362 };
363
364
365
366
367// <synopsis>
368// ColumnSlicer is used in one of the ArrayColumn::getColumnCells functions.
369// That method takes a potentially complex/ selection of data out of a
370// column cell (e.g., multiple slices along each axis) and then puts them
371// into a selection of a destination array.
372// This is most easily represented as a set of source,destination slicers
373// where one is applied to the cell and the other to the destination array.
374// </synopsis>
376{
377public:
378
379 // Construct the object.
380 // It takes over the pointers to the Slicer objects and deletes them
381 // in the destructor.
382 // The shape parameter is the shape of the destination array excluding
383 // the row axis.
385 const Vector<Slicer*>& dataSlicers,
386 const Vector<Slicer*>& destinationSlicers);
387
388 // The destructor deletes all Slicer objects.
390
391 // Get the data slicers.
393 { return dataSlicers_p; }
394
395 // Get the desintation slicers.
397 { return destinationSlicers_p; }
398
399 // Get the shape.
400 const IPosition& shape() const
401 { return shape_p; }
402
403private:
404 // Delete all Slicer objects.
406
407 // Check if the slicers match the array shape.
409
410 //# Data members.
414};
415
416
417
418} //# NAMESPACE CASACORE - END
419
420#endif
#define TABLECOLUMNCHECKROW(ROWNR)
Definition: TableColumn.h:51
Non-templated base class for templated Array class.
Definition: ArrayBase.h:73
void acbPutSlice(rownr_t rownr, const Vector< Vector< Slice > > &arraySlices, const ArrayBase &arr)
void reference(const ArrayColumnBase &)
Change the reference to another column.
void acbGetColumnCells(const RefRows &rownrs, const Slicer &arraySection, ArrayBase &arr, Bool resize) const
void acbGetColumn(const Vector< Vector< Slice > > &arraySection, ArrayBase &array, Bool resize) const
Get irregular slices from all arrays in the column as given by the vectors of Slice objects.
void baseGetSlice(rownr_t rownr, const Slicer &arraySection, ArrayBase &array) const
void acbGetColumn(ArrayBase &array, Bool resize) const
Get the array of all values in a column.
void acbPutColumn(const ArrayBase &array)
Put the array of all values in the column.
void acbPutColumnCells(const RefRows &rownrs, const Slicer &arraySection, const ArrayBase &arr)
void acbGetColumnRange(const Slicer &rowRange, ArrayBase &arr, Bool resize) const
Get the array of some values in a column.
void handleSlices(const Vector< Vector< Slice > > &slices, BaseSlicesFunctor &functor, const Slicer &slicer, const ArrayBase &array) const
A common function used by all functions that can get or put irregular array slices.
void setShape(rownr_t rownr, const IPosition &shape, const IPosition &tileShape)
Try to store the array in a tiled way using the given tile shape.
Bool checkShape(const IPosition &expShape, const IPosition &arrShape, Bool noSlicing, Int64 rownr, const String &where) const
Throw an exception if the array does not have the expected shape.
void acbGetColumnRange(const Slicer &rowRange, const Slicer &arraySection, ArrayBase &arr, Bool resize) const
Get slices from some arrays in a column.
ArrayColumnBase(const Table &, const String &columnName)
Construct for the given column in the given table.
void acbPutColumn(const Slicer &arraySection, const ArrayBase &array)
Put into subsections of the table arrays in the entire column.
void acbGetColumnCells(const RefRows &rownrs, ArrayBase &arr, Bool resize) const
void acbGetColumnCells(const RefRows &rows, const ColumnSlicer &columnSlicer, ArrayBase &destination, Bool resize) const
Get various slices from the given rows.
void acbPutColumn(const ArrayColumnBase &that)
Put the contents of that column into this one.
ArrayColumnBase(const ArrayColumnBase &)
Copy constructor (reference semantics).
void acbPutColumnCells(const RefRows &rows, const Vector< Vector< Slice > > &arraySlices, const ArrayBase &source)
Put various slices in the given rows.
ArrayColumnBase(const TableColumn &column)
Construct from the given table column.
void acbPutColumnRange(const Slicer &rowRange, const Slicer &arraySection, const ArrayBase &arr)
Put into subsection of the table arrays in some rows of the column.
void acbPutColumnCells(const RefRows &rows, const ColumnSlicer &columnSlicer, const ArrayBase &source)
void baseGet(rownr_t rownr, ArrayBase &array) const
Counterparts of the acbGet() functions below not checking shapes, etc.
void basePut(rownr_t rownr, const ArrayBase &array)
Counterparts of the acbPut() functions below not checking shapes, etc.
void acbGetSlice(rownr_t rownr, const Slicer &arraySection, ArrayBase &array, Bool resize) const
Get a slice of an N-dimensional array in a particular cell (i.e.
void acbPut(rownr_t rownr, const ArrayBase &array)
Put the array in a particular cell (i.e.
void basePutSlice(rownr_t rownr, const Slicer &arraySection, const ArrayBase &array)
void adaptShape(const IPosition &shp, ArrayBase &arr, Bool resize, Int64 rownr, const String &where) const
Adapt the shape of the array if possible.
void acbGet(rownr_t rownr, ArrayBase &array, Bool resize) const
Get the array value in a particular cell (i.e.
ArrayColumnBase & operator=(const ArrayColumnBase &)
Assignment uses reference semantics, thus works the same as function reference.
void acbGetSlice(rownr_t rownr, const Vector< Vector< Slice > > &arraySlices, ArrayBase &arr, Bool resize) const
Get an irregular slice of an N-dimensional array in a particular cell (i.e.
ArrayColumnBase()
The default constructor creates a null object, i.e.
void acbFillColumn(const ArrayBase &value)
Put the same value in all cells of the column.
void acbGetColumn(const Slicer &arraySection, ArrayBase &array, Bool resize) const
Get regular slices from all arrays in the column.
void setShape(rownr_t rownr, const IPosition &shape)
Set the shape of the array in the given row.
uInt ndim(rownr_t rownr) const
Get the #dimensions of an array in a particular cell.
void acbPutColumnCells(const RefRows &rownrs, const ArrayBase &arr)
void acbPutColumnRange(const Slicer &rowRange, const ArrayBase &arr)
Put the array of some values in the column.
IPosition shape(rownr_t rownr) const
Get the shape of an array in a particular cell.
void acbPutSlice(rownr_t rownr, const Slicer &arraySection, const ArrayBase &array)
Put into a slice of an N-dimensional array in a particular cell.
void acbPutColumn(const Vector< Vector< Slice > > &arraySlices, const ArrayBase &arr)
virtual void getArray(rownr_t rownr, ArrayBase &dataPtr) const
Get an array from a particular cell.
virtual void getSlice(rownr_t rownr, const Slicer &, ArrayBase &dataPtr) const
Get a slice of an N-dimensional array in a particular cell.
virtual uInt ndim(rownr_t rownr) const
Get the #dimensions of an array in a particular cell.
virtual IPosition shape(rownr_t rownr) const
Get the shape of an array in a particular cell.
virtual void putArray(rownr_t rownr, const ArrayBase &dataPtr)
Put the array value in a particular cell.
virtual void putSlice(rownr_t rownr, const Slicer &, const ArrayBase &dataPtr)
Put a slice of an N-dimensional array in a particular cell.
String validateParameters() const
Check if the slicers match the array shape.
const Vector< Slicer * > & getDestinationSlicers() const
Get the desintation slicers.
Vector< Slicer * > destinationSlicers_p
const IPosition & shape() const
Get the shape.
void freeSlicers()
Delete all Slicer objects.
const Vector< Slicer * > & getDataSlicers() const
Get the data slicers.
ColumnSlicer(const IPosition &shape, const Vector< Slicer * > &dataSlicers, const Vector< Slicer * > &destinationSlicers)
Construct the object.
Vector< Slicer * > dataSlicers_p
~ColumnSlicer()
The destructor deletes all Slicer objects.
String: the storage and methods of handling collections of characters.
Definition: String.h:225
IPosition tileShape(rownr_t rownr) const
Get the tile shape of an array in a particular cell.
Definition: TableColumn.h:235
BaseColumn * baseColPtr_p
Definition: TableColumn.h:388
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
TableExprNode array(const TableExprNode &values, const TableExprNodeSet &shape)
Create an array of the given shape and fill it with the values.
Definition: ExprNode.h:1929
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
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.
uInt64 rownr_t
Define the type of a row number in a table.
Definition: aipsxtype.h:46