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  // Get the tile shape of an array in a particular cell.
154  // If the cell does not contain an array, an empty IPosition is returned.
155  IPosition tileShape(uInt rownr) const;
156 
157  // Set dimensions of array in a particular cell.
158  // <group>
159  void setShape (uInt rownr, const IPosition& shape);
160  // The shape of tiles in the array can also be defined.
161  void setShape (uInt rownr, const IPosition& shape,
162  const IPosition& tileShape);
163  // </group>
164 
165  // Test if the given cell contains an array.
166  Bool isDefined (uInt rownr) const;
167 
168  // Get the array from a particular cell.
169  // The length of the buffer pointed to by arrayPtr must match
170  // the actual length. This is checked by ArrayColumn.
171  void get (uInt rownr, void* arrayPtr) const;
172 
173  // Get a slice of an N-dimensional array in a particular cell.
174  // The length of the buffer pointed to by arrayPtr must match
175  // the actual length. This is checked by ArrayColumn.
176  void getSlice (uInt rownr, const Slicer&, void* arrayPtr) const;
177 
178  // Get the array of all values in a column.
179  // If the column contains n-dim arrays, the resulting array is (n+1)-dim.
180  // The arrays in the column have to have the same shape in all cells.
181  // The length of the buffer pointed to by arrayPtr must match
182  // the actual length. This is checked by ArrayColumn.
183  void getArrayColumn (void* arrayPtr) const;
184 
185  // Get the array of some values in a column.
186  // If the column contains n-dim arrays, the resulting array is (n+1)-dim.
187  // The arrays in the column have to have the same shape in all cells.
188  // The length of the buffer pointed to by arrayPtr must match
189  // the actual length. This is checked by ArrayColumn.
190  void getArrayColumnCells (const RefRows& rownrs, void* arrayPtr) const;
191 
192  // Get subsections from all arrays in the column.
193  // If the column contains n-dim arrays, the resulting array is (n+1)-dim.
194  // The arrays in the column have to have the same shape in all cells.
195  // The length of the buffer pointed to by arrayPtr must match
196  // the actual length. This is checked by ArrayColumn.
197  void getColumnSlice (const Slicer&, void* arrayPtr) const;
198 
199  // Get subsections from some arrays in the column.
200  // If the column contains n-dim arrays, the resulting array is (n+1)-dim.
201  // The arrays in the column have to have the same shape in all cells.
202  // The length of the buffer pointed to by arrayPtr must match
203  // the actual length. This is checked by ArrayColumn.
204  void getColumnSliceCells (const RefRows& rownrs, const Slicer&,
205  void* arrayPtr) const;
206 
207  // Put the value in a particular cell.
208  // The length of the buffer pointed to by arrayPtr must match
209  // the actual length. This is checked by ArrayColumn.
210  void put (uInt rownr, const void* arrayPtr);
211 
212  // Put a slice of an N-dimensional array in a particular cell.
213  // The length of the buffer pointed to by arrayPtr must match
214  // the actual length. This is checked by ArrayColumn.
215  void putSlice (uInt rownr, const Slicer&, const void* arrayPtr);
216 
217  // Put the array of all values in the column.
218  // If the column contains n-dim arrays, the source array is (n+1)-dim.
219  // The arrays in the column have to have the same shape in all cells.
220  // The length of the buffer pointed to by arrayPtr must match
221  // the actual length. This is checked by ArrayColumn.
222  void putArrayColumn (const void* arrayPtr);
223 
224  // Put the array of some values in the column.
225  // If the column contains n-dim arrays, the source array is (n+1)-dim.
226  // The arrays in the column have to have the same shape in all cells.
227  // The length of the buffer pointed to by arrayPtr must match
228  // the actual length. This is checked by ArrayColumn.
229  void putArrayColumnCells (const RefRows& rownrs, const void* arrayPtr);
230 
231  // Put into subsections of all table arrays in the column.
232  // If the column contains n-dim arrays, the source array is (n+1)-dim.
233  // The arrays in the column have to have the same shape in all cells.
234  // The length of the buffer pointed to by arrayPtr must match
235  // the actual length. This is checked by ArrayColumn.
236  void putColumnSlice (const Slicer&, const void* arrayPtr);
237 
238  // Put into subsections of some table arrays in the column.
239  // If the column contains n-dim arrays, the source array is (n+1)-dim.
240  // The arrays in the column have to have the same shape in all cells.
241  // The length of the buffer pointed to by arrayPtr must match
242  // the actual length. This is checked by ArrayColumn.
243  void putColumnSliceCells (const RefRows& rownrs, const Slicer&,
244  const void* arrayPtr);
245 
246  // Create a data manager column object for this column.
248 
249 
250 private:
251  // Pointer to column description.
253  // Is the shape for all arrays in the columns defined.
255  // Shape for all arrays in the column.
257 
258 
259  // Copy constructor cannot be used.
261 
262  // Assignment cannot be used.
264 
265  // Check if the shape of an array can be set and if it is set
266  // correctly (i.e. if matching possible #dim in column description).
267  void checkShape (const IPosition& shape) const;
268 
269  // Write the column data.
270  // The control information is written into the given AipsIO object,
271  // while the data is written/flushed by the data manager.
272  void putFileDerived (AipsIO&);
273 
274  // Read the column data back.
275  // The control information is read from the given AipsIO object.
276  // This is used to bind the column to the appropriate data manager.
277  // Thereafter the data manager gets opened.
278  void getFileDerived (AipsIO&, const ColumnSet&);
279 };
280 
281 
282 
283 
284 } //# NAMESPACE CASACORE - END
285 
286 #ifndef CASACORE_NO_AUTO_TEMPLATES
287 #include <casacore/tables/Tables/ArrColData.tcc>
288 #endif //# CASACORE_NO_AUTO_TEMPLATES
289 #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.
void getSlice(uInt rownr, const Slicer &, void *arrayPtr) const
Get a slice of an N-dimensional 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.
virtual Bool canAccessColumnSlice(Bool &reask) const
Ask if the data manager can handle a column slice.
AipsIO is the object persistency mechanism of Casacore.
Definition: AipsIO.h:168
void initialize(uInt startRownr, uInt endRownr)
Initialize the rows from startRownr till endRownr (inclusive) with the default value defined in the c...
virtual Bool canAccessSlice(Bool &reask) const
Ask if the data manager can handle a cell slice.
ArrayColumnData< T > & operator=(const ArrayColumnData< T > &)
Assignment cannot be used.
void getColumnSlice(const Slicer &, void *arrayPtr) const
Get subsections from all arrays in the column.
Class to manage a set of table columns.
Definition: ColumnSet.h:93
Access to a table column containing arrays.
Definition: ArrColData.h:105
void checkShape(const IPosition &shape) const
Check if the shape of an array can be set and if it is set correctly (i.e.
IPosition tileShape(uInt rownr) const
Get the tile shape of an array in a particular cell.
void putSlice(uInt rownr, const Slicer &, const void *arrayPtr)
Put a slice of an N-dimensional array in a particular cell.
virtual Bool canAccessArrayColumnCells(Bool &reask) const
Ask if the data manager can handle some cells in a column.
Class holding the row numbers in a RefTable.
Definition: RefRows.h:85
Bool isDefined(uInt rownr) const
Test if the given cell contains an array.
IPosition shapeColumn() const
Get the global shape of an array (ie.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
virtual Bool canAccessArrayColumn(Bool &reask) const
Ask if the data manager can handle a column.
virtual Bool canChangeShape() const
Ask the data manager if the shape of an existing array can be changed.
void setShapeColumn(const IPosition &shape)
Set shape of all arrays in the column.
void getArrayColumn(void *arrayPtr) const
Get the array of all values in a column.
Bool shapeColDef_p
Is the shape for all arrays in the columns defined.
Definition: ArrColData.h:254
Specify which elements to extract from an n-dimensional array.
Definition: Slicer.h:289
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.
void getArrayColumnCells(const RefRows &rownrs, void *arrayPtr) const
Get the array of some values in a column.
void getColumnSliceCells(const RefRows &rownrs, const Slicer &, void *arrayPtr) const
Get subsections from some arrays in the column.
void putFileDerived(AipsIO &)
Write the column data.
uInt ndim(uInt rownr) const
Get the #dimensions of an array in a particular cell.
IPosition shape(uInt rownr) const
Get the shape of an array in a particular cell.
uInt ndimColumn() const
Get the global #dimensions of an array (ie.
void putArrayColumnCells(const RefRows &rownrs, const void *arrayPtr)
Put the array of some values in the column.
void createDataManagerColumn()
Create a data manager column object for this column.
const ArrayColumnDesc< T > * arrDescPtr_p
Pointer to column description.
Definition: ArrColData.h:252
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:51
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:256