00001 //# ScalarMeasColumn.h: Access to Scalar Measure Columns in Tables. 00002 //# Copyright (C) 1997,1998,1999,2000 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 MEASURES_SCALARMEASCOLUMN_H 00029 #define MEASURES_SCALARMEASCOLUMN_H 00030 00031 //# Includes 00032 #include <casacore/casa/aips.h> 00033 #include <casacore/measures/TableMeasures/TableMeasColumn.h> 00034 #include <casacore/measures/Measures/MeasRef.h> 00035 00036 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00037 00038 //# Forward Declarations 00039 template <class T> class ArrayColumn; 00040 template <class T> class ScalarColumn; 00041 00042 00043 // <summary> 00044 // Read only access to table scalar Measure columns. 00045 // </summary> 00046 00047 // <use visibility=export> 00048 00049 // <reviewed reviewer="Bob Garwood" date="1999/12/23" tests="tTableMeasures.cc"> 00050 // </reviewed> 00051 00052 // <prerequisite> 00053 //# Classes you should understand before using this one. 00054 // <li> <linkto module=Measures>Measures</linkto> 00055 // <li> <linkto module=Tables>Tables</linkto> 00056 // <li> <linkto class=TableMeasDesc>TableMeasDesc</linkto> 00057 // </prerequisite> 00058 00059 // <synopsis> 00060 // ScalarMeasColumn objects can be used to access scalar Measure Columns 00061 // in tables, both for reading and writing (if the table is writable). 00062 // 00063 // Before a column can be accessed it must have previously been defined as 00064 // a Measure column by use of the 00065 // <linkto class="TableMeasDesc">TableMeasDesc</linkto> object. 00066 // 00067 // The ScalarMeasColumn class is templated on Measure type. 00068 // Typedefs exist in the various Measure classes 00069 // (e.g. <linkto class=MEpoch>MEpoch</linkto>) to make declaration 00070 // less long winded. 00071 // Constructing scalar Measure column objects using these typedefs looks like 00072 // this: 00073 // <srcblock> 00074 // MEpoch::ScalarMeasColumn ec(table, "ColumnName); 00075 // </srcblock> 00076 // 00077 // <h3>Reading and writing Measures</h3> 00078 // 00079 // The reading and writing of Measures columns is very similar to reading and 00080 // writing of "ordinary" Table columns. 00081 // <linkto class="ScalarMeasColumn#get">get()</linkto> 00082 // and <linkto class="ScalarMeasColumn#get">operator()</linkto> 00083 // exist for reading Measures and the 00084 // <linkto class="ScalarMeasColumn#put">put()</linkto> member for adding 00085 // Measures to a column. (put() is obviously not defined for 00086 // ScalarMeasColumn objects.) Each of these members accepts a row number 00087 // as an argument. 00088 // The get() function gets the measure with the reference and offset as 00089 // it is stored in the column. Furthermore the convert() function is 00090 // available to get the measure with the given reference, possible offset, 00091 // and possible frame 00092 // 00093 // When a Measure is put, the reference and possible offset are converted 00094 // if the measure column is defined with a fixed reference and/or offset. 00095 // If the column's reference and offset are variable, the reference and 00096 // offset of the measure as put are written into the appropriate 00097 // reference and offset columns. 00098 // </synopsis> 00099 00100 // <example> 00101 // <srcblock> 00102 // // This creates a Scalar MEpoch column for read/write access. Column 00103 // // "Time1" must exist in Table "tab" and must have previously been 00104 // // defined as a MEpoch column using a TableMeasDesc. 00105 // MEpoch::ScalarMeasColumn timeCol(tab, "Time1"); 00106 // 00107 // // print some details about the column 00108 // if (timeCol.measDesc().isRefCodeVariable()) { 00109 // cout << "The column has variable references." << endl; 00110 // } else { 00111 // cout << "The fixed MeasRef for the column is: " 00112 // << timeCol.getMeasRef() << endl; 00113 // } 00114 // 00115 // // Add tab.nrow() measures to the column. 00116 // MEpoch tm(Quantity(MeasData::MJD2000, "d"), MEpoch::TAI); 00117 // for (uInt i=0; i<tab.nrow(); i++) { 00118 // timeCol.put(i, tm); 00119 // } 00120 // 00121 // // We could read from the column using timeCol but instead a read 00122 // // only column object is created. 00123 // MEpoch::ScalarMeasColumn timeColRead(tab, "Time1"); 00124 // for (i=0; i<tab.nrow(); i++) { 00125 // cout << timeColRead(i) << endl; 00126 // } 00127 // </srcblock> 00128 // </example> 00129 00130 // <motivation> 00131 // The standard Casacore Table system does not support Measures columns. 00132 // This class overcomes this limitation. 00133 // </motivation> 00134 // 00135 // <thrown> 00136 // <li>AipsError during construction if the column specified variable 00137 // offsets which are stored in an Array- rather than a ScalarColumn. 00138 // </thrown> 00139 // 00140 //# <todo asof="$DATE:$"> 00141 //# </todo> 00142 00143 template <class M> class ScalarMeasColumn : public TableMeasColumn 00144 { 00145 public: 00146 // The default constructor creates a null object. Useful for creating 00147 // arrays of ScalarMeasColumn objects. Attempting to use a null object 00148 // will produce a segmentation fault so care needs to be taken to 00149 // initialize the objects first by using attach(). 00150 // An ScalarMeasColumn object can be tested if it is null by using the 00151 // isNull() member. 00152 ScalarMeasColumn(); 00153 00154 // Create the ScalarMeasColumn from the table and column Name. 00155 ScalarMeasColumn (const Table& tab, const String& columnName); 00156 00157 // Copy constructor (copy semantics). 00158 ScalarMeasColumn (const ScalarMeasColumn<M>& that); 00159 00160 virtual ~ScalarMeasColumn(); 00161 00162 // Change the reference to another column. 00163 void reference (const ScalarMeasColumn<M>& that); 00164 00165 // Attach a column to the object. 00166 void attach (const Table& tab, const String& columnName); 00167 00168 // Get the Measure contained in the specified row. 00169 // It returns the Measure as found in the table. 00170 // <group name=get> 00171 void get (uInt rownr, M& meas) const; 00172 M operator() (uInt rownr) const; 00173 // </group> 00174 00175 // Get the Measure contained in the specified row and convert 00176 // it to the reference and offset found in the given measure. 00177 M convert (uInt rownr, const M& meas) const 00178 { return convert (rownr, meas.getRef()); } 00179 00180 // Get the Measure contained in the specified row and convert 00181 // it to the given reference. 00182 // <group> 00183 M convert (uInt rownr, const MeasRef<M>& measRef) const; 00184 M convert (uInt rownr, uInt refCode) const; 00185 // </group> 00186 00187 // Returns the column's fixed reference or the reference of the last 00188 // read Measure if references are variable. 00189 const MeasRef<M>& getMeasRef() const 00190 { return itsMeasRef; } 00191 00192 // Reset the refCode, offset, or units. 00193 // It overwrites the value used when defining the TableMeasDesc. 00194 // Resetting the refCode and offset can only be done if they were 00195 // defined as fixed in the description. 00196 // <note role=tip> 00197 // In principle the functions can only be used if the table is empty, 00198 // otherwise already written values have thereafter the incorrect 00199 // reference, offset, or unit. 00200 // However, it is possible that part of the table is already 00201 // written and that the entire measure column is filled in later. 00202 // In that case the reference, offset, or units can be set by using 00203 // a False <src>tableMustBeEmpty</src> argument. 00204 // </note> 00205 // <group> 00206 void setDescRefCode (uInt refCode, Bool tableMustBeEmpty=True); 00207 void setDescOffset (const Measure& offset, Bool tableMustBeEmpty=True); 00208 void setDescUnits (const Vector<Unit>& units, Bool tableMustBeEmpty=True); 00209 // </group> 00210 00211 // Put a Measure into the given row. 00212 // <group name=put> 00213 void put (uInt rownr, const M& meas); 00214 // </group> 00215 00216 protected: 00217 // Make a MeasRef for the given row. 00218 MeasRef<M> makeMeasRef (uInt rownr) const; 00219 00220 private: 00221 //# Whether conversion is needed during a put. True if either 00222 //# the reference code or offset is fixed for the column 00223 Bool itsConvFlag; 00224 //# Column which contains the Measure's actual data. An array column 00225 //# is needed if the data component of the underlying Measure is 00226 //# represented by more than 1 value 00227 ArrayColumn<Double>* itsArrDataCol; 00228 ScalarColumn<Double>* itsScaDataCol; 00229 //# Its MeasRef code column when references are variable. 00230 ScalarColumn<Int>* itsRefIntCol; 00231 ScalarColumn<String>* itsRefStrCol; 00232 //# Column containing its variable offsets. Only applicable if the 00233 //# measure references have offsets and they are variable. 00234 ScalarMeasColumn<M>* itsOffsetCol; 00235 //# This is either the column's fixed Measure reference or the reference 00236 //# of the last Measure read. 00237 MeasRef<M> itsMeasRef; 00238 00239 00240 // Assignment makes no sense in a readonly class. 00241 // Declaring this operator private makes it unusable. 00242 ScalarMeasColumn& operator= (const ScalarMeasColumn<M>& that); 00243 00244 // Check if refs have the same value (as opposed to being the same object). 00245 Bool equalRefs (const MRBase& r1, const MRBase& r2) const; 00246 00247 //# Deletes allocated memory etc. Called by ~tor and any member which 00248 //# needs to reallocate data. 00249 void cleanUp(); 00250 }; 00251 00252 00253 } //# NAMESPACE CASACORE - END 00254 00255 00256 //# Make old name ROScalarMeasColumn still available. 00257 #define ROScalarMeasColumn ScalarMeasColumn 00258 00259 00260 #ifndef CASACORE_NO_AUTO_TEMPLATES 00261 #include <casacore/measures/TableMeasures/ScalarMeasColumn.tcc> 00262 #endif //# CASACORE_NO_AUTO_TEMPLATES 00263 #endif