casacore
ArrColData.h
Go to the documentation of this file.
1 //# ArrColData.h: Access to a table column containing arrays
2 //# Copyright (C) 1994,1995,1996,1998,1999
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_ARRCOLDATA_H
29 #define TABLES_ARRCOLDATA_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/tables/Tables/PlainColumn.h>
34 #include <casacore/casa/Arrays/IPosition.h>
35 
36 namespace casacore { //# NAMESPACE CASACORE - BEGIN
37 
38 //# Forward Declarations
39 class ColumnSet;
40 template<class T> class ArrayColumnDesc;
41 class AipsIO;
42 
43 
44 // <summary>
45 // Access to a table column containing arrays
46 // </summary>
47 
48 // <use visibility=local>
49 
50 // <reviewed reviewer="Gareth Hunt" date="94Nov17" tests="">
51 // </reviewed>
52 
53 // <prerequisite>
54 //# Classes you should understand before using this one.
55 // <li> PlainColumn
56 // <li> ArrayColumnDesc
57 // <li> Table
58 // </prerequisite>
59 
60 // <etymology>
61 // ArrayColumnData represents a table column containing array data.
62 // </etymology>
63 
64 // <synopsis>
65 // The class ArrayColumnData is derived from PlainColumn.
66 // It implements the virtual functions accessing a table column
67 // containing arrays with an arbitrary data type.
68 // Both direct and indirect arrays are supported.
69 //
70 // It is possible to access an array or a subsection of it in an
71 // individual cell (i.e. table row) or in the entire column.
72 // The functions accessing the entire column are implemented by
73 // looping over the individual cells.
74 //
75 // The main task of this class is to communicate with the data manager
76 // column object. This consists of:
77 // <ul>
78 // <li> Binding itself to a data manager.
79 // <li> Letting the data manager create its column object and
80 // setting the shape for direct arrays.
81 // <li> Closing the data manager column object (in putFileDerived).
82 // <li> Reconstructing the data manager object for an existing table
83 // (in getFileDerived).
84 // <li> Transferring get/put calls to the data manager column object.
85 // </ul>
86 //
87 // The class is hidden from the user by the envelope class ArrayColumn.
88 // It used directly, it should be done with care. It assumes that the
89 // arrays in the various get and put functions have the correct length.
90 // ArrayColumn does that check.
91 // </synopsis>
92 
93 // <templating arg=T>
94 // <li> Default constructor
95 // <li> Copy constructor
96 // <li> Assignment operator
97 // </templating>
98 
99 // <todo asof="$DATE:$">
100 //# A List of bugs, limitations, extensions or planned refinements.
101 // <li> support tiling
102 // </todo>
103 
104 
105 template<class T> class ArrayColumnData : public PlainColumn
106 {
107 public:
108 
109  // Construct an array column object from the given description
110  // in the given column set.
111  // This constructor is used by ArrayColumnDesc::makeColumn.
113 
115 
116  // Ask the data manager if the shape of an existing array can be changed.
117  virtual Bool canChangeShape() const;
118 
119  // Ask if the data manager can handle a cell slice.
120  virtual Bool canAccessSlice (Bool& reask) const;
121 
122  // Ask if the data manager can handle a column.
123  virtual Bool canAccessArrayColumn (Bool& reask) const;
124 
125  // Ask if the data manager can handle some cells in a column.
126  virtual Bool canAccessArrayColumnCells (Bool& reask) const;
127 
128  // Ask if the data manager can handle a column slice.
129  virtual Bool canAccessColumnSlice (Bool& reask) const;
130 
131  // Initialize the rows from startRownr till endRownr (inclusive)
132  // with the default value defined in the column description (if defined).
133  void initialize (uInt startRownr, uInt endRownr);
134 
135  // Get the global #dimensions of an array (ie. for all rows).
136  uInt ndimColumn() const;
137 
138  // Get the global shape of an array (ie. for all rows).
139  IPosition shapeColumn() const;
140 
141  // Set shape of all arrays in the column.
142  // It can only be used for direct arrays.
143  void setShapeColumn (const IPosition& shape);
144 
145  // Get the #dimensions of an array in a particular cell.
146  // If the cell does not contain an array, 0 is returned.
147  uInt ndim (uInt rownr) const;
148 
149  // Get the shape of an array in a particular cell.
150  // If the cell does not contain an array, an empty IPosition is returned.
151  IPosition shape(uInt rownr) const;
152 
153  // Set dimensions of array in a particular cell.
154  // <group>
155  void setShape (uInt rownr, const IPosition& shape);
156  // The shape of tiles in the array can also be defined.
157  void setShape (uInt rownr, const IPosition& shape,
158  const IPosition& tileShape);
159  // </group>
160 
161  // Test if the given cell contains an array.
162  Bool isDefined (uInt rownr) const;
163 
164  // Get the array from a particular cell.
165  // The length of the buffer pointed to by arrayPtr must match
166  // the actual length. This is checked by ArrayColumn.
167  void get (uInt rownr, void* arrayPtr) const;
168 
169  // Get a slice of an N-dimensional array in a particular cell.
170  // The length of the buffer pointed to by arrayPtr must match
171  // the actual length. This is checked by ArrayColumn.
172  void getSlice (uInt rownr, const Slicer&, void* arrayPtr) const;
173 
174  // Get the array of all values in a column.
175  // If the column contains n-dim arrays, the resulting array is (n+1)-dim.
176  // The arrays in the column have to have the same shape in all cells.
177  // The length of the buffer pointed to by arrayPtr must match
178  // the actual length. This is checked by ArrayColumn.
179  void getArrayColumn (void* arrayPtr) const;
180 
181  // Get the array of some values in a column.
182  // If the column contains n-dim arrays, the resulting array is (n+1)-dim.
183  // The arrays in the column have to have the same shape in all cells.
184  // The length of the buffer pointed to by arrayPtr must match
185  // the actual length. This is checked by ArrayColumn.
186  void getArrayColumnCells (const RefRows& rownrs, void* arrayPtr) const;
187 
188  // Get subsections from all arrays in the column.
189  // If the column contains n-dim arrays, the resulting array is (n+1)-dim.
190  // The arrays in the column have to have the same shape in all cells.
191  // The length of the buffer pointed to by arrayPtr must match
192  // the actual length. This is checked by ArrayColumn.
193  void getColumnSlice (const Slicer&, void* arrayPtr) const;
194 
195  // Get subsections from some arrays in the column.
196  // If the column contains n-dim arrays, the resulting array is (n+1)-dim.
197  // The arrays in the column have to have the same shape in all cells.
198  // The length of the buffer pointed to by arrayPtr must match
199  // the actual length. This is checked by ArrayColumn.
200  void getColumnSliceCells (const RefRows& rownrs, const Slicer&,
201  void* arrayPtr) const;
202 
203  // Put the value in a particular cell.
204  // The length of the buffer pointed to by arrayPtr must match
205  // the actual length. This is checked by ArrayColumn.
206  void put (uInt rownr, const void* arrayPtr);
207 
208  // Put a slice of an N-dimensional array in a particular cell.
209  // The length of the buffer pointed to by arrayPtr must match
210  // the actual length. This is checked by ArrayColumn.
211  void putSlice (uInt rownr, const Slicer&, const void* arrayPtr);
212 
213  // Put the array of all values in the column.
214  // If the column contains n-dim arrays, the source array is (n+1)-dim.
215  // The arrays in the column have to have the same shape in all cells.
216  // The length of the buffer pointed to by arrayPtr must match
217  // the actual length. This is checked by ArrayColumn.
218  void putArrayColumn (const void* arrayPtr);
219 
220  // Put the array of some values in the column.
221  // If the column contains n-dim arrays, the source array is (n+1)-dim.
222  // The arrays in the column have to have the same shape in all cells.
223  // The length of the buffer pointed to by arrayPtr must match
224  // the actual length. This is checked by ArrayColumn.
225  void putArrayColumnCells (const RefRows& rownrs, const void* arrayPtr);
226 
227  // Put into subsections of all table arrays in the column.
228  // If the column contains n-dim arrays, the source array is (n+1)-dim.
229  // The arrays in the column have to have the same shape in all cells.
230  // The length of the buffer pointed to by arrayPtr must match
231  // the actual length. This is checked by ArrayColumn.
232  void putColumnSlice (const Slicer&, const void* arrayPtr);
233 
234  // Put into subsections of some table arrays in the column.
235  // If the column contains n-dim arrays, the source array is (n+1)-dim.
236  // The arrays in the column have to have the same shape in all cells.
237  // The length of the buffer pointed to by arrayPtr must match
238  // the actual length. This is checked by ArrayColumn.
239  void putColumnSliceCells (const RefRows& rownrs, const Slicer&,
240  const void* arrayPtr);
241 
242  // Create a data manager column object for this column.
244 
245 
246 private:
247  // Pointer to column description.
249  // Is the shape for all arrays in the columns defined.
251  // Shape for all arrays in the column.
253 
254 
255  // Copy constructor cannot be used.
257 
258  // Assignment cannot be used.
260 
261  // Check if the shape of an array can be set and if it is set
262  // correctly (i.e. if matching possible #dim in column description).
263  void checkShape (const IPosition& shape) const;
264 
265  // Write the column data.
266  // The control information is written into the given AipsIO object,
267  // while the data is written/flushed by the data manager.
268  void putFileDerived (AipsIO&);
269 
270  // Read the column data back.
271  // The control information is read from the given AipsIO object.
272  // This is used to bind the column to the appropriate data manager.
273  // Thereafter the data manager gets opened.
274  void getFileDerived (AipsIO&, const ColumnSet&);
275 };
276 
277 
278 
279 
280 } //# NAMESPACE CASACORE - END
281 
282 #ifndef CASACORE_NO_AUTO_TEMPLATES
283 #include <casacore/tables/Tables/ArrColData.tcc>
284 #endif //# CASACORE_NO_AUTO_TEMPLATES
285 #endif
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:119
Templated class for description of table array columns.
Definition: ArrColData.h:40
void putColumnSliceCells(const RefRows &rownrs, const Slicer &, const void *arrayPtr)
Put into subsections of some table arrays in the column.
IPosition shape(uInt rownr) const
Get the shape of an array in a particular cell.
void getFileDerived(AipsIO &, const ColumnSet &)
Read the column data back.
void putArrayColumn(const void *arrayPtr)
Put the array of all values in the column.
AipsIO is the object persistency mechanism of Casacore.
Definition: AipsIO.h:168
uInt ndim(uInt rownr) const
Get the #dimensions of an array in a particular cell.
void initialize(uInt startRownr, uInt endRownr)
Initialize the rows from startRownr till endRownr (inclusive) with the default value defined in the c...
ArrayColumnData< T > & operator=(const ArrayColumnData< T > &)
Assignment cannot be used.
Class to manage a set of table columns.
Definition: ColumnSet.h:93
void checkShape(const IPosition &shape) const
Check if the shape of an array can be set and if it is set correctly (i.e.
Access to a table column containing arrays.
Definition: ArrColData.h:105
IPosition shapeColumn() const
Get the global shape of an array (ie.
void putSlice(uInt rownr, const Slicer &, const void *arrayPtr)
Put a slice of an N-dimensional array in a particular cell.
Class holding the row numbers in a RefTable.
Definition: RefRows.h:85
virtual Bool canAccessColumnSlice(Bool &reask) const
Ask if the data manager can handle a column slice.
void getColumnSliceCells(const RefRows &rownrs, const Slicer &, void *arrayPtr) const
Get subsections from some arrays in the column.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:39
virtual Bool canAccessSlice(Bool &reask) const
Ask if the data manager can handle a cell slice.
void getArrayColumn(void *arrayPtr) const
Get the array of all values in a column.
void setShapeColumn(const IPosition &shape)
Set shape of all arrays in the column.
Bool shapeColDef_p
Is the shape for all arrays in the columns defined.
Definition: ArrColData.h:250
Specify which elements to extract from an n-dimensional array.
Definition: Slicer.h:275
Base class for a column in a plain table.
Definition: PlainColumn.h:84
ArrayColumnData(const ArrayColumnDesc< T > *, ColumnSet *)
Construct an array column object from the given description in the given column set.
void put(uInt rownr, const void *arrayPtr)
Put the value in a particular cell.
uInt ndimColumn() const
Get the global #dimensions of an array (ie.
virtual Bool canAccessArrayColumnCells(Bool &reask) const
Ask if the data manager can handle some cells in a column.
void putFileDerived(AipsIO &)
Write the column data.
void getArrayColumnCells(const RefRows &rownrs, void *arrayPtr) const
Get the array of some values in a column.
void getSlice(uInt rownr, const Slicer &, void *arrayPtr) const
Get a slice of an N-dimensional array in a particular cell.
void putArrayColumnCells(const RefRows &rownrs, const void *arrayPtr)
Put the array of some values in the column.
void getColumnSlice(const Slicer &, void *arrayPtr) const
Get subsections from all arrays in the column.
Bool isDefined(uInt rownr) const
Test if the given cell contains an array.
virtual Bool canAccessArrayColumn(Bool &reask) const
Ask if the data manager can handle a column.
void createDataManagerColumn()
Create a data manager column object for this column.
const ArrayColumnDesc< T > * arrDescPtr_p
Pointer to column description.
Definition: ArrColData.h:248
virtual Bool canChangeShape() const
Ask the data manager if the shape of an existing array can be changed.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
void putColumnSlice(const Slicer &, const void *arrayPtr)
Put into subsections of all table arrays in the column.
unsigned int uInt
Definition: aipstype.h:48
void setShape(uInt rownr, const IPosition &shape)
Set dimensions of array in a particular cell.
IPosition shapeCol_p
Shape for all arrays in the column.
Definition: ArrColData.h:252