casacore
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 
36 namespace casacore { //# NAMESPACE CASACORE - BEGIN
37 
38 //# Forward Declarations
39 class String;
40 class Table;
41 class TableMeasRefDesc;
42 class 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 
259 template<class M> class TableMeasDesc : public TableMeasDescBase
260 {
261 public:
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(const TableMeasDesc< M > &that)
Copy constructor (copy semantics).
TableMeasDesc(const TableMeasValueDesc &)
Constructor with measure value descriptor.
virtual TableMeasDescBase * clone() const
Clone the object.
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.
TableMeasDesc< M > & operator=(const TableMeasDesc< M > &that)
Assignment operator (copy semantics)
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