TableMeasOffsetDesc.h

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

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1