TableMeasOffsetDesc.h

Go to the documentation of this file.

// # TableMeasOffseDesc.h: Definition of an Offset 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_TABLEMEASOFFSETDESC_H
#define MEASURES_TABLEMEASOFFSETDESC_H
 
// # Includes
#include <casacore/casa/aips.h>
#include <casacore/casa/BasicSL/String.h>
#include <casacore/measures/Measures/MeasureHolder.h>
 
namespace casacore {  // # NAMESPACE CASACORE - BEGIN
 
// # Forward Declarations
class TableMeasDescBase;
class Measure;
class Table;
class TableDesc;
class TableRecord;
class String;
 
// <summary>
// Definition of a Measure Offset 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>
//   <li> <linkto class=TableMeasDesc>TableMeasDesc</linkto>
// </prerequisite>
 
// <synopsis>
// This class assists in the definition of the offset component of a
// TableMeasDesc
// in the TableMeasures system.  Four possibilities exist for specifying the
// handling of measure offsets in a Measure column.  These are:
//
// <ul>
//   <li> an offset is not used
//   <li> all measures in the column have the same offset
//   <li> a unique (and probably different) offset is stored for each row
//   <li> a unique offset is stored in each array element per (Array)column
//  row
// </ul>
//
// Note that this last option is only relevant when using ArrayMeasColumns.
//
// Examples of each of these follow.
// </synopsis>
 
// <example>
//<ol>
// <li>Specifying a single fixed offset.  Note that a Measure offset is itself
// a measure
// <srcblock>
//    // create an MEpoch to use as the offset in an MEpoch column
//    MEpoch offset(MVEpoch(MVTime(1996, 5, 17, (8+18./60.)/24.)), MEpoch::UTC);
//    TableMeasOffsetDesc offsetDesc(offset);
// </srcblock>
//
// <li>Storing an offset per row needs an offset column.  Measure offsets are
// Measures so a Measure column is needed:
// <srcblock>
//    // Need a column for the offsets.  This is to be a Measure column,
//    // so the rules for creating a Measure column apply.
//    ArrayColumnDesc<Double> cdOffset("OffsetCol", "Variable Offset col");
//    ...
//    // add the column to the table
//    td.addColumn(cdOffset);
//    ...
//    // Create the Measure column to be used as the measure offset column
//    TableMeasValueDesc valDesc(td, "OffsetCol");
//    TableMeasDesc<MEpoch> offset(valDesc);
//    // Create the offset descriptor
//    TableMeasOffsetDesc offsetDesc(offset);
//
// </srcblock>
//
// <li>Storing an offset per array element per row requires one change in the
// constructor used in the previous example:
// <srcblock>
//    ...
//    // set up column and TableMeasDesc as before
//    ...
//    // Setting the asArray parameter to True in the constructor specifies
//    // per element offset storage
//    TableMeasOffsetDesc offsetDesc(offset, True);
// </srcblock>
// </ol>
//
// For an example of the use of the TableMeasOffsetDesc class in the context
// of a full TableMeasDesc declaration see class
// <linkto class="TableMeasDesc">TableMeasDesc</linkto>.
// </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 during reconstruction of non-variable offset if a
//    component of the offset measure is missing in the column keywords or
//    is corrupt in some way.
//    <li>AipsError if getOffset() called on a variable offset object.
//    <li>AipsError during a reconstruct if the column doesn't have a Unit.
// </thrown>
//
// # <todo asof="$DATE:$">
// # A List of bugs, limitations, extensions or planned refinements.
// # </todo>
 
class TableMeasOffsetDesc {
 public:
  // Constructor which defines a constant (non-variable) offset.  All
  // measures in the columns will have the same offset.
  TableMeasOffsetDesc(const Measure& offset);
 
  // Constructor for defining a variable offset.  If asArray is True then
  // the offset is stored per array element.  The default is for the
  // offset to be stored (and hence variable) per row.
  TableMeasOffsetDesc(const TableMeasDescBase& offsetColumn, Bool asArray = False);
 
  // Copy constructor (copy semantics).
  TableMeasOffsetDesc(const TableMeasOffsetDesc& that);
 
  ~TableMeasOffsetDesc();
 
  // Assignment operator (copy semantics).
  TableMeasOffsetDesc& operator=(const TableMeasOffsetDesc& that);
 
  // Reconstructs the TableMeasOffsetDesc from the measInfo TableRecord.
  static TableMeasOffsetDesc* reconstruct(const TableRecord& measInfo, const String& prefix,
                                          const Table& tab);
 
  // Get the (non-variable) measure offset for this column.  If it doesn't
  // exist (thus if the offset is variable), an exception is thrown.
  const Measure& getOffset() const;
 
  // Returns True if the offset varies per row.
  Bool isVariable() const { return (itsTMDesc != 0); }
 
  // Returns True if the offset varies per array element.
  Bool isArray() const { return (isVariable() && itsVarPerArr); }
 
  // Gets the name of the column which stores the variable offset.
  // "" is returned if the offset is not variable.
  const String& columnName() const { return itsVarColName; }
 
  // Reset the offset.
  // It overwrites the value used when defining the TableMeasDesc.
  // It is only possible if it was defined as fixed for the entire column.
  void resetOffset(const Measure& offset);
 
  // Write the information into the record.
  // <group>
  void write(TableDesc&, TableRecord& measInfo, const String& prefix);
  void write(Table&, TableRecord& measInfo, const String& prefix);
  // </group>
 
 private:
  TableMeasDescBase* itsTMDesc;  // # Stores variable offset if applicable
  MeasureHolder itsMeasure;      // # The offset if non-variable.
  String itsVarColName;          // # "" if offset non-variable.
  Bool itsVarPerArr;             // # Is variable per array element.
 
  // Constructor which uses the measInfo TableRecord.
  TableMeasOffsetDesc(const TableRecord& measInfo, const String& prefix, const Table&);
 
  // Write the actual keywords.
  void writeKeys(TableRecord& measInfo, const String& prefix);
};
 
}  // namespace casacore
 
#endif