casacore
Loading...
Searching...
No Matches
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
36namespace casacore { //# NAMESPACE CASACORE - BEGIN
37
38//# Forward Declarations
39class TableMeasDescBase;
40class Measure;
41class Table;
42class TableDesc;
43class TableRecord;
44class 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{
147public:
148 // Constructor which defines a constant (non-variable) offset. All
149 // measures in the columns will have the same 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.
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.
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
199private:
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)
const Measure & getOffset() const
Get the (non-variable) measure offset for this column.
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.
static TableMeasOffsetDesc * reconstruct(const TableRecord &measInfo, const String &prefix, const Table &tab)
Reconstructs the TableMeasOffsetDesc from the measInfo TableRecord.
TableMeasOffsetDesc & operator=(const TableMeasOffsetDesc &that)
Assignment operator (copy semantics).
Bool isVariable() const
Returns True if the offset varies per row.
TableMeasOffsetDesc(const Measure &offset)
Constructor which defines a constant (non-variable) offset.
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