casacore
TableMeasOffsetDesc.h
Go to the documentation of this file.
1 //# TableMeasOffseDesc.h: Definition of an Offset measure in a Table.
2 //# Copyright (C) 1997,1999,2000,2001
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 #ifndef MEASURES_TABLEMEASOFFSETDESC_H
29 #define MEASURES_TABLEMEASOFFSETDESC_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/casa/BasicSL/String.h>
34 #include <casacore/measures/Measures/MeasureHolder.h>
35 
36 namespace casacore { //# NAMESPACE CASACORE - BEGIN
37 
38 //# Forward Declarations
39 class TableMeasDescBase;
40 class Measure;
41 class Table;
42 class TableDesc;
43 class TableRecord;
44 class String;
45 
46 
47 // <summary>
48 // Definition of a Measure Offset in a Table.
49 // </summary>
50 
51 // <use visibility=export>
52 
53 // <reviewed reviewer="Bob Garwood" date="1999/12/23" tests="tTableMeasures.cc">
54 // </reviewed>
55 
56 // <prerequisite>
57 //# Classes you should understand before using this one.
58 // <li> <linkto module=Measures>Measures</linkto>
59 // <li> <linkto module=Tables>Tables</linkto>
60 // <li> <linkto class=TableMeasDesc>TableMeasDesc</linkto>
61 // </prerequisite>
62 
63 // <synopsis>
64 // This class assists in the definition of the offset component of a
65 // TableMeasDesc
66 // in the TableMeasures system. Four possibilities exist for specifying the
67 // handling of measure offsets in a Measure column. These are:
68 //
69 // <ul>
70 // <li> an offset is not used
71 // <li> all measures in the column have the same offset
72 // <li> a unique (and probably different) offset is stored for each row
73 // <li> a unique offset is stored in each array element per (Array)column
74 // row
75 // </ul>
76 //
77 // Note that this last option is only relevant when using ArrayMeasColumns.
78 //
79 // Examples of each of these follow.
80 // </synopsis>
81 
82 // <example>
83 //<ol>
84 // <li>Specifying a single fixed offset. Note that a Measure offset is itself
85 // a measure
86 // <srcblock>
87 // // create an MEpoch to use as the offset in an MEpoch column
88 // MEpoch offset(MVEpoch(MVTime(1996, 5, 17, (8+18./60.)/24.)), MEpoch::UTC);
89 // TableMeasOffsetDesc offsetDesc(offset);
90 // </srcblock>
91 //
92 // <li>Storing an offset per row needs an offset column. Measure offsets are
93 // Measures so a Measure column is needed:
94 // <srcblock>
95 // // Need a column for the offsets. This is to be a Measure column,
96 // // so the rules for creating a Measure column apply.
97 // ArrayColumnDesc<Double> cdOffset("OffsetCol", "Variable Offset col");
98 // ...
99 // // add the column to the table
100 // td.addColumn(cdOffset);
101 // ...
102 // // Create the Measure column to be used as the measure offset column
103 // TableMeasValueDesc valDesc(td, "OffsetCol");
104 // TableMeasDesc<MEpoch> offset(valDesc);
105 // // Create the offset descriptor
106 // TableMeasOffsetDesc offsetDesc(offset);
107 //
108 // </srcblock>
109 //
110 // <li>Storing an offset per array element per row requires one change in the
111 // constructor used in the previous example:
112 // <srcblock>
113 // ...
114 // // set up column and TableMeasDesc as before
115 // ...
116 // // Setting the asArray parameter to True in the constructor specifies
117 // // per element offset storage
118 // TableMeasOffsetDesc offsetDesc(offset, True);
119 // </srcblock>
120 // </ol>
121 //
122 // For an example of the use of the TableMeasOffsetDesc class in the context
123 // of a full TableMeasDesc declaration see class
124 // <linkto class="TableMeasDesc">TableMeasDesc</linkto>.
125 // </example>
126 
127 // <motivation>
128 // Creating the required keyword for the definition of a Measure
129 // in a Table is somewhat complicated. This class assists in that
130 // process.
131 // </motivation>
132 //
133 // <thrown>
134 // <li>AipsError during reconstruction of non-variable offset if a
135 // component of the offset measure is missing in the column keywords or
136 // is corrupt in some way.
137 // <li>AipsError if getOffset() called on a variable offset object.
138 // <li>AipsError during a reconstruct if the column doesn't have a Unit.
139 // </thrown>
140 //
141 //# <todo asof="$DATE:$">
142 //# A List of bugs, limitations, extensions or planned refinements.
143 //# </todo>
144 
146 {
147 public:
148  // Constructor which defines a constant (non-variable) offset. All
149  // measures in the columns will have the same offset.
150  TableMeasOffsetDesc (const Measure& offset);
151 
152  // Constructor for defining a variable offset. If asArray is True then
153  // the offset is stored per array element. The default is for the
154  // offset to be stored (and hence variable) per row.
156  Bool asArray=False);
157 
158  // Copy constructor (copy semantics).
160 
162 
163  // Assignment operator (copy semantics).
165 
166  // Reconstructs the TableMeasOffsetDesc from the measInfo TableRecord.
167  static TableMeasOffsetDesc* reconstruct (const TableRecord& measInfo,
168  const String& prefix,
169  const Table& tab);
170 
171  // Get the (non-variable) measure offset for this column. If it doesn't
172  // exist (thus if the offset is variable), an exception is thrown.
173  const Measure& getOffset() const;
174 
175  // Returns True if the offset varies per row.
176  Bool isVariable() const
177  { return (itsTMDesc != 0); }
178 
179  // Returns True if the offset varies per array element.
180  Bool isArray() const
181  { return (isVariable() && itsVarPerArr); }
182 
183  // Gets the name of the column which stores the variable offset.
184  // "" is returned if the offset is not variable.
185  const String& columnName() const
186  { return itsVarColName; }
187 
188  // Reset the offset.
189  // It overwrites the value used when defining the TableMeasDesc.
190  // It is only possible if it was defined as fixed for the entire column.
191  void resetOffset (const Measure& offset);
192 
193  // Write the information into the record.
194  // <group>
195  void write (TableDesc&, TableRecord& measInfo, const String& prefix);
196  void write (Table&, TableRecord& measInfo, const String& prefix);
197  // </group>
198 
199 private:
200  TableMeasDescBase* itsTMDesc; //# Stores variable offset if applicable
201  MeasureHolder itsMeasure; //# The offset if non-variable.
202  String itsVarColName; //# "" if offset non-variable.
203  Bool itsVarPerArr; //# Is variable per array element.
204 
205 
206  // Constructor which uses the measInfo TableRecord.
207  TableMeasOffsetDesc (const TableRecord& measInfo, const String& prefix,
208  const Table&);
209 
210  // Write the actual keywords.
211  void writeKeys (TableRecord& measInfo, const String& prefix);
212 };
213 
214 
215 
216 } //# NAMESPACE CASACORE - END
217 
218 #endif
String: the storage and methods of handling collections of characters.
Definition: String.h:225
TableMeasOffsetDesc(const TableMeasDescBase &offsetColumn, Bool asArray=False)
Constructor for defining a variable offset.
void resetOffset(const Measure &offset)
Reset the offset.
const String & columnName() const
Gets the name of the column which stores the variable offset.
void write(Table &, TableRecord &measInfo, const String &prefix)
void writeKeys(TableRecord &measInfo, const String &prefix)
Write the actual keywords.
TableMeasOffsetDesc(const TableMeasOffsetDesc &that)
Copy constructor (copy semantics).
TableMeasOffsetDesc(const TableRecord &measInfo, const String &prefix, const Table &)
Constructor which uses the measInfo TableRecord.
Bool isArray() const
Returns True if the offset varies per array element.
void write(TableDesc &, TableRecord &measInfo, const String &prefix)
Write the information into the record.
Bool isVariable() const
Returns True if the offset varies per row.
const Measure & getOffset() const
Get the (non-variable) measure offset for this column.
TableMeasOffsetDesc & operator=(const TableMeasOffsetDesc &that)
Assignment operator (copy semantics).
TableMeasOffsetDesc(const Measure &offset)
Constructor which defines a constant (non-variable) offset.
static TableMeasOffsetDesc * reconstruct(const TableRecord &measInfo, const String &prefix, const Table &tab)
Reconstructs the TableMeasOffsetDesc from the measInfo TableRecord.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
const Bool False
Definition: aipstype.h:44
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42