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.
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.
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:39
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: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.
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:248
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