ScalarMeasColumn.h

Go to the documentation of this file.
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
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1