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  // Get the tile shape of an array in a particular cell.
149  virtual IPosition tileShape (uInt rownr) const;
150 
151  // Ask the data manager if the shape of an existing array can be changed.
152  // Default is no.
153  virtual Bool canChangeShape() const;
154 
155  // Ask if the data manager can handle a scalar column.
156  // Default is never.
157  virtual Bool canAccessScalarColumn (Bool& reask) const;
158 
159  // Ask if the data manager can handle an array column.
160  // Default is never.
161  virtual Bool canAccessArrayColumn (Bool& reask) const;
162 
163  // Ask if the data manager can handle a collection of cells in a
164  // scalar column. Default is never.
165  virtual Bool canAccessScalarColumnCells (Bool& reask) const;
166 
167  // Ask if the data manager can handle a collection of cells in an
168  // array column. Default is never.
169  virtual Bool canAccessArrayColumnCells (Bool& reask) const;
170 
171  // Ask if the data manager can handle a cell slice.
172  // Default is never.
173  virtual Bool canAccessSlice (Bool& reask) const;
174 
175  // Ask if the data manager can handle a column slice.
176  // Default is never.
177  virtual Bool canAccessColumnSlice (Bool& reask) const;
178 
179  // Initialize the rows from startRow till endRow (inclusive)
180  // with the default value defined in the column description.
181  virtual void initialize (uInt startRownr, uInt endRownr) = 0;
182 
183  // Get the value from a particular cell.
184  // This can be a scalar or an array.
185  virtual void get (uInt rownr, void* dataPtr) const = 0;
186 
187  // Get a slice of an N-dimensional array in a particular cell.
188  virtual void getSlice (uInt rownr, const Slicer&, void* dataPtr) const;
189 
190  // Get the vector of all scalar values in a column.
191  virtual void getScalarColumn (void* dataPtr) const;
192 
193  // Get the array of all array values in a column.
194  // If the column contains n-dim arrays, the resulting array is (n+1)-dim.
195  // The arrays in the column have to have the same shape in all cells.
196  virtual void getArrayColumn (void* dataPtr) const;
197 
198  // Get subsections from all arrays in the column.
199  // If the column contains n-dim arrays, the resulting array is (n+1)-dim.
200  // The arrays in the column have to have the same shape in all cells.
201  virtual void getColumnSlice (const Slicer&, void* dataPtr) const;
202 
203  // Get the vector of some scalar values in a column.
204  virtual void getScalarColumnCells (const RefRows& rownrs,
205  void* dataPtr) const;
206 
207  // Get the array of some array values in a column.
208  // If the column contains n-dim arrays, the resulting array is (n+1)-dim.
209  // The arrays in the column have to have the same shape in all cells.
210  virtual void getArrayColumnCells (const RefRows& rownrs,
211  void* dataPtr) const;
212 
213  // Get subsections from some arrays in the column.
214  // If the column contains n-dim arrays, the resulting array is (n+1)-dim.
215  // The arrays in the column have to have the same shape in all cells.
216  virtual void getColumnSliceCells (const RefRows& rownrs,
217  const Slicer&, void* dataPtr) const;
218 
219  // Put the value in a particular cell.
220  // This can be a scalar or an array.
221  virtual void put (uInt rownr, const void* dataPtr) = 0;
222 
223  // Put a slice of an N-dimensional array in a particular cell.
224  virtual void putSlice (uInt rownr, const Slicer&, const void* dataPtr);
225 
226  // Put the vector of all scalar values in the column.
227  virtual void putScalarColumn (const void* dataPtr);
228 
229  // Put the array of all array values in the column.
230  // If the column contains n-dim arrays, the source array is (n+1)-dim.
231  // The arrays in the column have to have the same shape in all cells.
232  virtual void putArrayColumn (const void* dataPtr);
233 
234  // Put into subsections of all 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  virtual void putColumnSlice (const Slicer&, const void* dataPtr);
238 
239  // Get the vector of some scalar values in a column.
240  virtual void putScalarColumnCells (const RefRows& rownrs,
241  const void* dataPtr);
242 
243  // Get the array of some array values in a column.
244  // If the column contains n-dim arrays, the resulting array is (n+1)-dim.
245  // The arrays in the column have to have the same shape in all cells.
246  virtual void putArrayColumnCells (const RefRows& rownrs,
247  const void* dataPtr);
248 
249  // Put subsections of some arrays in the column.
250  // If the column contains n-dim arrays, the source array is (n+1)-dim.
251  // The arrays in the column have to have the same shape in all cells.
252  virtual void putColumnSliceCells (const RefRows& rownrs,
253  const Slicer&, const void* dataPtr);
254 
255  // Get the value from the row and convert it to the required type.
256  // This can only be used for scalar columns with a standard data type.
257  // Note that an unsigned integer cannot be converted to a signed integer
258  // with the same length. So only Int64 can handle all integer values.
259  // <group>
260  void getScalar (uInt rownr, Bool& value) const;
261  void getScalar (uInt rownr, uChar& value) const;
262  void getScalar (uInt rownr, Short& value) const;
263  void getScalar (uInt rownr, uShort& value) const;
264  void getScalar (uInt rownr, Int& value) const;
265  void getScalar (uInt rownr, uInt& value) const;
266  void getScalar (uInt rownr, Int64& value) const;
267  void getScalar (uInt rownr, float& value) const;
268  void getScalar (uInt rownr, double& value) const;
269  void getScalar (uInt rownr, Complex& value) const;
270  void getScalar (uInt rownr, DComplex& value) const;
271  void getScalar (uInt rownr, String& value) const;
272  void getScalar (uInt rownr, TableRecord& value) const;
273  // </group>
274 
275  // Get a scalar for the other data types.
276  // The given data type id must match the data type id of this column.
277  void getScalar (uInt rownr, void* value, const String& dataTypeId) const;
278 
279  // Put the value into the row and convert it from the given type.
280  // This can only be used for scalar columns with a standard data type.
281  // <group>
282  void putScalar (uInt rownr, const Bool& value);
283  void putScalar (uInt rownr, const uChar& value);
284  void putScalar (uInt rownr, const Short& value);
285  void putScalar (uInt rownr, const uShort& value);
286  void putScalar (uInt rownr, const Int& value);
287  void putScalar (uInt rownr, const uInt& value);
288  void putScalar (uInt rownr, const float& value);
289  void putScalar (uInt rownr, const double& value);
290  void putScalar (uInt rownr, const Complex& value);
291  void putScalar (uInt rownr, const DComplex& value);
292  void putScalar (uInt rownr, const String& value);
293  void putScalar (uInt rownr, const Char* value)
294  { putScalar (rownr, String(value)); }
295  void putScalar (uInt rownr, const TableRecord& value);
296  // </group>
297 
298  // Get a pointer to the underlying column cache.
299  virtual ColumnCache& columnCache() = 0;
300 
301  // Set the maximum cache size (in bytes) to be used by a storage manager.
302  virtual void setMaximumCacheSize (uInt nbytes) = 0;
303 
304  // Add this column and its data to the Sort object.
305  // It may allocate some storage on the heap, which will be saved
306  // in the argument dataSave.
307  // The function freeSortKey must be called to free this storage.
308  // <group>
309  virtual void makeSortKey (Sort&, CountedPtr<BaseCompare>& cmpObj,
310  Int order, const void*& dataSave);
311  // Do it only for the given row numbers.
312  virtual void makeRefSortKey (Sort&, CountedPtr<BaseCompare>& cmpObj,
313  Int order, const Vector<uInt>& rownrs,
314  const void*& dataSave);
315  // </group>
316 
317  // Free storage on the heap allocated by makeSortkey().
318  // The pointer will be set to zero.
319  virtual void freeSortKey (const void*& dataSave);
320 
321  // Allocate value buffers for the table iterator.
322  // Also get a comparison object if undefined.
323  // The function freeIterBuf must be called to free the buffers.
324  virtual void allocIterBuf (void*& lastVal, void*& curVal,
325  CountedPtr<BaseCompare>& cmpObj);
326 
327  // Free the value buffers allocated by allocIterBuf.
328  virtual void freeIterBuf (void*& lastVal, void*& curVal);
329 
330 protected:
331  // Throw exceptions for invalid scalar get or put.
332  // <group>
333  void throwGetScalar() const;
334  void throwPutScalar() const;
335  void throwGetType (const String& type) const;
336  void throwPutType (const String& type) const;
337  // </group>
338 
339  //# Data members
341  //# This ColumnDesc object is created to be able to return
342  //# a const ColumnDesc& by function columnDesc().
344 };
345 
346 
347 
348 
349 } //# NAMESPACE CASACORE - END
350 
351 #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.
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
int Int
Definition: aipstype.h:50
virtual uInt nrow() const =0
Get nr of rows in the column.
virtual Bool isWritable() const =0
Test if the column is writable.
virtual TableRecord & keywordSet()=0
ColumnDesc colDesc_p
Definition: BaseColumn.h:343
virtual void getArrayColumnCells(const RefRows &rownrs, void *dataPtr) const
Get the array of some array values in a column.
virtual Bool canAccessSlice(Bool &reask) const
Ask if the data manager can handle a cell slice.
virtual void getArrayColumn(void *dataPtr) const
Get the array of all array values in a column.
virtual IPosition tileShape(uInt rownr) const
Get the tile shape of an array in a particular cell.
virtual Bool canAccessScalarColumnCells(Bool &reask) const
Ask if the data manager can handle a collection of cells in a scalar column.
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:47
virtual void putColumnSliceCells(const RefRows &rownrs, const Slicer &, const void *dataPtr)
Put subsections of some arrays in the column.
char Char
Definition: aipstype.h:46
virtual void getSlice(uInt rownr, const Slicer &, void *dataPtr) const
Get a slice of an N-dimensional array in a particular cell.
virtual Bool canAccessArrayColumn(Bool &reask) const
Ask if the data manager can handle an array column.
virtual Bool canChangeShape() const
Ask the data manager if the shape of an existing array can be changed.
void getScalar(uInt rownr, Bool &value) const
Get the value from the row and convert it to the required type.
virtual Bool canAccessColumnSlice(Bool &reask) const
Ask if the data manager can handle a column slice.
virtual IPosition shapeColumn() const
Get the global shape of an array (ie.
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:48
virtual void getScalarColumn(void *dataPtr) const
Get the vector of all scalar values in a column.
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 uInt ndimColumn() const
Get the global #dimensions of an array (ie.
virtual void putScalarColumnCells(const RefRows &rownrs, const void *dataPtr)
Get the vector of some scalar values in a column.
virtual uInt ndim(uInt rownr) const
Get the #dimensions of an array in a particular cell.
virtual ColumnCache & columnCache()=0
Get a pointer to the underlying column cache.
void throwGetScalar() const
Throw exceptions for invalid scalar get or put.
Referenced counted pointer for constant data.
Definition: CountedPtr.h:86
virtual void makeRefSortKey(Sort &, CountedPtr< BaseCompare > &cmpObj, Int order, const Vector< uInt > &rownrs, const void *&dataSave)
Do it only for the given row numbers.
void throwGetType(const String &type) const
virtual void getScalarColumnCells(const RefRows &rownrs, void *dataPtr) const
Get the vector of some scalar values in a column.
Class holding the row numbers in a RefTable.
Definition: RefRows.h:85
virtual Bool canAccessArrayColumnCells(Bool &reask) const
Ask if the data manager can handle a collection of cells in an array column.
virtual void setMaximumCacheSize(uInt nbytes)=0
Set the maximum cache size (in bytes) to be used by a storage manager.
virtual void getColumnSlice(const Slicer &, void *dataPtr) const
Get subsections from all arrays in the column.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
virtual TableRecord & rwKeywordSet()=0
Get access to the column keyword set.
A caching object for a table column.
Definition: ColumnCache.h:83
virtual Bool canAccessScalarColumn(Bool &reask) const
Ask if the data manager can handle a scalar column.
void throwPutScalar() const
void putScalar(uInt rownr, const Char *value)
Definition: BaseColumn.h:293
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.
Specify which elements to extract from an n-dimensional array.
Definition: Slicer.h:289
virtual Bool isStored() const =0
Test if the column is stored (otherwise it is virtual).
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.
virtual void getColumnSliceCells(const RefRows &rownrs, const Slicer &, void *dataPtr) const
Get subsections from some arrays in the column.
const BaseColumnDesc * colDescPtr_p
Definition: BaseColumn.h:340
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 IPosition shape(uInt rownr) const
Get the shape of an array in a particular cell.
const ColumnDesc & columnDesc() const
Get const access to the column description.
Definition: BaseColumn.h:120
virtual void putArrayColumnCells(const RefRows &rownrs, const void *dataPtr)
Get the array of some array values in a column.
void throwPutType(const String &type) const
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:51
BaseColumn(const BaseColumnDesc *)
Construct it using the given column description.
unsigned short uShort
Definition: aipstype.h:49
Abstract base class for a table column.
Definition: BaseColumn.h:98