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 
37 namespace casacore { //# NAMESPACE CASACORE - BEGIN
38 
39 //# Forward Declarations
40 class BaseSlicesFunctor;
41 class RefRows;
42 class ColumnSlicer;
43 class IPosition;
44 class Slice;
45 class Slicer;
46 class 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.
97  ArrayColumnBase (const TableColumn& column);
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.
113  void reference (const ArrayColumnBase&);
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,
208  ArrayBase& array,
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.
288  void acbPutColumn (const ArrayBase& array);
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 {
377 public:
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 
403 private:
404  // Delete all Slicer objects.
405  void freeSlicers();
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 & operator=(const ArrayColumnBase &)
Assignment uses reference semantics, thus works the same as function reference.
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.
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.
Vector< Slicer * > destinationSlicers_p
const Vector< Slicer * > & getDestinationSlicers() const
Get the desintation slicers.
void freeSlicers()
Delete all Slicer objects.
const IPosition & shape() const
Get the shape.
ColumnSlicer(const IPosition &shape, const Vector< Slicer * > &dataSlicers, const Vector< Slicer * > &destinationSlicers)
Construct the object.
Vector< Slicer * > dataSlicers_p
const Vector< Slicer * > & getDataSlicers() const
Get the data slicers.
~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