TableMeasDesc.h

Go to the documentation of this file.

// # TableMeasDesc.h: Definition of a Measure in a Table.
// # Copyright (C) 1997,1999,2000,2001
// # Associated Universities, Inc. Washington DC, USA.
// #
// # This library is free software; you can redistribute it and/or modify it
// # under the terms of the GNU Library General Public License as published by
// # the Free Software Foundation; either version 2 of the License, or (at your
// # option) any later version.
// #
// # This library is distributed in the hope that it will be useful, but WITHOUT
// # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
// # FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
// # License for more details.
// #
// # You should have received a copy of the GNU Library General Public License
// # along with this library; if not, write to the Free Software Foundation,
// # Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
// #
// # Correspondence concerning AIPS++ should be addressed as follows:
// #        Internet email: casa-feedback@nrao.edu.
// #        Postal address: AIPS++ Project Office
// #                        National Radio Astronomy Observatory
// #                        520 Edgemont Road
// #                        Charlottesville, VA 22903-2475 USA
 
#ifndef MEASURES_TABLEMEASDESC_H
#define MEASURES_TABLEMEASDESC_H
 
// # Includes
#include <casacore/casa/aips.h>
#include <casacore/measures/TableMeasures/TableMeasDescBase.h>
 
namespace casacore {  // # NAMESPACE CASACORE - BEGIN
 
// # Forward Declarations
class String;
class Table;
class TableMeasRefDesc;
class TableMeasValueDesc;
 
// <summary>
// Definition of a Measure column in a Table.
// </summary>
 
// <use visibility=export>
 
// <reviewed reviewer="Bob Garwood" date="1999/12/23" tests="tTableMeasures.cc">
// </reviewed>
 
// <prerequisite>
// # Classes you should understand before using this one.
//   <li> <linkto module=Measures>Measures</linkto>
//   <li> <linkto module=Tables>Tables</linkto>
// </prerequisite>
 
// <synopsis>
// The TableMeasures system was created to add support for Measure
// columns to the Casacore Table system.
// Measures are not a fundamental type of the Tables system and hence
// cannot be represented directly.  Instead a Measure column can be created
// with the aid of
// the TableMeasDesc class hierarchy.  The TableMeasDesc class hierarchy
// creates a Measure column by associating some number of fundamental data
// type Table
// columns into a unit.  The associations between these columns
// is represented in the column keywords of each of
// the columns which make up a specific Measure column.
//
// Creating and using Measure columns
// is a three step process:
// <ol>
// <li> For each Measure column some number of columns are defined and added
//      to the Table descriptor.
// <li> A TableMeasDesc object is used to define a (empty) Measure column
//      from the columns created in the first step.
// <li> <linkto class="ScalarMeasColumn">(RO)ScalarMeasColumns</linkto> or
//  <linkto class="ArrayMeasColumn">(RO)ArrayMeasColumns</linkto> objects
//   are used to access the Measure column for the reading and writing
//   of Measures.
// </ol>
//
// Defining a Measure column (that is, steps 1 and 2 above) is the more complex
// operation.  However, for each Measure column it is a once only operation.
// After a Measure column has been created its subsequent use is not
// much different to using "ordinary" Table columns. For information
// on how to use a Measure column see the
// <linkto class="ScalarMeasColumn">(RO)ScalarMeasColumns</linkto> and
// <linkto class="ArrayMeasColumn">(RO)ArrayMeasColumns</linkto> classes.
// <p>
// The TableMeasDesc class hierarchy contains classes for defining each
// component of the Measures to be contained in column.  A
// <linkto class="TableMeasOffsetDesc">TableMeasOffsetDesc</linkto> is used
// to specify the offset component, a
// <linkto class="TableMeasRefDesc">TableMeasRefDesc</linkto> to set up
// the reference code component and a
// <linkto class="TableMeasValueDesc">TableMeasValueDesc</linkto> names the
// column used as the main Measure column through which the
// Measure column is subsequently accessed.
// <br>
// The final step needed to create a Measure column is the creation of a
// TableMeasDesc object whose
// constructor takes a TableMeasValueDesc and (optionally) a
// TableMeasRefDesc.   After construction the TableMeasDesc object's
// write() member is used to make the
// the Measure column persistent within the Table.
// <p>
// The following examples demonstrate the creation of Measure columns using
// the above components.  Further details about each of these components
// is available with each class description.
// <br>
// All examples write the measure description into a TableDesc object,
// i.e. the argument used in the TableMeasDesc::write function is a
// TableDesc object. It is, however, also possible to write them
// into a Table object which is useful if measure columns are added
// to an already existing table (see example 2).
// </synopsis>
 
// <example>
//<ol>
// <li> The following creates a MEpoch column with a fixed reference.
// <srcblock>
//    // Need a table to work with.
//    TableDesc td("measureTable_desc", "1", TableDesc::New);
//    td.comment() = "A test of TableMeasures class.";
//
//    // Define a column and add it to the table
//    // The main measure column is always an Array column of type Double
//    ArrayColumnDesc<Double> cdTime("Time", "An MEpoch column");
//    td.addColumn(cdtime);
//
//    // Create the Measure column for an MEpoch.  The MEpoch in
//    // the column has reference code MEpoch::TAI
//    TableMeasRefDesc measRef(MEpoch::TAI);
//    TableMeasValueDesc measVal(td, "Time");
//    TableMeasDesc<MEpoch> mepochCol(measVal, measRef);
//    // write makes the Measure column persistent.
//    mepochCol.write(td);
//
//    // create the table with 5 rows
//    SetupNewTable newtab("MeasuresTable", td, Table::New);
//    Table tab(newtab, 5);
// </srcblock>
 
// <li> Same as example above, but for an already existing table.
// <srcblock>
//    // Need a table to work with.
//    TableDesc td("measureTable_desc", "1", TableDesc::New);
//    td.comment() = "A test of TableMeasures class.";
//
//    // Define a column and add it to the table
//    // The main measure column is always an Array column of type Double
//    ArrayColumnDesc<Double> cdTime("Time", "An MEpoch column");
//    td.addColumn(cdtime);
//
//    // create the table with 5 rows
//    SetupNewTable newtab("MeasuresTable", td, Table::New);
//    Table tab(newtab, 5);
//
//    // Create the Measure column for an MEpoch.  The MEpoch in
//    // the column has reference code MEpoch::TAI
//    TableMeasRefDesc measRef(MEpoch::TAI);
//    TableMeasValueDesc measVal(tab.tableDesc(), "Time");
//    TableMeasDesc<MEpoch> mepochCol(measVal, measRef);
//    // write makes the Measure column persistent.
//    mepochCol.write(tab);
// </srcblock>
 
// <li> An MEpoch column with a variable reference code with a fixed offset:
// <srcblock>
//    // The following three columns will be used to set up a Scalar MEpoch
//    // column with variable references and offsets.  3 columns are needed.
//    // The "main" column where the MEpoch will be stored
//    ArrayColumnDesc<Double> cdTime("Time", "An MEpoch column");
 
//    // Variable (i.e., per row) reference code storage needs a column.
//    // The column type is either Int or String (Int is faster but String
//    // may be useful when browsing the table).  Either a Scalar column or
//    // Array column can be used here dependent on whether a Scalar or
//    // Array Measure column is used and whether in case of an Array Measure
//    // column the reference code has to be variable per array element.
//    ScalarColumnDesc<Int> cdRef("TimeRef", "Reference column for Time");
//
//    // add the columns to the Table decriptor
//    td.addColumn(cdTime);
//    td.addColumn(cdRef);
//
//    // now create the MEpoch column.
//    // want a fixed offset.  Offsets are Measures
//    MEpoch offset(MVEpoch(MVTime(1996, 5, 17), MEpoch::UTC);
//    TableMeasOffsetDesc offsetDesc(offset);
//    // the reference
//    TableMeasRefDesc measRef(td, "TimeRef", offsetDesc);
//    // the value descriptor, create and write the column
//    TableMeasValueDesc measVal(td, "Time");
//    TableMeasDesc<MEpoch> mepochCol(measVal, measRef);
//    mepochCol.write();
//
//    // create the table, etc
//    ...
// </srcblock>
//
// <li> An MEpoch column with a variable reference code and offset
// <srcblock>
//    // Variable (per row storage of) offsets needs its own column. Measure
//    // offsets are Measures therefore a Measure column is needed.
//    ArrayColumnDesc<Double> cdOffset("OffsetCol", "Variable Offset col");
//
//    // A column for the variable reference code
//    ScalarColumnDesc<String> cdRef("RefCol", "Variable reference column");
//
//    // The main (value) column for the Measure column
//    ArrayColumnDesc<Double> cdTime("Time", "MEpoch column");
//
//    // add the column descriptors to the table
//    td.addColumn(cdOffset);
//    td.addColumn(cdRef);
//    td.addColumn(cdTime);
//
//    // Create the Measure column
//
//    // The offset column is itself a Measure column, but write() is not
//    // called
//    TableMeasValueDesc offsetVal(td, "OffsetCol");
//    TableMeasDesc<MEpoch> offset(offsetVal);
//    TableMeasOffsetDesc offsetDesc(offset);
//
//    // the reference
//    TableMeasRefDesc ref(td, "RefCol", offsetDesc);
//
//    // create the Measure column
//    TableMeasValueDesc val(td, "Time");
//    TableMeasDesc<MEpoch> mepochCol(val, ref);
//    mepochCol.write();
 
//    // create the table, etc
//    ...
// </srcblock>
//</ol>
// </example>
 
// <motivation>
// Creating the required keyword for the definition of a Measure
// in a Table is somewhat complicated. This class assists in that
// process.
// </motivation>
//
// <thrown>
//    <li>AipsError if a reference code string is invalid.
// </thrown>
//
// # <todo asof="$DATE:$">
// # A List of bugs, limitations, extensions or planned refinements.
// # </todo>
 
template <class M>
class TableMeasDesc : public TableMeasDescBase {
 public:
  // Constructor with measure value descriptor.  The Measure reference for
  // the column will be the default reference code for M.  Units for the
  // column will be the default for the Measure type.
  TableMeasDesc(const TableMeasValueDesc&);
 
  // Constructor with measure value descriptor and Vector of Units.
  // The Measure reference for the column will be the default reference
  // code for the Measure type.   Number of Units must be compatible
  // with the Measure.
  TableMeasDesc(const TableMeasValueDesc&, const Vector<Unit>&);
 
  // Constructor with value and reference descriptors. Units for the
  // column will be the default for Measure type.
  TableMeasDesc(const TableMeasValueDesc&, const TableMeasRefDesc&);
 
  // Constructor with value and reference descriptors and Vector of
  // Units. Number of Units must be compatible with the Measure.
  TableMeasDesc(const TableMeasValueDesc&, const TableMeasRefDesc&, const Vector<Unit>&);
 
  // Clone the object.
  virtual TableMeasDescBase* clone() const;
 
  // Copy constructor (copy semantics).
  TableMeasDesc(const TableMeasDesc<M>& that);
 
  ~TableMeasDesc();
 
  // Assignment operator (copy semantics)
  TableMeasDesc<M>& operator=(const TableMeasDesc<M>& that);
};
 
}  // namespace casacore
 
#ifndef CASACORE_NO_AUTO_TEMPLATES
#include <casacore/measures/TableMeasures/TableMeasDesc.tcc>
#endif  // # CASACORE_NO_AUTO_TEMPLATES
#endif