casacore
Loading...
Searching...
No Matches
TableMeasDesc.h
Go to the documentation of this file.
1//# TableMeasDesc.h: Definition of a 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_TABLEMEASDESC_H
29#define MEASURES_TABLEMEASDESC_H
30
31
32//# Includes
33#include <casacore/casa/aips.h>
34#include <casacore/measures/TableMeasures/TableMeasDescBase.h>
35
36namespace casacore { //# NAMESPACE CASACORE - BEGIN
37
38//# Forward Declarations
39class String;
40class Table;
41class TableMeasRefDesc;
42class TableMeasValueDesc;
43
44// <summary>
45// Definition of a Measure column in a Table.
46// </summary>
47
48// <use visibility=export>
49
50// <reviewed reviewer="Bob Garwood" date="1999/12/23" tests="tTableMeasures.cc">
51// </reviewed>
52
53// <prerequisite>
54//# Classes you should understand before using this one.
55// <li> <linkto module=Measures>Measures</linkto>
56// <li> <linkto module=Tables>Tables</linkto>
57// </prerequisite>
58
59// <synopsis>
60// The TableMeasures system was created to add support for Measure
61// columns to the Casacore Table system.
62// Measures are not a fundamental type of the Tables system and hence
63// cannot be represented directly. Instead a Measure column can be created
64// with the aid of
65// the TableMeasDesc class hierarchy. The TableMeasDesc class hierarchy
66// creates a Measure column by associating some number of fundamental data
67// type Table
68// columns into a unit. The associations between these columns
69// is represented in the column keywords of each of
70// the columns which make up a specific Measure column.
71//
72// Creating and using Measure columns
73// is a three step process:
74// <ol>
75// <li> For each Measure column some number of columns are defined and added
76// to the Table descriptor.
77// <li> A TableMeasDesc object is used to define a (empty) Measure column
78// from the columns created in the first step.
79// <li> <linkto class="ScalarMeasColumn">(RO)ScalarMeasColumns</linkto> or
80// <linkto class="ArrayMeasColumn">(RO)ArrayMeasColumns</linkto> objects
81// are used to access the Measure column for the reading and writing
82// of Measures.
83// </ol>
84//
85// Defining a Measure column (that is, steps 1 and 2 above) is the more complex
86// operation. However, for each Measure column it is a once only operation.
87// After a Measure column has been created its subsequent use is not
88// much different to using "ordinary" Table columns. For information
89// on how to use a Measure column see the
90// <linkto class="ScalarMeasColumn">(RO)ScalarMeasColumns</linkto> and
91// <linkto class="ArrayMeasColumn">(RO)ArrayMeasColumns</linkto> classes.
92// <p>
93// The TableMeasDesc class hierarchy contains classes for defining each
94// component of the Measures to be contained in column. A
95// <linkto class="TableMeasOffsetDesc">TableMeasOffsetDesc</linkto> is used
96// to specify the offset component, a
97// <linkto class="TableMeasRefDesc">TableMeasRefDesc</linkto> to set up
98// the reference code component and a
99// <linkto class="TableMeasValueDesc">TableMeasValueDesc</linkto> names the
100// column used as the main Measure column through which the
101// Measure column is subsequently accessed.
102// <br>
103// The final step needed to create a Measure column is the creation of a
104// TableMeasDesc object whose
105// constructor takes a TableMeasValueDesc and (optionally) a
106// TableMeasRefDesc. After construction the TableMeasDesc object's
107// write() member is used to make the
108// the Measure column persistent within the Table.
109// <p>
110// The following examples demonstrate the creation of Measure columns using
111// the above components. Further details about each of these components
112// is available with each class description.
113// <br>
114// All examples write the measure description into a TableDesc object,
115// i.e. the argument used in the TableMeasDesc::write function is a
116// TableDesc object. It is, however, also possible to write them
117// into a Table object which is useful if measure columns are added
118// to an already existing table (see example 2).
119// </synopsis>
120
121// <example>
122//<ol>
123// <li> The following creates a MEpoch column with a fixed reference.
124// <srcblock>
125// // Need a table to work with.
126// TableDesc td("measureTable_desc", "1", TableDesc::New);
127// td.comment() = "A test of TableMeasures class.";
128//
129// // Define a column and add it to the table
130// // The main measure column is always an Array column of type Double
131// ArrayColumnDesc<Double> cdTime("Time", "An MEpoch column");
132// td.addColumn(cdtime);
133//
134// // Create the Measure column for an MEpoch. The MEpoch in
135// // the column has reference code MEpoch::TAI
136// TableMeasRefDesc measRef(MEpoch::TAI);
137// TableMeasValueDesc measVal(td, "Time");
138// TableMeasDesc<MEpoch> mepochCol(measVal, measRef);
139// // write makes the Measure column persistent.
140// mepochCol.write(td);
141//
142// // create the table with 5 rows
143// SetupNewTable newtab("MeasuresTable", td, Table::New);
144// Table tab(newtab, 5);
145// </srcblock>
146
147// <li> Same as example above, but for an already existing table.
148// <srcblock>
149// // Need a table to work with.
150// TableDesc td("measureTable_desc", "1", TableDesc::New);
151// td.comment() = "A test of TableMeasures class.";
152//
153// // Define a column and add it to the table
154// // The main measure column is always an Array column of type Double
155// ArrayColumnDesc<Double> cdTime("Time", "An MEpoch column");
156// td.addColumn(cdtime);
157//
158// // create the table with 5 rows
159// SetupNewTable newtab("MeasuresTable", td, Table::New);
160// Table tab(newtab, 5);
161//
162// // Create the Measure column for an MEpoch. The MEpoch in
163// // the column has reference code MEpoch::TAI
164// TableMeasRefDesc measRef(MEpoch::TAI);
165// TableMeasValueDesc measVal(tab.tableDesc(), "Time");
166// TableMeasDesc<MEpoch> mepochCol(measVal, measRef);
167// // write makes the Measure column persistent.
168// mepochCol.write(tab);
169// </srcblock>
170
171// <li> An MEpoch column with a variable reference code with a fixed offset:
172// <srcblock>
173// // The following three columns will be used to set up a Scalar MEpoch
174// // column with variable references and offsets. 3 columns are needed.
175// // The "main" column where the MEpoch will be stored
176// ArrayColumnDesc<Double> cdTime("Time", "An MEpoch column");
177
178// // Variable (i.e., per row) reference code storage needs a column.
179// // The column type is either Int or String (Int is faster but String
180// // may be useful when browsing the table). Either a Scalar column or
181// // Array column can be used here dependent on whether a Scalar or
182// // Array Measure column is used and whether in case of an Array Measure
183// // column the reference code has to be variable per array element.
184// ScalarColumnDesc<Int> cdRef("TimeRef", "Reference column for Time");
185//
186// // add the columns to the Table decriptor
187// td.addColumn(cdTime);
188// td.addColumn(cdRef);
189//
190// // now create the MEpoch column.
191// // want a fixed offset. Offsets are Measures
192// MEpoch offset(MVEpoch(MVTime(1996, 5, 17), MEpoch::UTC);
193// TableMeasOffsetDesc offsetDesc(offset);
194// // the reference
195// TableMeasRefDesc measRef(td, "TimeRef", offsetDesc);
196// // the value descriptor, create and write the column
197// TableMeasValueDesc measVal(td, "Time");
198// TableMeasDesc<MEpoch> mepochCol(measVal, measRef);
199// mepochCol.write();
200//
201// // create the table, etc
202// ...
203// </srcblock>
204//
205// <li> An MEpoch column with a variable reference code and offset
206// <srcblock>
207// // Variable (per row storage of) offsets needs its own column. Measure
208// // offsets are Measures therefore a Measure column is needed.
209// ArrayColumnDesc<Double> cdOffset("OffsetCol", "Variable Offset col");
210//
211// // A column for the variable reference code
212// ScalarColumnDesc<String> cdRef("RefCol", "Variable reference column");
213//
214// // The main (value) column for the Measure column
215// ArrayColumnDesc<Double> cdTime("Time", "MEpoch column");
216//
217// // add the column descriptors to the table
218// td.addColumn(cdOffset);
219// td.addColumn(cdRef);
220// td.addColumn(cdTime);
221//
222// // Create the Measure column
223//
224// // The offset column is itself a Measure column, but write() is not
225// // called
226// TableMeasValueDesc offsetVal(td, "OffsetCol");
227// TableMeasDesc<MEpoch> offset(offsetVal);
228// TableMeasOffsetDesc offsetDesc(offset);
229//
230// // the reference
231// TableMeasRefDesc ref(td, "RefCol", offsetDesc);
232//
233// // create the Measure column
234// TableMeasValueDesc val(td, "Time");
235// TableMeasDesc<MEpoch> mepochCol(val, ref);
236// mepochCol.write();
237
238// // create the table, etc
239// ...
240// </srcblock>
241//</ol>
242// </example>
243
244// <motivation>
245// Creating the required keyword for the definition of a Measure
246// in a Table is somewhat complicated. This class assists in that
247// process.
248// </motivation>
249//
250// <thrown>
251// <li>AipsError if a reference code string is invalid.
252// </thrown>
253//
254//# <todo asof="$DATE:$">
255//# A List of bugs, limitations, extensions or planned refinements.
256//# </todo>
257
258
259template<class M> class TableMeasDesc : public TableMeasDescBase
260{
261public:
262 // Constructor with measure value descriptor. The Measure reference for
263 // the column will be the default reference code for M. Units for the
264 // column will be the default for the Measure type.
266
267 // Constructor with measure value descriptor and Vector of Units.
268 // The Measure reference for the column will be the default reference
269 // code for the Measure type. Number of Units must be compatible
270 // with the Measure.
272
273 // Constructor with value and reference descriptors. Units for the
274 // column will be the default for Measure type.
276
277 // Constructor with value and reference descriptors and Vector of
278 // Units. Number of Units must be compatible with the Measure.
280 const Vector<Unit>&);
281
282 // Clone the object.
283 virtual TableMeasDescBase* clone() const;
284
285 // Copy constructor (copy semantics).
287
289
290 // Assignment operator (copy semantics)
292};
293
294
295
296} //# NAMESPACE CASACORE - END
297
298#ifndef CASACORE_NO_AUTO_TEMPLATES
299#include <casacore/measures/TableMeasures/TableMeasDesc.tcc>
300#endif //# CASACORE_NO_AUTO_TEMPLATES
301#endif
TableMeasDesc< M > & operator=(const TableMeasDesc< M > &that)
Assignment operator (copy semantics)
TableMeasDesc(const TableMeasDesc< M > &that)
Copy constructor (copy semantics).
TableMeasDesc(const TableMeasValueDesc &)
Constructor with measure value descriptor.
TableMeasDesc(const TableMeasValueDesc &, const TableMeasRefDesc &, const Vector< Unit > &)
Constructor with value and reference descriptors and Vector of Units.
TableMeasDesc(const TableMeasValueDesc &, const TableMeasRefDesc &)
Constructor with value and reference descriptors.
virtual TableMeasDescBase * clone() const
Clone the object.
TableMeasDesc(const TableMeasValueDesc &, const Vector< Unit > &)
Constructor with measure value descriptor and Vector of Units.
this file contains all the compiler specific defines
Definition mainpage.dox:28