00001 //# TableMeasDesc.h: Definition of a Measure in a Table. 00002 //# Copyright (C) 1997,1999,2000,2001 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_TABLEMEASDESC_H 00029 #define MEASURES_TABLEMEASDESC_H 00030 00031 00032 //# Includes 00033 #include <casacore/casa/aips.h> 00034 #include <casacore/measures/TableMeasures/TableMeasDescBase.h> 00035 00036 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00037 00038 //# Forward Declarations 00039 class String; 00040 class Table; 00041 class TableMeasRefDesc; 00042 class TableMeasValueDesc; 00043 00044 // <summary> 00045 // Definition of a Measure column in a Table. 00046 // </summary> 00047 00048 // <use visibility=export> 00049 00050 // <reviewed reviewer="Bob Garwood" date="1999/12/23" tests="tTableMeasures.cc"> 00051 // </reviewed> 00052 00053 // <prerequisite> 00054 //# Classes you should understand before using this one. 00055 // <li> <linkto module=Measures>Measures</linkto> 00056 // <li> <linkto module=Tables>Tables</linkto> 00057 // </prerequisite> 00058 00059 // <synopsis> 00060 // The TableMeasures system was created to add support for Measure 00061 // columns to the Casacore Table system. 00062 // Measures are not a fundamental type of the Tables system and hence 00063 // cannot be represented directly. Instead a Measure column can be created 00064 // with the aid of 00065 // the TableMeasDesc class hierarchy. The TableMeasDesc class hierarchy 00066 // creates a Measure column by associating some number of fundamental data 00067 // type Table 00068 // columns into a unit. The associations between these columns 00069 // is represented in the column keywords of each of 00070 // the columns which make up a specific Measure column. 00071 // 00072 // Creating and using Measure columns 00073 // is a three step process: 00074 // <ol> 00075 // <li> For each Measure column some number of columns are defined and added 00076 // to the Table descriptor. 00077 // <li> A TableMeasDesc object is used to define a (empty) Measure column 00078 // from the columns created in the first step. 00079 // <li> <linkto class="ScalarMeasColumn">(RO)ScalarMeasColumns</linkto> or 00080 // <linkto class="ArrayMeasColumn">(RO)ArrayMeasColumns</linkto> objects 00081 // are used to access the Measure column for the reading and writing 00082 // of Measures. 00083 // </ol> 00084 // 00085 // Defining a Measure column (that is, steps 1 and 2 above) is the more complex 00086 // operation. However, for each Measure column it is a once only operation. 00087 // After a Measure column has been created its subsequent use is not 00088 // much different to using "ordinary" Table columns. For information 00089 // on how to use a Measure column see the 00090 // <linkto class="ScalarMeasColumn">(RO)ScalarMeasColumns</linkto> and 00091 // <linkto class="ArrayMeasColumn">(RO)ArrayMeasColumns</linkto> classes. 00092 // <p> 00093 // The TableMeasDesc class hierarchy contains classes for defining each 00094 // component of the Measures to be contained in column. A 00095 // <linkto class="TableMeasOffsetDesc">TableMeasOffsetDesc</linkto> is used 00096 // to specify the offset component, a 00097 // <linkto class="TableMeasRefDesc">TableMeasRefDesc</linkto> to set up 00098 // the reference code component and a 00099 // <linkto class="TableMeasValueDesc">TableMeasValueDesc</linkto> names the 00100 // column used as the main Measure column through which the 00101 // Measure column is subsequently accessed. 00102 // <br> 00103 // The final step needed to create a Measure column is the creation of a 00104 // TableMeasDesc object whose 00105 // constructor takes a TableMeasValueDesc and (optionally) a 00106 // TableMeasRefDesc. After construction the TableMeasDesc object's 00107 // write() member is used to make the 00108 // the Measure column persistent within the Table. 00109 // <p> 00110 // The following examples demonstrate the creation of Measure columns using 00111 // the above components. Further details about each of these components 00112 // is available with each class description. 00113 // <br> 00114 // All examples write the measure description into a TableDesc object, 00115 // i.e. the argument used in the TableMeasDesc::write function is a 00116 // TableDesc object. It is, however, also possible to write them 00117 // into a Table object which is useful if measure columns are added 00118 // to an already existing table (see example 2). 00119 // </synopsis> 00120 00121 // <example> 00122 //<ol> 00123 // <li> The following creates a MEpoch column with a fixed reference. 00124 // <srcblock> 00125 // // Need a table to work with. 00126 // TableDesc td("measureTable_desc", "1", TableDesc::New); 00127 // td.comment() = "A test of TableMeasures class."; 00128 // 00129 // // Define a column and add it to the table 00130 // // The main measure column is always an Array column of type Double 00131 // ArrayColumnDesc<Double> cdTime("Time", "An MEpoch column"); 00132 // td.addColumn(cdtime); 00133 // 00134 // // Create the Measure column for an MEpoch. The MEpoch in 00135 // // the column has reference code MEpoch::TAI 00136 // TableMeasRefDesc measRef(MEpoch::TAI); 00137 // TableMeasValueDesc measVal(td, "Time"); 00138 // TableMeasDesc<MEpoch> mepochCol(measVal, measRef); 00139 // // write makes the Measure column persistent. 00140 // mepochCol.write(td); 00141 // 00142 // // create the table with 5 rows 00143 // SetupNewTable newtab("MeasuresTable", td, Table::New); 00144 // Table tab(newtab, 5); 00145 // </srcblock> 00146 00147 // <li> Same as example above, but for an already existing table. 00148 // <srcblock> 00149 // // Need a table to work with. 00150 // TableDesc td("measureTable_desc", "1", TableDesc::New); 00151 // td.comment() = "A test of TableMeasures class."; 00152 // 00153 // // Define a column and add it to the table 00154 // // The main measure column is always an Array column of type Double 00155 // ArrayColumnDesc<Double> cdTime("Time", "An MEpoch column"); 00156 // td.addColumn(cdtime); 00157 // 00158 // // create the table with 5 rows 00159 // SetupNewTable newtab("MeasuresTable", td, Table::New); 00160 // Table tab(newtab, 5); 00161 // 00162 // // Create the Measure column for an MEpoch. The MEpoch in 00163 // // the column has reference code MEpoch::TAI 00164 // TableMeasRefDesc measRef(MEpoch::TAI); 00165 // TableMeasValueDesc measVal(tab.tableDesc(), "Time"); 00166 // TableMeasDesc<MEpoch> mepochCol(measVal, measRef); 00167 // // write makes the Measure column persistent. 00168 // mepochCol.write(tab); 00169 // </srcblock> 00170 00171 // <li> An MEpoch column with a variable reference code with a fixed offset: 00172 // <srcblock> 00173 // // The following three columns will be used to set up a Scalar MEpoch 00174 // // column with variable references and offsets. 3 columns are needed. 00175 // // The "main" column where the MEpoch will be stored 00176 // ArrayColumnDesc<Double> cdTime("Time", "An MEpoch column"); 00177 00178 // // Variable (i.e., per row) reference code storage needs a column. 00179 // // The column type is either Int or String (Int is faster but String 00180 // // may be useful when browsing the table). Either a Scalar column or 00181 // // Array column can be used here dependent on whether a Scalar or 00182 // // Array Measure column is used and whether in case of an Array Measure 00183 // // column the reference code has to be variable per array element. 00184 // ScalarColumnDesc<Int> cdRef("TimeRef", "Reference column for Time"); 00185 // 00186 // // add the columns to the Table decriptor 00187 // td.addColumn(cdTime); 00188 // td.addColumn(cdRef); 00189 // 00190 // // now create the MEpoch column. 00191 // // want a fixed offset. Offsets are Measures 00192 // MEpoch offset(MVEpoch(MVTime(1996, 5, 17), MEpoch::UTC); 00193 // TableMeasOffsetDesc offsetDesc(offset); 00194 // // the reference 00195 // TableMeasRefDesc measRef(td, "TimeRef", offsetDesc); 00196 // // the value descriptor, create and write the column 00197 // TableMeasValueDesc measVal(td, "Time"); 00198 // TableMeasDesc<MEpoch> mepochCol(measVal, measRef); 00199 // mepochCol.write(); 00200 // 00201 // // create the table, etc 00202 // ... 00203 // </srcblock> 00204 // 00205 // <li> An MEpoch column with a variable reference code and offset 00206 // <srcblock> 00207 // // Variable (per row storage of) offsets needs its own column. Measure 00208 // // offsets are Measures therefore a Measure column is needed. 00209 // ArrayColumnDesc<Double> cdOffset("OffsetCol", "Variable Offset col"); 00210 // 00211 // // A column for the variable reference code 00212 // ScalarColumnDesc<String> cdRef("RefCol", "Variable reference column"); 00213 // 00214 // // The main (value) column for the Measure column 00215 // ArrayColumnDesc<Double> cdTime("Time", "MEpoch column"); 00216 // 00217 // // add the column descriptors to the table 00218 // td.addColumn(cdOffset); 00219 // td.addColumn(cdRef); 00220 // td.addColumn(cdTime); 00221 // 00222 // // Create the Measure column 00223 // 00224 // // The offset column is itself a Measure column, but write() is not 00225 // // called 00226 // TableMeasValueDesc offsetVal(td, "OffsetCol"); 00227 // TableMeasDesc<MEpoch> offset(offsetVal); 00228 // TableMeasOffsetDesc offsetDesc(offset); 00229 // 00230 // // the reference 00231 // TableMeasRefDesc ref(td, "RefCol", offsetDesc); 00232 // 00233 // // create the Measure column 00234 // TableMeasValueDesc val(td, "Time"); 00235 // TableMeasDesc<MEpoch> mepochCol(val, ref); 00236 // mepochCol.write(); 00237 00238 // // create the table, etc 00239 // ... 00240 // </srcblock> 00241 //</ol> 00242 // </example> 00243 00244 // <motivation> 00245 // Creating the required keyword for the definition of a Measure 00246 // in a Table is somewhat complicated. This class assists in that 00247 // process. 00248 // </motivation> 00249 // 00250 // <thrown> 00251 // <li>AipsError if a reference code string is invalid. 00252 // </thrown> 00253 // 00254 //# <todo asof="$DATE:$"> 00255 //# A List of bugs, limitations, extensions or planned refinements. 00256 //# </todo> 00257 00258 00259 template<class M> class TableMeasDesc : public TableMeasDescBase 00260 { 00261 public: 00262 // Constructor with measure value descriptor. The Measure reference for 00263 // the column will be the default reference code for M. Units for the 00264 // column will be the default for the Measure type. 00265 TableMeasDesc (const TableMeasValueDesc&); 00266 00267 // Constructor with measure value descriptor and Vector of Units. 00268 // The Measure reference for the column will be the default reference 00269 // code for the Measure type. Number of Units must be compatible 00270 // with the Measure. 00271 TableMeasDesc (const TableMeasValueDesc&, const Vector<Unit>&); 00272 00273 // Constructor with value and reference descriptors. Units for the 00274 // column will be the default for Measure type. 00275 TableMeasDesc (const TableMeasValueDesc&, const TableMeasRefDesc&); 00276 00277 // Constructor with value and reference descriptors and Vector of 00278 // Units. Number of Units must be compatible with the Measure. 00279 TableMeasDesc (const TableMeasValueDesc&, const TableMeasRefDesc&, 00280 const Vector<Unit>&); 00281 00282 // Clone the object. 00283 virtual TableMeasDescBase* clone() const; 00284 00285 // Copy constructor (copy semantics). 00286 TableMeasDesc (const TableMeasDesc<M>& that); 00287 00288 ~TableMeasDesc(); 00289 00290 // Assignment operator (copy semantics) 00291 TableMeasDesc<M>& operator= (const TableMeasDesc<M>& that); 00292 }; 00293 00294 00295 00296 } //# NAMESPACE CASACORE - END 00297 00298 #ifndef CASACORE_NO_AUTO_TEMPLATES 00299 #include <casacore/measures/TableMeasures/TableMeasDesc.tcc> 00300 #endif //# CASACORE_NO_AUTO_TEMPLATES 00301 #endif