casacore
BaseColumn.h
Go to the documentation of this file.
1 //# BaseColumn.h: Abstract base class for a table column
2 //# Copyright (C) 1994,1995,1996,1997,1998
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_BASECOLUMN_H
29 #define TABLES_BASECOLUMN_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/tables/Tables/ColumnDesc.h>
35 #include <casacore/casa/Utilities/Compare.h>
36 #include <casacore/casa/Utilities/CountedPtr.h>
37 #include <casacore/casa/BasicSL/Complex.h>
38 
39 namespace casacore { //# NAMESPACE CASACORE - BEGIN
40 
41 //# Forward Declarations
42 class BaseColumnDesc;
43 class ColumnCache;
44 class TableRecord;
45 class RefRows;
46 class IPosition;
47 class Slicer;
48 class Sort;
49 template<class T> class Array;
50 template<class T> class Vector;
51 
52 // <summary>
53 // Abstract base class for a table column
54 // </summary>
55 
56 // <use visibility=local>
57 
58 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
59 // </reviewed>
60 
61 // <prerequisite>
62 //# Classes you should understand before using this one.
63 // <li> ColumnDesc
64 // <li> Table
65 // </prerequisite>
66 
67 // <etymology>
68 // This is the (abstract) base class to access a column in a table.
69 // </etymology>
70 
71 // <synopsis>
72 // This class is the base class for the derived column classes.
73 // It is a private class in the sense that the user cannot get
74 // access to it. All user access to a column is done via the
75 // classes TableColumn, ScalarColumn and ArrayColumn. They call
76 // the corresponding functions in this class and its derived classes.
77 // </synopsis>
78 
79 // <motivation>
80 // This class serves a the base for the more specialized column classes
81 // like FilledScalarColumn and RefColumn. It defines many virtual
82 // functions, which are implemented in the derived classes.
83 // Some of these functions are purely virtual, some have a default
84 // implementation throwing an "invalid operation" exception. In that
85 // way those latter functions only have to be implemented in the
86 // classes which handle those cases.
87 // <note role=tip> The class RefColumn is in fact implemented in terms of
88 // this class. Almost every function in RefColumn calls the corresponding
89 // function in BaseColumn with the correct row number.
90 // </note>
91 // </motivation>
92 
93 // <todo asof="$DATE:$">
94 //# A List of bugs, limitations, extensions or planned refinements.
95 // </todo>
96 
97 
99 {
100 public:
101 
102  // Construct it using the given column description.
103  BaseColumn (const BaseColumnDesc*);
104 
105  virtual ~BaseColumn();
106 
107  // Test if the column is writable.
108  virtual Bool isWritable() const = 0;
109 
110  // Test if the column is stored (otherwise it is virtual).
111  virtual Bool isStored() const = 0;
112 
113  // Get access to the column keyword set.
114  // <group>
115  virtual TableRecord& rwKeywordSet() = 0;
116  virtual TableRecord& keywordSet() = 0;
117  // </group>
118 
119  // Get const access to the column description.
120  const ColumnDesc& columnDesc() const
121  { return colDesc_p; }
122 
123  // Get nr of rows in the column.
124  virtual uInt nrow() const = 0;
125 
126  // Test if the given cell contains a defined value.
127  virtual Bool isDefined (uInt rownr) const = 0;
128 
129  // Set the shape of the array in the given row.
130  virtual void setShape (uInt rownr, const IPosition& shape);
131 
132  // Set the shape and tile shape of the array in the given row.
133  virtual void setShape (uInt rownr, const IPosition& shape,
134  const IPosition& tileShape);
135 
136  // Get the global #dimensions of an array (ie. for all rows).
137  virtual uInt ndimColumn() const;
138 
139  // Get the global shape of an array (ie. for all rows).
140  virtual IPosition shapeColumn() const;
141 
142  // Get the #dimensions of an array in a particular cell.
143  virtual uInt ndim (uInt rownr) const;
144 
145  // Get the shape of an array in a particular cell.
146  virtual IPosition shape (uInt rownr) const;
147 
148  // Ask the data manager if the shape of an existing array can be changed.
149  // Default is no.
150  virtual Bool canChangeShape() const;
151 
152  // Ask if the data manager can handle a scalar column.
153  // Default is never.
154  virtual Bool canAccessScalarColumn (Bool& reask) const;
155 
156  // Ask if the data manager can handle an array column.
157  // Default is never.
158  virtual Bool canAccessArrayColumn (Bool& reask) const;
159 
160  // Ask if the data manager can handle a collection of cells in a
161  // scalar column. Default is never.
162  virtual Bool canAccessScalarColumnCells (Bool& reask) const;
163 
164  // Ask if the data manager can handle a collection of cells in an
165  // array column. Default is never.
166  virtual Bool canAccessArrayColumnCells (Bool& reask) const;
167 
168  // Ask if the data manager can handle a cell slice.
169  // Default is never.
170  virtual Bool canAccessSlice (Bool& reask) const;
171 
172  // Ask if the data manager can handle a column slice.
173  // Default is never.
174  virtual Bool canAccessColumnSlice (Bool& reask) const;
175 
176  // Initialize the rows from startRow till endRow (inclusive)
177  // with the default value defined in the column description.
178  virtual void initialize (uInt startRownr, uInt endRownr) = 0;
179 
180  // Get the value from a particular cell.
181  // This can be a scalar or an array.
182  virtual void get (uInt rownr, void* dataPtr) const = 0;
183 
184  // Get a slice of an N-dimensional array in a particular cell.
185  virtual void getSlice (uInt rownr, const Slicer&, void* dataPtr) const;
186 
187  // Get the vector of all scalar values in a column.
188  virtual void getScalarColumn (void* dataPtr) const;
189 
190  // Get the array of all array values in a column.
191  // If the column contains n-dim arrays, the resulting array is (n+1)-dim.
192  // The arrays in the column have to have the same shape in all cells.
193  virtual void getArrayColumn (void* dataPtr) const;
194 
195  // Get subsections from all 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  virtual void getColumnSlice (const Slicer&, void* dataPtr) const;
199 
200  // Get the vector of some scalar values in a column.
201  virtual void getScalarColumnCells (const RefRows& rownrs,
202  void* dataPtr) const;
203 
204  // Get the array of some array values in a column.
205  // If the column contains n-dim arrays, the resulting array is (n+1)-dim.
206  // The arrays in the column have to have the same shape in all cells.
207  virtual void getArrayColumnCells (const RefRows& rownrs,
208  void* dataPtr) const;
209 
210  // Get subsections from some arrays in the column.
211  // If the column contains n-dim arrays, the resulting array is (n+1)-dim.
212  // The arrays in the column have to have the same shape in all cells.
213  virtual void getColumnSliceCells (const RefRows& rownrs,
214  const Slicer&, void* dataPtr) const;
215 
216  // Put the value in a particular cell.
217  // This can be a scalar or an array.
218  virtual void put (uInt rownr, const void* dataPtr) = 0;
219 
220  // Put a slice of an N-dimensional array in a particular cell.
221  virtual void putSlice (uInt rownr, const Slicer&, const void* dataPtr);
222 
223  // Put the vector of all scalar values in the column.
224  virtual void putScalarColumn (const void* dataPtr);
225 
226  // Put the array of all array values in the column.
227  // If the column contains n-dim arrays, the source array is (n+1)-dim.
228  // The arrays in the column have to have the same shape in all cells.
229  virtual void putArrayColumn (const void* dataPtr);
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  virtual void putColumnSlice (const Slicer&, const void* dataPtr);
235 
236  // Get the vector of some scalar values in a column.
237  virtual void putScalarColumnCells (const RefRows& rownrs,
238  const void* dataPtr);
239 
240  // Get the array of some array values in a column.
241  // If the column contains n-dim arrays, the resulting array is (n+1)-dim.
242  // The arrays in the column have to have the same shape in all cells.
243  virtual void putArrayColumnCells (const RefRows& rownrs,
244  const void* dataPtr);
245 
246  // Put subsections of some arrays in the column.
247  // If the column contains n-dim arrays, the source array is (n+1)-dim.
248  // The arrays in the column have to have the same shape in all cells.
249  virtual void putColumnSliceCells (const RefRows& rownrs,
250  const Slicer&, const void* dataPtr);
251 
252  // Get the value from the row and convert it to the required type.
253  // This can only be used for scalar columns with a standard data type.
254  // Note that an unsigned integer cannot be converted to a signed integer
255  // with the same length. So only Int64 can handle all integer values.
256  // <group>
257  void getScalar (uInt rownr, Bool& value) const;
258  void getScalar (uInt rownr, uChar& value) const;
259  void getScalar (uInt rownr, Short& value) const;
260  void getScalar (uInt rownr, uShort& value) const;
261  void getScalar (uInt rownr, Int& value) const;
262  void getScalar (uInt rownr, uInt& value) const;
263  void getScalar (uInt rownr, Int64& value) const;
264  void getScalar (uInt rownr, float& value) const;
265  void getScalar (uInt rownr, double& value) const;
266  void getScalar (uInt rownr, Complex& value) const;
267  void getScalar (uInt rownr, DComplex& value) const;
268  void getScalar (uInt rownr, String& value) const;
269  void getScalar (uInt rownr, TableRecord& value) const;
270  // </group>
271 
272  // Get a scalar for the other data types.
273  // The given data type id must match the data type id of this column.
274  void getScalar (uInt rownr, void* value, const String& dataTypeId) const;
275 
276  // Put the value into the row and convert it from the given type.
277  // This can only be used for scalar columns with a standard data type.
278  // <group>
279  void putScalar (uInt rownr, const Bool& value);
280  void putScalar (uInt rownr, const uChar& value);
281  void putScalar (uInt rownr, const Short& value);
282  void putScalar (uInt rownr, const uShort& value);
283  void putScalar (uInt rownr, const Int& value);
284  void putScalar (uInt rownr, const uInt& value);
285  void putScalar (uInt rownr, const float& value);
286  void putScalar (uInt rownr, const double& value);
287  void putScalar (uInt rownr, const Complex& value);
288  void putScalar (uInt rownr, const DComplex& value);
289  void putScalar (uInt rownr, const String& value);
290  void putScalar (uInt rownr, const Char* value)
291  { putScalar (rownr, String(value)); }
292  void putScalar (uInt rownr, const TableRecord& value);
293  // </group>
294 
295  // Get a pointer to the underlying column cache.
296  virtual ColumnCache& columnCache() = 0;
297 
298  // Set the maximum cache size (in bytes) to be used by a storage manager.
299  virtual void setMaximumCacheSize (uInt nbytes) = 0;
300 
301  // Add this column and its data to the Sort object.
302  // It may allocate some storage on the heap, which will be saved
303  // in the argument dataSave.
304  // The function freeSortKey must be called to free this storage.
305  // <group>
306  virtual void makeSortKey (Sort&, CountedPtr<BaseCompare>& cmpObj,
307  Int order, const void*& dataSave);
308  // Do it only for the given row numbers.
309  virtual void makeRefSortKey (Sort&, CountedPtr<BaseCompare>& cmpObj,
310  Int order, const Vector<uInt>& rownrs,
311  const void*& dataSave);
312  // </group>
313 
314  // Free storage on the heap allocated by makeSortkey().
315  // The pointer will be set to zero.
316  virtual void freeSortKey (const void*& dataSave);
317 
318  // Allocate value buffers for the table iterator.
319  // Also get a comparison object if undefined.
320  // The function freeIterBuf must be called to free the buffers.
321  virtual void allocIterBuf (void*& lastVal, void*& curVal,
322  CountedPtr<BaseCompare>& cmpObj);
323 
324  // Free the value buffers allocated by allocIterBuf.
325  virtual void freeIterBuf (void*& lastVal, void*& curVal);
326 
327 protected:
328  // Throw exceptions for invalid scalar get or put.
329  // <group>
330  void throwGetScalar() const;
331  void throwPutScalar() const;
332  void throwGetType (const String& type) const;
333  void throwPutType (const String& type) const;
334  // </group>
335 
336  //# Data members
338  //# This ColumnDesc object is created to be able to return
339  //# a const ColumnDesc& by function columnDesc().
341 };
342 
343 
344 
345 
346 } //# NAMESPACE CASACORE - END
347 
348 #endif
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:119
virtual void putArrayColumn(const void *dataPtr)
Put the array of all array values in the column.
virtual IPosition shape(uInt rownr) const
Get the shape of an array in a particular cell.
virtual void getScalarColumnCells(const RefRows &rownrs, void *dataPtr) const
Get the vector of some scalar values in a column.
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
virtual uInt ndimColumn() const
Get the global #dimensions of an array (ie.
int Int
Definition: aipstype.h:47
virtual Bool canAccessColumnSlice(Bool &reask) const
Ask if the data manager can handle a column slice.
virtual uInt nrow() const =0
Get nr of rows in the column.
void getScalar(uInt rownr, Bool &value) const
Get the value from the row and convert it to the required type.
virtual void getArrayColumnCells(const RefRows &rownrs, void *dataPtr) const
Get the array of some array values in a column.
virtual Bool isWritable() const =0
Test if the column is writable.
virtual TableRecord & keywordSet()=0
ColumnDesc colDesc_p
Definition: BaseColumn.h:340
virtual void getSlice(uInt rownr, const Slicer &, void *dataPtr) const
Get a slice of an N-dimensional array in a particular cell.
An abstract base class for table column descriptions.
Definition: BaseColDesc.h:107
Envelope class for the description of a table column.
Definition: ColumnDesc.h:131
unsigned char uChar
Definition: aipstype.h:44
virtual void putColumnSliceCells(const RefRows &rownrs, const Slicer &, const void *dataPtr)
Put subsections of some arrays in the column.
virtual Bool canAccessScalarColumnCells(Bool &reask) const
Ask if the data manager can handle a collection of cells in a scalar column.
char Char
Definition: aipstype.h:43
virtual void getColumnSlice(const Slicer &, void *dataPtr) const
Get subsections from all arrays in the column.
void throwGetType(const String &type) const
virtual void initialize(uInt startRownr, uInt endRownr)=0
Initialize the rows from startRow till endRow (inclusive) with the default value defined in the colum...
short Short
Definition: aipstype.h:45
virtual void putSlice(uInt rownr, const Slicer &, const void *dataPtr)
Put a slice of an N-dimensional array in a particular cell.
virtual void freeSortKey(const void *&dataSave)
Free storage on the heap allocated by makeSortkey().
Sort on one or more keys, ascending and/or descending.
Definition: Sort.h:248
virtual void putScalarColumnCells(const RefRows &rownrs, const void *dataPtr)
Get the vector of some scalar values in a column.
virtual void getArrayColumn(void *dataPtr) const
Get the array of all array values in a column.
virtual ColumnCache & columnCache()=0
Get a pointer to the underlying column cache.
Referenced counted pointer for constant data.
Definition: CountedPtr.h:86
void throwGetScalar() const
Throw exceptions for invalid scalar get or put.
virtual Bool canAccessArrayColumn(Bool &reask) const
Ask if the data manager can handle an array column.
virtual void makeRefSortKey(Sort &, CountedPtr< BaseCompare > &cmpObj, Int order, const Vector< uInt > &rownrs, const void *&dataSave)
Do it only for the given row numbers.
Class holding the row numbers in a RefTable.
Definition: RefRows.h:85
void throwPutType(const String &type) const
virtual void setMaximumCacheSize(uInt nbytes)=0
Set the maximum cache size (in bytes) to be used by a storage manager.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:39
virtual TableRecord & rwKeywordSet()=0
Get access to the column keyword set.
A caching object for a table column.
Definition: ColumnCache.h:83
virtual void getScalarColumn(void *dataPtr) const
Get the vector of all scalar values in a column.
void putScalar(uInt rownr, const Char *value)
Definition: BaseColumn.h:290
void putScalar(uInt rownr, const Bool &value)
Put the value into the row and convert it from the given type.
virtual void putScalarColumn(const void *dataPtr)
Put the vector of all scalar values in the column.
A hierarchical collection of named fields of various types.
Definition: TableRecord.h:182
virtual void makeSortKey(Sort &, CountedPtr< BaseCompare > &cmpObj, Int order, const void *&dataSave)
Add this column and its data to the Sort object.
virtual Bool canChangeShape() const
Ask the data manager if the shape of an existing array can be changed.
Specify which elements to extract from an n-dimensional array.
Definition: Slicer.h:275
virtual Bool canAccessScalarColumn(Bool &reask) const
Ask if the data manager can handle a scalar column.
virtual Bool isStored() const =0
Test if the column is stored (otherwise it is virtual).
virtual void getColumnSliceCells(const RefRows &rownrs, const Slicer &, void *dataPtr) const
Get subsections from some arrays in the column.
virtual Bool canAccessSlice(Bool &reask) const
Ask if the data manager can handle a cell slice.
virtual void putColumnSlice(const Slicer &, const void *dataPtr)
Put into subsections of all table arrays in the column.
virtual void allocIterBuf(void *&lastVal, void *&curVal, CountedPtr< BaseCompare > &cmpObj)
Allocate value buffers for the table iterator.
const ColumnDesc & columnDesc() const
Get const access to the column description.
Definition: BaseColumn.h:120
void throwPutScalar() const
const BaseColumnDesc * colDescPtr_p
Definition: BaseColumn.h:337
String: the storage and methods of handling collections of characters.
Definition: String.h:223
virtual void setShape(uInt rownr, const IPosition &shape)
Set the shape of the array in the given row.
virtual Bool isDefined(uInt rownr) const =0
Test if the given cell contains a defined value.
virtual void putArrayColumnCells(const RefRows &rownrs, const void *dataPtr)
Get the array of some array values in a column.
virtual Bool canAccessArrayColumnCells(Bool &reask) const
Ask if the data manager can handle a collection of cells in an array column.
virtual void put(uInt rownr, const void *dataPtr)=0
Put the value in a particular cell.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
virtual void freeIterBuf(void *&lastVal, void *&curVal)
Free the value buffers allocated by allocIterBuf.
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
unsigned int uInt
Definition: aipstype.h:48
BaseColumn(const BaseColumnDesc *)
Construct it using the given column description.
virtual IPosition shapeColumn() const
Get the global shape of an array (ie.
unsigned short uShort
Definition: aipstype.h:46
Abstract base class for a table column.
Definition: BaseColumn.h:98
virtual uInt ndim(uInt rownr) const
Get the #dimensions of an array in a particular cell.