TableColumn.h

Go to the documentation of this file.
00001 //# TableColumn.h: Access to a table column
00002 //# Copyright (C) 1994,1995,1996,1997,1998,1999,2001,2002
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_TABLECOLUMN_H
00029 #define TABLES_TABLECOLUMN_H
00030 
00031 
00032 //# Includes
00033 #include <casacore/casa/aips.h>
00034 #include <casacore/tables/Tables/BaseColumn.h>
00035 #include <casacore/tables/Tables/BaseTable.h>
00036 #include <casacore/casa/BasicSL/String.h>
00037 #include <casacore/casa/Arrays/IPosition.h>
00038 
00039 namespace casacore { //# NAMESPACE CASACORE - BEGIN
00040 
00041 //# Forward Declarations
00042 class Table;
00043 class BaseTable;
00044 
00045 
00046 //# Check the number of rows in debug mode.
00047 #if defined(AIPS_DEBUG)
00048 # define TABLECOLUMNCHECKROW(ROWNR) \
00049     (checkRowNumber (ROWNR))
00050 #else
00051 # define TABLECOLUMNCHECKROW(ROWNR)
00052 #endif
00053 
00054 
00055 // <summary>
00056 // Read/write access to a table column
00057 // </summary>
00058 
00059 // <use visibility=export>
00060 
00061 // <reviewed reviewer="dschieb" date="1994/08/10" tests="none">
00062 // </reviewed>
00063 
00064 // <prerequisite>
00065 //   <li> Table
00066 //   <li> ColumnDesc
00067 // </prerequisite>
00068 
00069 // <synopsis>
00070 // The class TableColumn gives read and write access to a column
00071 // in a table. In particular access to the column description
00072 // (for name, data type, etc.) and to the column keyword set
00073 // can be obtained. 
00074 // Another important function is isDefined, which tests if a
00075 // cell (i.e. table row) in a column contains a value.
00076 //
00077 // The classes ScalarColumn<T> and ArrayColumn<T> have to be
00078 // used to get/put the data in the column cells.
00079 // However, TableColumn has get functions for the basic data types
00080 // (Bool, uChar, Short, uSort, Int, uInt, float, double,
00081 //  Complex, DComplex and String).
00082 // Opposite to the get functions in ScalarColumn<T>, the
00083 // TableColumn get functions support data type promotion.
00084 //
00085 // A default constructor is defined to allow construction of an array
00086 // of TableColumn objects. However, this constructs an object not
00087 // referencing a column. Functions like get, etc. will fail (i.e. result
00088 // in a segmentation fault) when used on such objects. The functions
00089 // isNull and throwIfNull can be used to test on this.
00090 // The functions attach and reference can fill in the object.
00091 // </synopsis>
00092 
00093 // <example>
00094 // See module <linkto module="Tables#open">Tables</linkto>.
00095 // </example>
00096 
00097 
00098 class TableColumn
00099 {
00100 friend class ForwardColumn;      //# for function baseColPtr()
00101 
00102 public:
00103 
00104     // The default constructor creates a null object, i.e. it
00105     // does not reference a table column.
00106     // The sole purpose of this constructor is to allow construction
00107     // of an array of TableColumn objects.
00108     // The functions reference and attach can be used to make a null object
00109     // reference a column.
00110     // Note that get functions, etc. will cause a segmentation fault
00111     // when operating on a null object. It was felt it was too expensive
00112     // to test on null over and over again. The user should use the isNull
00113     // or throwIfNull function in case of doubt.
00114     TableColumn();
00115 
00116     // Construct the object for a column in the table using its name.
00117     TableColumn (const Table&, const String& columnName);
00118 
00119     // Construct the object for a column in the table using its index.
00120     // This allows to loop through all columns in a table as:
00121     // <srcblock>
00122     //    for (uInt=0; i<tab.ncolumn(); i++) {
00123     //        TableColumn tabcol(tab,i);
00124     //    }
00125     // </srcblock>
00126     TableColumn (const Table&, uInt columnIndex);
00127 
00128     // Copy constructor (reference semantics).
00129     TableColumn (const TableColumn&);
00130 
00131     virtual ~TableColumn();
00132 
00133     // Assignment has reference semantics.
00134     // It copies the object, not the data of that column to this column.
00135     // Function <src>putColumn</src> can be used to copy the data of a column.
00136     // <br>It does the same as the reference function.
00137     TableColumn& operator= (const TableColumn&);        
00138 
00139     // Clone the object.
00140     virtual TableColumn* clone() const;
00141 
00142     // Change the reference to another column.
00143     // This is in fact an assignment operator with reference semantics.
00144     // It removes the reference to the current column and creates
00145     // a reference to the column referenced in the other object.
00146     // It will handle null objects correctly.
00147     void reference (const TableColumn&);
00148 
00149     // Attach a column to the object.
00150     // This is in fact only a shorthand for 
00151     // <<br><src> reference (TableColumn (table, columnName)); </src>
00152     // <group>
00153     void attach (const Table& table, const String& columnName)
00154         { reference (TableColumn (table, columnName)); }
00155     void attach (const Table& table, uInt columnIndex)
00156         { reference (TableColumn (table, columnIndex)); }
00157     // </group>
00158 
00159     // Test if the object is null, i.e. does not reference a column.
00160     Bool isNull() const
00161         { return (baseColPtr_p == 0  ?  True : False); }
00162 
00163     // Throw an exception if the object is null, i.e.
00164     // if function isNull() is True.
00165     void throwIfNull() const;
00166 
00167     // Test if the column can be written to, thus if the column and
00168     // the underlying table can be written to.
00169     Bool isWritable() const
00170         { return baseTabPtr_p->isWritable()  &&  isColWritable_p; }
00171 
00172     // Test if the column is writable at all (virtual columns might not be).
00173     // Note that keywords can always be written, even for virtual columns.
00174     Bool isWritableAtAll() const
00175         { return isColWritable_p; }
00176 
00177     // Check if the column is writable and throw an exception if not.
00178     void checkWritable() const
00179         { if (!isWritable()) throwNotWritable(); }
00180 
00181     // Get readonly access to the column keyword set.
00182     const TableRecord& keywordSet() const
00183         { return baseColPtr_p->keywordSet(); }
00184 
00185     // Get read/write access to the column keyword set.
00186     // An exception is thrown if the table is not writable.
00187     TableRecord& rwKeywordSet();
00188 
00189     // Get const access to the column description.
00190     // ColumnDesc functions have to be used to get the data type, etc..
00191     const ColumnDesc& columnDesc() const;
00192 
00193     // Get the Table object this column belongs to.
00194     Table table() const;
00195 
00196     // Get the number of rows in the column.
00197     uInt nrow() const
00198         { return baseColPtr_p->nrow(); }
00199 
00200     // Can the shape of an already existing non-FixedShape array be changed?
00201     // This depends on the storage manager. Most storage managers
00202     // can handle it, but TiledDataStMan and TiledColumnStMan can not.
00203     Bool canChangeShape() const
00204         { return canChangeShape_p; }
00205 
00206     // Get the global #dimensions of an array (ie. for all cells in column).
00207     // This is always set for fixed shape arrays.
00208     // Otherwise, 0 will be returned.
00209     uInt ndimColumn() const
00210         { return baseColPtr_p->ndimColumn(); }
00211 
00212     // Get the global shape of an array (ie. for all cells in the column).
00213     // This is always set for fixed shape arrays.
00214     // Otherwise, a 0-dim shape will be returned.
00215     IPosition shapeColumn() const
00216         { return baseColPtr_p->shapeColumn(); }
00217 
00218     // Test if the given cell contains a defined value.
00219     Bool isDefined (uInt rownr) const
00220         { TABLECOLUMNCHECKROW(rownr); return baseColPtr_p->isDefined (rownr); }
00221 
00222     // Does the column has content in the given row (default is the first row)?
00223     // It has if it is defined and does not contain an empty array.
00224     Bool hasContent (uInt rownr=0) const;
00225 
00226     // Get the #dimensions of an array in a particular cell.
00227     uInt ndim (uInt rownr) const
00228         { TABLECOLUMNCHECKROW(rownr); return baseColPtr_p->ndim (rownr); }
00229 
00230     // Get the shape of an array in a particular cell.
00231     IPosition shape (uInt rownr) const
00232         { TABLECOLUMNCHECKROW(rownr); return baseColPtr_p->shape (rownr); }
00233 
00234     // Get the tile shape of an array in a particular cell.
00235     IPosition tileShape (uInt rownr) const
00236         { TABLECOLUMNCHECKROW(rownr); return baseColPtr_p->tileShape (rownr); }
00237 
00238     // Get the value of a scalar in the given row.
00239     // Data type promotion is possible.
00240     // These functions only work for the standard data types.
00241     // <group>
00242     void getScalar (uInt rownr, Bool& value) const
00243         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->getScalar (rownr, value); }
00244     void getScalar (uInt rownr, uChar& value) const
00245         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->getScalar (rownr, value); }
00246     void getScalar (uInt rownr, Short& value) const
00247         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->getScalar (rownr, value); }
00248     void getScalar (uInt rownr, uShort& value) const
00249         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->getScalar (rownr, value); }
00250     void getScalar (uInt rownr, Int& value) const
00251         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->getScalar (rownr, value); }
00252     void getScalar (uInt rownr, uInt& value) const
00253         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->getScalar (rownr, value); }
00254     void getScalar (uInt rownr, Int64& value) const
00255         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->getScalar (rownr, value); }
00256     void getScalar (uInt rownr, float& value) const
00257         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->getScalar (rownr, value); }
00258     void getScalar (uInt rownr, double& value) const
00259         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->getScalar (rownr, value); }
00260     void getScalar (uInt rownr, Complex& value) const
00261         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->getScalar (rownr, value); }
00262     void getScalar (uInt rownr, DComplex& value) const
00263         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->getScalar (rownr, value); }
00264     void getScalar (uInt rownr, String& value) const
00265         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->getScalar (rownr, value); }
00266     // </group>
00267 
00268     // Get the value from the row and convert it to the required type.
00269     // This can only be used for scalar columns with a standard data type.
00270     // <group>
00271     Bool     asBool     (uInt rownr) const;
00272     uChar    asuChar    (uInt rownr) const;
00273     Short    asShort    (uInt rownr) const;
00274     uShort   asuShort   (uInt rownr) const;
00275     Int      asInt      (uInt rownr) const;
00276     uInt     asuInt     (uInt rownr) const;
00277     float    asfloat    (uInt rownr) const;
00278     double   asdouble   (uInt rownr) const;
00279     Complex  asComplex  (uInt rownr) const;
00280     DComplex asDComplex (uInt rownr) const;
00281     String   asString   (uInt rownr) const;
00282     // </group>
00283 
00284     // Get the value of a scalar in the given row.
00285     // These functions work for all data types.
00286     // Data type promotion is possible for the standard data types.
00287     // The functions are primarily meant for ScalarColumn<T>.
00288     // <group>
00289     void getScalarValue (uInt rownr, Bool* value, const String&) const
00290         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->getScalar (rownr,*value); }
00291     void getScalarValue (uInt rownr, uChar* value, const String&) const
00292         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->getScalar (rownr,*value); }
00293     void getScalarValue (uInt rownr, Short* value, const String&) const
00294         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->getScalar (rownr,*value); }
00295     void getScalarValue (uInt rownr, uShort* value, const String&) const
00296         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->getScalar (rownr,*value); }
00297     void getScalarValue (uInt rownr, Int* value, const String&) const
00298         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->getScalar (rownr,*value); }
00299     void getScalarValue (uInt rownr, uInt* value, const String&) const
00300         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->getScalar (rownr,*value); }
00301     void getScalarValue (uInt rownr, float* value, const String&) const
00302         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->getScalar (rownr,*value); }
00303     void getScalarValue (uInt rownr, double* value, const String&) const
00304         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->getScalar (rownr,*value); }
00305     void getScalarValue (uInt rownr, Complex* value, const String&) const
00306         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->getScalar (rownr,*value); }
00307     void getScalarValue (uInt rownr, DComplex* value, const String&) const
00308         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->getScalar (rownr,*value); }
00309     void getScalarValue (uInt rownr, String* value, const String&) const
00310         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->getScalar (rownr,*value); }
00311     void getScalarValue (uInt rownr, void* value,
00312                          const String& dataTypeId) const
00313         { TABLECOLUMNCHECKROW(rownr);
00314           baseColPtr_p->getScalar (rownr,value,dataTypeId); }
00315     // </group>
00316 
00317     // Copy the value of a cell of that column to a cell of this column.
00318     // This function only works for the standard data types.
00319     // Data type promotion will be done if needed.
00320     // An exception is thrown if this column is not writable or if
00321     // the data cannot be converted.
00322     // <group>
00323     // Use the same row numbers for both cells.
00324     void put (uInt rownr, const TableColumn& that,
00325               Bool preserveTileShape=False)
00326       { put (rownr, that, rownr, preserveTileShape); }
00327     // Use possibly different row numbers for that (i.e. input) and
00328     // and this (i.e. output) cell.
00329     virtual void put (uInt thisRownr, const TableColumn& that,
00330                       uInt thatRownr, Bool preserveTileShape=False);
00331     // </group>
00332 
00333     // Copy the values of that column to this column.
00334     // The numbers of rows in both columns must be equal.
00335     // Data type promotion is possible.
00336     // An exception is thrown if the data cannot be converted.
00337     // This function is useful to copy one column to another without
00338     // knowing their data types.
00339     // In fact, this function is an assignment operator with copy semantics.
00340     void putColumn (const TableColumn& that);
00341 
00342     // Put the value of a scalar in the given row.
00343     // Data type promotion is possible.
00344     // These functions only work for the standard data types.
00345     // <group>
00346     void putScalar (uInt rownr, const Bool& value)
00347         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->putScalar (rownr, value); }
00348     void putScalar (uInt rownr, const uChar& value)
00349         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->putScalar (rownr, value); }
00350     void putScalar (uInt rownr, const Short& value)
00351         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->putScalar (rownr, value); }
00352     void putScalar (uInt rownr, const uShort& value)
00353         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->putScalar (rownr, value); }
00354     void putScalar (uInt rownr, const Int& value)
00355         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->putScalar (rownr, value); }
00356     void putScalar (uInt rownr, const uInt& value)
00357         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->putScalar (rownr, value); }
00358     void putScalar (uInt rownr, const float& value)
00359         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->putScalar (rownr, value); }
00360     void putScalar (uInt rownr, const double& value)
00361         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->putScalar (rownr, value); }
00362     void putScalar (uInt rownr, const Complex& value)
00363         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->putScalar (rownr, value); }
00364     void putScalar (uInt rownr, const DComplex& value)
00365         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->putScalar (rownr, value); }
00366     void putScalar (uInt rownr, const String& value)
00367         { TABLECOLUMNCHECKROW(rownr); baseColPtr_p->putScalar (rownr, value); }
00368     void putScalar (uInt rownr, const Char* value)
00369         { putScalar (rownr, String(value)); }
00370     // </group>
00371 
00372     // Check if the row number is valid.
00373     // It throws an exception if out of range.
00374     void checkRowNumber (uInt rownr) const
00375         { baseTabPtr_p->checkRowNumber (rownr); }
00376 
00377     // Set the maximum cache size (in bytes) to be used by a storage manager.
00378     void setMaximumCacheSize (uInt nbytes) const
00379         { baseColPtr_p->setMaximumCacheSize (nbytes); }
00380 
00381 protected:
00382     BaseTable*  baseTabPtr_p;
00383     BaseColumn* baseColPtr_p;                //# pointer to real column object
00384     const ColumnCache* colCachePtr_p;
00385     Bool canChangeShape_p;
00386     Bool isColWritable_p;                    //# is the column writable at all?
00387 
00388 
00389     // Get the baseColPtr_p of this TableColumn object.
00390     BaseColumn* baseColPtr () const
00391         { return baseColPtr_p; }
00392 
00393     // Get the baseColPtr_p of another TableColumn object.
00394     // This is needed for function put, because baseColPtr_p is a
00395     // protected member of TableColumn. Another TableColumn has
00396     // no access to that.
00397     BaseColumn* baseColPtr (const TableColumn& that) const
00398         { return that.baseColPtr_p; }
00399 
00400 private:
00401     // Throw the exception that the column is not writable.
00402     void throwNotWritable() const;
00403 };
00404 
00405 
00406 // Define ROTableColumn for backward compatibility.
00407 typedef TableColumn ROTableColumn;
00408 
00409 
00410 } //# NAMESPACE CASACORE - END
00411 
00412 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1