00001 //# TableMeasOffseDesc.h: Definition of an Offset 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_TABLEMEASOFFSETDESC_H 00029 #define MEASURES_TABLEMEASOFFSETDESC_H 00030 00031 //# Includes 00032 #include <casacore/casa/aips.h> 00033 #include <casacore/casa/BasicSL/String.h> 00034 #include <casacore/measures/Measures/MeasureHolder.h> 00035 00036 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00037 00038 //# Forward Declarations 00039 class TableMeasDescBase; 00040 class Measure; 00041 class Table; 00042 class TableDesc; 00043 class TableRecord; 00044 class String; 00045 00046 00047 // <summary> 00048 // Definition of a Measure Offset in a Table. 00049 // </summary> 00050 00051 // <use visibility=export> 00052 00053 // <reviewed reviewer="Bob Garwood" date="1999/12/23" tests="tTableMeasures.cc"> 00054 // </reviewed> 00055 00056 // <prerequisite> 00057 //# Classes you should understand before using this one. 00058 // <li> <linkto module=Measures>Measures</linkto> 00059 // <li> <linkto module=Tables>Tables</linkto> 00060 // <li> <linkto class=TableMeasDesc>TableMeasDesc</linkto> 00061 // </prerequisite> 00062 00063 // <synopsis> 00064 // This class assists in the definition of the offset component of a 00065 // TableMeasDesc 00066 // in the TableMeasures system. Four possibilities exist for specifying the 00067 // handling of measure offsets in a Measure column. These are: 00068 // 00069 // <ul> 00070 // <li> an offset is not used 00071 // <li> all measures in the column have the same offset 00072 // <li> a unique (and probably different) offset is stored for each row 00073 // <li> a unique offset is stored in each array element per (Array)column 00074 // row 00075 // </ul> 00076 // 00077 // Note that this last option is only relevant when using ArrayMeasColumns. 00078 // 00079 // Examples of each of these follow. 00080 // </synopsis> 00081 00082 // <example> 00083 //<ol> 00084 // <li>Specifying a single fixed offset. Note that a Measure offset is itself 00085 // a measure 00086 // <srcblock> 00087 // // create an MEpoch to use as the offset in an MEpoch column 00088 // MEpoch offset(MVEpoch(MVTime(1996, 5, 17, (8+18./60.)/24.)), MEpoch::UTC); 00089 // TableMeasOffsetDesc offsetDesc(offset); 00090 // </srcblock> 00091 // 00092 // <li>Storing an offset per row needs an offset column. Measure offsets are 00093 // Measures so a Measure column is needed: 00094 // <srcblock> 00095 // // Need a column for the offsets. This is to be a Measure column, 00096 // // so the rules for creating a Measure column apply. 00097 // ArrayColumnDesc<Double> cdOffset("OffsetCol", "Variable Offset col"); 00098 // ... 00099 // // add the column to the table 00100 // td.addColumn(cdOffset); 00101 // ... 00102 // // Create the Measure column to be used as the measure offset column 00103 // TableMeasValueDesc valDesc(td, "OffsetCol"); 00104 // TableMeasDesc<MEpoch> offset(valDesc); 00105 // // Create the offset descriptor 00106 // TableMeasOffsetDesc offsetDesc(offset); 00107 // 00108 // </srcblock> 00109 // 00110 // <li>Storing an offset per array element per row requires one change in the 00111 // constructor used in the previous example: 00112 // <srcblock> 00113 // ... 00114 // // set up column and TableMeasDesc as before 00115 // ... 00116 // // Setting the asArray parameter to True in the constructor specifies 00117 // // per element offset storage 00118 // TableMeasOffsetDesc offsetDesc(offset, True); 00119 // </srcblock> 00120 // </ol> 00121 // 00122 // For an example of the use of the TableMeasOffsetDesc class in the context 00123 // of a full TableMeasDesc declaration see class 00124 // <linkto class="TableMeasDesc">TableMeasDesc</linkto>. 00125 // </example> 00126 00127 // <motivation> 00128 // Creating the required keyword for the definition of a Measure 00129 // in a Table is somewhat complicated. This class assists in that 00130 // process. 00131 // </motivation> 00132 // 00133 // <thrown> 00134 // <li>AipsError during reconstruction of non-variable offset if a 00135 // component of the offset measure is missing in the column keywords or 00136 // is corrupt in some way. 00137 // <li>AipsError if getOffset() called on a variable offset object. 00138 // <li>AipsError during a reconstruct if the column doesn't have a Unit. 00139 // </thrown> 00140 // 00141 //# <todo asof="$DATE:$"> 00142 //# A List of bugs, limitations, extensions or planned refinements. 00143 //# </todo> 00144 00145 class TableMeasOffsetDesc 00146 { 00147 public: 00148 // Constructor which defines a constant (non-variable) offset. All 00149 // measures in the columns will have the same offset. 00150 TableMeasOffsetDesc (const Measure& offset); 00151 00152 // Constructor for defining a variable offset. If asArray is True then 00153 // the offset is stored per array element. The default is for the 00154 // offset to be stored (and hence variable) per row. 00155 TableMeasOffsetDesc (const TableMeasDescBase& offsetColumn, 00156 Bool asArray=False); 00157 00158 // Copy constructor (copy semantics). 00159 TableMeasOffsetDesc (const TableMeasOffsetDesc& that); 00160 00161 ~TableMeasOffsetDesc(); 00162 00163 // Assignment operator (copy semantics). 00164 TableMeasOffsetDesc& operator= (const TableMeasOffsetDesc& that); 00165 00166 // Reconstructs the TableMeasOffsetDesc from the measInfo TableRecord. 00167 static TableMeasOffsetDesc* reconstruct (const TableRecord& measInfo, 00168 const String& prefix, 00169 const Table& tab); 00170 00171 // Get the (non-variable) measure offset for this column. If it doesn't 00172 // exist (thus if the offset is variable), an exception is thrown. 00173 const Measure& getOffset() const; 00174 00175 // Returns True if the offset varies per row. 00176 Bool isVariable() const 00177 { return (itsTMDesc != 0); } 00178 00179 // Returns True if the offset varies per array element. 00180 Bool isArray() const 00181 { return (isVariable() && itsVarPerArr); } 00182 00183 // Gets the name of the column which stores the variable offset. 00184 // "" is returned if the offset is not variable. 00185 const String& columnName() const 00186 { return itsVarColName; } 00187 00188 // Reset the offset. 00189 // It overwrites the value used when defining the TableMeasDesc. 00190 // It is only possible if it was defined as fixed for the entire column. 00191 void resetOffset (const Measure& offset); 00192 00193 // Write the information into the record. 00194 // <group> 00195 void write (TableDesc&, TableRecord& measInfo, const String& prefix); 00196 void write (Table&, TableRecord& measInfo, const String& prefix); 00197 // </group> 00198 00199 private: 00200 TableMeasDescBase* itsTMDesc; //# Stores variable offset if applicable 00201 MeasureHolder itsMeasure; //# The offset if non-variable. 00202 String itsVarColName; //# "" if offset non-variable. 00203 Bool itsVarPerArr; //# Is variable per array element. 00204 00205 00206 // Constructor which uses the measInfo TableRecord. 00207 TableMeasOffsetDesc (const TableRecord& measInfo, const String& prefix, 00208 const Table&); 00209 00210 // Write the actual keywords. 00211 void writeKeys (TableRecord& measInfo, const String& prefix); 00212 }; 00213 00214 00215 00216 } //# NAMESPACE CASACORE - END 00217 00218 #endif