00001 //# BaseColumn.h: Abstract base class for a table column 00002 //# Copyright (C) 1994,1995,1996,1997,1998 00003 //# Associated Universities, Inc. Washington DC, USA. 00004 //# 00005 //# This library is free software; you can redistribute it and/or modify it 00006 //# under the terms of the GNU Library General Public License as published by 00007 //# the Free Software Foundation; either version 2 of the License, or (at your 00008 //# option) any later version. 00009 //# 00010 //# This library is distributed in the hope that it will be useful, but WITHOUT 00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 00012 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public 00013 //# License for more details. 00014 //# 00015 //# You should have received a copy of the GNU Library General Public License 00016 //# along with this library; if not, write to the Free Software Foundation, 00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA. 00018 //# 00019 //# Correspondence concerning AIPS++ should be addressed as follows: 00020 //# Internet email: aips2-request@nrao.edu. 00021 //# Postal address: AIPS++ Project Office 00022 //# National Radio Astronomy Observatory 00023 //# 520 Edgemont Road 00024 //# Charlottesville, VA 22903-2475 USA 00025 //# 00026 //# $Id$ 00027 00028 #ifndef TABLES_BASECOLUMN_H 00029 #define TABLES_BASECOLUMN_H 00030 00031 00032 //# Includes 00033 #include <casacore/casa/aips.h> 00034 #include <casacore/tables/Tables/ColumnDesc.h> 00035 #include <casacore/casa/Utilities/Compare.h> 00036 #include <casacore/casa/Utilities/CountedPtr.h> 00037 #include <casacore/casa/BasicSL/Complex.h> 00038 00039 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00040 00041 //# Forward Declarations 00042 class BaseColumnDesc; 00043 class ColumnCache; 00044 class TableRecord; 00045 class RefRows; 00046 class IPosition; 00047 class Slicer; 00048 class Sort; 00049 template<class T> class Array; 00050 template<class T> class Vector; 00051 00052 // <summary> 00053 // Abstract base class for a table column 00054 // </summary> 00055 00056 // <use visibility=local> 00057 00058 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests=""> 00059 // </reviewed> 00060 00061 // <prerequisite> 00062 //# Classes you should understand before using this one. 00063 // <li> ColumnDesc 00064 // <li> Table 00065 // </prerequisite> 00066 00067 // <etymology> 00068 // This is the (abstract) base class to access a column in a table. 00069 // </etymology> 00070 00071 // <synopsis> 00072 // This class is the base class for the derived column classes. 00073 // It is a private class in the sense that the user cannot get 00074 // access to it. All user access to a column is done via the 00075 // classes TableColumn, ScalarColumn and ArrayColumn. They call 00076 // the corresponding functions in this class and its derived classes. 00077 // </synopsis> 00078 00079 // <motivation> 00080 // This class serves a the base for the more specialized column classes 00081 // like FilledScalarColumn and RefColumn. It defines many virtual 00082 // functions, which are implemented in the derived classes. 00083 // Some of these functions are purely virtual, some have a default 00084 // implementation throwing an "invalid operation" exception. In that 00085 // way those latter functions only have to be implemented in the 00086 // classes which handle those cases. 00087 // <note role=tip> The class RefColumn is in fact implemented in terms of 00088 // this class. Almost every function in RefColumn calls the corresponding 00089 // function in BaseColumn with the correct row number. 00090 // </note> 00091 // </motivation> 00092 00093 // <todo asof="$DATE:$"> 00094 //# A List of bugs, limitations, extensions or planned refinements. 00095 // </todo> 00096 00097 00098 class BaseColumn 00099 { 00100 public: 00101 00102 // Construct it using the given column description. 00103 BaseColumn (const BaseColumnDesc*); 00104 00105 virtual ~BaseColumn(); 00106 00107 // Test if the column is writable. 00108 virtual Bool isWritable() const = 0; 00109 00110 // Test if the column is stored (otherwise it is virtual). 00111 virtual Bool isStored() const = 0; 00112 00113 // Get access to the column keyword set. 00114 // <group> 00115 virtual TableRecord& rwKeywordSet() = 0; 00116 virtual TableRecord& keywordSet() = 0; 00117 // </group> 00118 00119 // Get const access to the column description. 00120 const ColumnDesc& columnDesc() const 00121 { return colDesc_p; } 00122 00123 // Get nr of rows in the column. 00124 virtual uInt nrow() const = 0; 00125 00126 // Test if the given cell contains a defined value. 00127 virtual Bool isDefined (uInt rownr) const = 0; 00128 00129 // Set the shape of the array in the given row. 00130 virtual void setShape (uInt rownr, const IPosition& shape); 00131 00132 // Set the shape and tile shape of the array in the given row. 00133 virtual void setShape (uInt rownr, const IPosition& shape, 00134 const IPosition& tileShape); 00135 00136 // Get the global #dimensions of an array (ie. for all rows). 00137 virtual uInt ndimColumn() const; 00138 00139 // Get the global shape of an array (ie. for all rows). 00140 virtual IPosition shapeColumn() const; 00141 00142 // Get the #dimensions of an array in a particular cell. 00143 virtual uInt ndim (uInt rownr) const; 00144 00145 // Get the shape of an array in a particular cell. 00146 virtual IPosition shape (uInt rownr) const; 00147 00148 // Get the tile shape of an array in a particular cell. 00149 virtual IPosition tileShape (uInt rownr) const; 00150 00151 // Ask the data manager if the shape of an existing array can be changed. 00152 // Default is no. 00153 virtual Bool canChangeShape() const; 00154 00155 // Ask if the data manager can handle a scalar column. 00156 // Default is never. 00157 virtual Bool canAccessScalarColumn (Bool& reask) const; 00158 00159 // Ask if the data manager can handle an array column. 00160 // Default is never. 00161 virtual Bool canAccessArrayColumn (Bool& reask) const; 00162 00163 // Ask if the data manager can handle a collection of cells in a 00164 // scalar column. Default is never. 00165 virtual Bool canAccessScalarColumnCells (Bool& reask) const; 00166 00167 // Ask if the data manager can handle a collection of cells in an 00168 // array column. Default is never. 00169 virtual Bool canAccessArrayColumnCells (Bool& reask) const; 00170 00171 // Ask if the data manager can handle a cell slice. 00172 // Default is never. 00173 virtual Bool canAccessSlice (Bool& reask) const; 00174 00175 // Ask if the data manager can handle a column slice. 00176 // Default is never. 00177 virtual Bool canAccessColumnSlice (Bool& reask) const; 00178 00179 // Initialize the rows from startRow till endRow (inclusive) 00180 // with the default value defined in the column description. 00181 virtual void initialize (uInt startRownr, uInt endRownr) = 0; 00182 00183 // Get the value from a particular cell. 00184 // This can be a scalar or an array. 00185 virtual void get (uInt rownr, void* dataPtr) const = 0; 00186 00187 // Get a slice of an N-dimensional array in a particular cell. 00188 virtual void getSlice (uInt rownr, const Slicer&, void* dataPtr) const; 00189 00190 // Get the vector of all scalar values in a column. 00191 virtual void getScalarColumn (void* dataPtr) const; 00192 00193 // Get the array of all array values in a column. 00194 // If the column contains n-dim arrays, the resulting array is (n+1)-dim. 00195 // The arrays in the column have to have the same shape in all cells. 00196 virtual void getArrayColumn (void* dataPtr) const; 00197 00198 // Get subsections from all arrays in the column. 00199 // If the column contains n-dim arrays, the resulting array is (n+1)-dim. 00200 // The arrays in the column have to have the same shape in all cells. 00201 virtual void getColumnSlice (const Slicer&, void* dataPtr) const; 00202 00203 // Get the vector of some scalar values in a column. 00204 virtual void getScalarColumnCells (const RefRows& rownrs, 00205 void* dataPtr) const; 00206 00207 // Get the array of some array values in a column. 00208 // If the column contains n-dim arrays, the resulting array is (n+1)-dim. 00209 // The arrays in the column have to have the same shape in all cells. 00210 virtual void getArrayColumnCells (const RefRows& rownrs, 00211 void* dataPtr) const; 00212 00213 // Get subsections from some arrays in the column. 00214 // If the column contains n-dim arrays, the resulting array is (n+1)-dim. 00215 // The arrays in the column have to have the same shape in all cells. 00216 virtual void getColumnSliceCells (const RefRows& rownrs, 00217 const Slicer&, void* dataPtr) const; 00218 00219 // Put the value in a particular cell. 00220 // This can be a scalar or an array. 00221 virtual void put (uInt rownr, const void* dataPtr) = 0; 00222 00223 // Put a slice of an N-dimensional array in a particular cell. 00224 virtual void putSlice (uInt rownr, const Slicer&, const void* dataPtr); 00225 00226 // Put the vector of all scalar values in the column. 00227 virtual void putScalarColumn (const void* dataPtr); 00228 00229 // Put the array of all array values in the column. 00230 // If the column contains n-dim arrays, the source array is (n+1)-dim. 00231 // The arrays in the column have to have the same shape in all cells. 00232 virtual void putArrayColumn (const void* dataPtr); 00233 00234 // Put into subsections of all table arrays in the column. 00235 // If the column contains n-dim arrays, the source array is (n+1)-dim. 00236 // The arrays in the column have to have the same shape in all cells. 00237 virtual void putColumnSlice (const Slicer&, const void* dataPtr); 00238 00239 // Get the vector of some scalar values in a column. 00240 virtual void putScalarColumnCells (const RefRows& rownrs, 00241 const void* dataPtr); 00242 00243 // Get the array of some array values in a column. 00244 // If the column contains n-dim arrays, the resulting array is (n+1)-dim. 00245 // The arrays in the column have to have the same shape in all cells. 00246 virtual void putArrayColumnCells (const RefRows& rownrs, 00247 const void* dataPtr); 00248 00249 // Put subsections of some arrays in the column. 00250 // If the column contains n-dim arrays, the source array is (n+1)-dim. 00251 // The arrays in the column have to have the same shape in all cells. 00252 virtual void putColumnSliceCells (const RefRows& rownrs, 00253 const Slicer&, const void* dataPtr); 00254 00255 // Get the value from the row and convert it to the required type. 00256 // This can only be used for scalar columns with a standard data type. 00257 // Note that an unsigned integer cannot be converted to a signed integer 00258 // with the same length. So only Int64 can handle all integer values. 00259 // <group> 00260 void getScalar (uInt rownr, Bool& value) const; 00261 void getScalar (uInt rownr, uChar& value) const; 00262 void getScalar (uInt rownr, Short& value) const; 00263 void getScalar (uInt rownr, uShort& value) const; 00264 void getScalar (uInt rownr, Int& value) const; 00265 void getScalar (uInt rownr, uInt& value) const; 00266 void getScalar (uInt rownr, Int64& value) const; 00267 void getScalar (uInt rownr, float& value) const; 00268 void getScalar (uInt rownr, double& value) const; 00269 void getScalar (uInt rownr, Complex& value) const; 00270 void getScalar (uInt rownr, DComplex& value) const; 00271 void getScalar (uInt rownr, String& value) const; 00272 void getScalar (uInt rownr, TableRecord& value) const; 00273 // </group> 00274 00275 // Get a scalar for the other data types. 00276 // The given data type id must match the data type id of this column. 00277 void getScalar (uInt rownr, void* value, const String& dataTypeId) const; 00278 00279 // Put the value into the row and convert it from the given type. 00280 // This can only be used for scalar columns with a standard data type. 00281 // <group> 00282 void putScalar (uInt rownr, const Bool& value); 00283 void putScalar (uInt rownr, const uChar& value); 00284 void putScalar (uInt rownr, const Short& value); 00285 void putScalar (uInt rownr, const uShort& value); 00286 void putScalar (uInt rownr, const Int& value); 00287 void putScalar (uInt rownr, const uInt& value); 00288 void putScalar (uInt rownr, const float& value); 00289 void putScalar (uInt rownr, const double& value); 00290 void putScalar (uInt rownr, const Complex& value); 00291 void putScalar (uInt rownr, const DComplex& value); 00292 void putScalar (uInt rownr, const String& value); 00293 void putScalar (uInt rownr, const Char* value) 00294 { putScalar (rownr, String(value)); } 00295 void putScalar (uInt rownr, const TableRecord& value); 00296 // </group> 00297 00298 // Get a pointer to the underlying column cache. 00299 virtual ColumnCache& columnCache() = 0; 00300 00301 // Set the maximum cache size (in bytes) to be used by a storage manager. 00302 virtual void setMaximumCacheSize (uInt nbytes) = 0; 00303 00304 // Add this column and its data to the Sort object. 00305 // It may allocate some storage on the heap, which will be saved 00306 // in the argument dataSave. 00307 // The function freeSortKey must be called to free this storage. 00308 // <group> 00309 virtual void makeSortKey (Sort&, CountedPtr<BaseCompare>& cmpObj, 00310 Int order, const void*& dataSave); 00311 // Do it only for the given row numbers. 00312 virtual void makeRefSortKey (Sort&, CountedPtr<BaseCompare>& cmpObj, 00313 Int order, const Vector<uInt>& rownrs, 00314 const void*& dataSave); 00315 // </group> 00316 00317 // Free storage on the heap allocated by makeSortkey(). 00318 // The pointer will be set to zero. 00319 virtual void freeSortKey (const void*& dataSave); 00320 00321 // Allocate value buffers for the table iterator. 00322 // Also get a comparison object if undefined. 00323 // The function freeIterBuf must be called to free the buffers. 00324 virtual void allocIterBuf (void*& lastVal, void*& curVal, 00325 CountedPtr<BaseCompare>& cmpObj); 00326 00327 // Free the value buffers allocated by allocIterBuf. 00328 virtual void freeIterBuf (void*& lastVal, void*& curVal); 00329 00330 protected: 00331 // Throw exceptions for invalid scalar get or put. 00332 // <group> 00333 void throwGetScalar() const; 00334 void throwPutScalar() const; 00335 void throwGetType (const String& type) const; 00336 void throwPutType (const String& type) const; 00337 // </group> 00338 00339 //# Data members 00340 const BaseColumnDesc* colDescPtr_p; 00341 //# This ColumnDesc object is created to be able to return 00342 //# a const ColumnDesc& by function columnDesc(). 00343 ColumnDesc colDesc_p; 00344 }; 00345 00346 00347 00348 00349 } //# NAMESPACE CASACORE - END 00350 00351 #endif