casacore
Loading...
Searching...
No Matches
ScalarMeasColumn.h
Go to the documentation of this file.
1//# ScalarMeasColumn.h: Access to Scalar Measure Columns in Tables.
2//# Copyright (C) 1997,1998,1999,2000
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_SCALARMEASCOLUMN_H
29#define MEASURES_SCALARMEASCOLUMN_H
30
31//# Includes
32#include <casacore/casa/aips.h>
33#include <casacore/measures/TableMeasures/TableMeasColumn.h>
34#include <casacore/measures/Measures/MeasRef.h>
35
36namespace casacore { //# NAMESPACE CASACORE - BEGIN
37
38//# Forward Declarations
39template <class T> class ArrayColumn;
40template <class T> class ScalarColumn;
41
42
43// <summary>
44// Read only access to table scalar Measure columns.
45// </summary>
46
47// <use visibility=export>
48
49// <reviewed reviewer="Bob Garwood" date="1999/12/23" tests="tTableMeasures.cc">
50// </reviewed>
51
52// <prerequisite>
53//# Classes you should understand before using this one.
54// <li> <linkto module=Measures>Measures</linkto>
55// <li> <linkto module=Tables>Tables</linkto>
56// <li> <linkto class=TableMeasDesc>TableMeasDesc</linkto>
57// </prerequisite>
58
59// <synopsis>
60// ScalarMeasColumn objects can be used to access scalar Measure Columns
61// in tables, both for reading and writing (if the table is writable).
62//
63// Before a column can be accessed it must have previously been defined as
64// a Measure column by use of the
65// <linkto class="TableMeasDesc">TableMeasDesc</linkto> object.
66//
67// The ScalarMeasColumn class is templated on Measure type.
68// Typedefs exist in the various Measure classes
69// (e.g. <linkto class=MEpoch>MEpoch</linkto>) to make declaration
70// less long winded.
71// Constructing scalar Measure column objects using these typedefs looks like
72// this:
73// <srcblock>
74// MEpoch::ScalarMeasColumn ec(table, "ColumnName);
75// </srcblock>
76//
77// <h3>Reading and writing Measures</h3>
78//
79// The reading and writing of Measures columns is very similar to reading and
80// writing of "ordinary" Table columns.
81// <linkto class="ScalarMeasColumn#get">get()</linkto>
82// and <linkto class="ScalarMeasColumn#get">operator()</linkto>
83// exist for reading Measures and the
84// <linkto class="ScalarMeasColumn#put">put()</linkto> member for adding
85// Measures to a column. (put() is obviously not defined for
86// ScalarMeasColumn objects.) Each of these members accepts a row number
87// as an argument.
88// The get() function gets the measure with the reference and offset as
89// it is stored in the column. Furthermore the convert() function is
90// available to get the measure with the given reference, possible offset,
91// and possible frame
92//
93// When a Measure is put, the reference and possible offset are converted
94// if the measure column is defined with a fixed reference and/or offset.
95// If the column's reference and offset are variable, the reference and
96// offset of the measure as put are written into the appropriate
97// reference and offset columns.
98// </synopsis>
99
100// <example>
101// <srcblock>
102// // This creates a Scalar MEpoch column for read/write access. Column
103// // "Time1" must exist in Table "tab" and must have previously been
104// // defined as a MEpoch column using a TableMeasDesc.
105// MEpoch::ScalarMeasColumn timeCol(tab, "Time1");
106//
107// // print some details about the column
108// if (timeCol.measDesc().isRefCodeVariable()) {
109// cout << "The column has variable references." << endl;
110// } else {
111// cout << "The fixed MeasRef for the column is: "
112// << timeCol.getMeasRef() << endl;
113// }
114//
115// // Add tab.nrow() measures to the column.
116// MEpoch tm(Quantity(MeasData::MJD2000, "d"), MEpoch::TAI);
117// for (rownr_t i=0; i<tab.nrow(); i++) {
118// timeCol.put(i, tm);
119// }
120//
121// // We could read from the column using timeCol but instead a read
122// // only column object is created.
123// MEpoch::ScalarMeasColumn timeColRead(tab, "Time1");
124// for (i=0; i<tab.nrow(); i++) {
125// cout << timeColRead(i) << endl;
126// }
127// </srcblock>
128// </example>
129
130// <motivation>
131// The standard Casacore Table system does not support Measures columns.
132// This class overcomes this limitation.
133// </motivation>
134//
135// <thrown>
136// <li>AipsError during construction if the column specified variable
137// offsets which are stored in an Array- rather than a ScalarColumn.
138// </thrown>
139//
140//# <todo asof="$DATE:$">
141//# </todo>
142
143template <class M> class ScalarMeasColumn : public TableMeasColumn
144{
145public:
146 // The default constructor creates a null object. Useful for creating
147 // arrays of ScalarMeasColumn objects. Attempting to use a null object
148 // will produce a segmentation fault so care needs to be taken to
149 // initialize the objects first by using attach().
150 // An ScalarMeasColumn object can be tested if it is null by using the
151 // isNull() member.
153
154 // Create the ScalarMeasColumn from the table and column Name.
156
157 // Copy constructor (copy semantics).
159
161
162 // Change the reference to another column.
163 void reference (const ScalarMeasColumn<M>& that);
164
165 // Attach a column to the object.
166 void attach (const Table& tab, const String& columnName);
167
168 // Get the Measure contained in the specified row.
169 // It returns the Measure as found in the table.
170 // <group name=get>
171 void get (rownr_t rownr, M& meas) const;
172 M operator() (rownr_t rownr) const;
173 // </group>
174
175 // Get the Measure contained in the specified row and convert
176 // it to the reference and offset found in the given measure.
177 M convert (rownr_t rownr, const M& meas) const
178 { return convert (rownr, meas.getRef()); }
179
180 // Get the Measure contained in the specified row and convert
181 // it to the given reference.
182 // <group>
183 M convert (rownr_t rownr, const MeasRef<M>& measRef) const;
184 M convert (rownr_t rownr, uInt refCode) const;
185 // </group>
186
187 // Returns the column's fixed reference or the reference of the last
188 // read Measure if references are variable.
189 const MeasRef<M>& getMeasRef() const
190 { return itsMeasRef; }
191
192 // Reset the refCode, offset, or units.
193 // It overwrites the value used when defining the TableMeasDesc.
194 // Resetting the refCode and offset can only be done if they were
195 // defined as fixed in the description.
196 // <note role=tip>
197 // In principle the functions can only be used if the table is empty,
198 // otherwise already written values have thereafter the incorrect
199 // reference, offset, or unit.
200 // However, it is possible that part of the table is already
201 // written and that the entire measure column is filled in later.
202 // In that case the reference, offset, or units can be set by using
203 // a False <src>tableMustBeEmpty</src> argument.
204 // </note>
205 // <group>
206 void setDescRefCode (uInt refCode, Bool tableMustBeEmpty=True);
207 void setDescOffset (const Measure& offset, Bool tableMustBeEmpty=True);
208 void setDescUnits (const Vector<Unit>& units, Bool tableMustBeEmpty=True);
209 // </group>
210
211 // Put a Measure into the given row.
212 // <group name=put>
213 void put (rownr_t rownr, const M& meas);
214 // </group>
215
216protected:
217 // Make a MeasRef for the given row.
219
220private:
221 //# Whether conversion is needed during a put. True if either
222 //# the reference code or offset is fixed for the column
224 //# Column which contains the Measure's actual data. An array column
225 //# is needed if the data component of the underlying Measure is
226 //# represented by more than 1 value
229 //# Its MeasRef code column when references are variable.
232 //# Column containing its variable offsets. Only applicable if the
233 //# measure references have offsets and they are variable.
235 //# This is either the column's fixed Measure reference or the reference
236 //# of the last Measure read.
238
239
240 // Assignment makes no sense in a readonly class.
241 // Declaring this operator private makes it unusable.
243
244 // Check if refs have the same value (as opposed to being the same object).
245 Bool equalRefs (const MRBase& r1, const MRBase& r2) const;
246
247 //# Deletes allocated memory etc. Called by ~tor and any member which
248 //# needs to reallocate data.
249 void cleanUp();
250};
251
252
253} //# NAMESPACE CASACORE - END
254
255
256//# Make old name ROScalarMeasColumn still available.
257#define ROScalarMeasColumn ScalarMeasColumn
258
259
260#ifndef CASACORE_NO_AUTO_TEMPLATES
261#include <casacore/measures/TableMeasures/ScalarMeasColumn.tcc>
262#endif //# CASACORE_NO_AUTO_TEMPLATES
263#endif
M convert(rownr_t rownr, uInt refCode) const
Bool equalRefs(const MRBase &r1, const MRBase &r2) const
Check if refs have the same value (as opposed to being the same object).
void setDescUnits(const Vector< Unit > &units, Bool tableMustBeEmpty=True)
ScalarMeasColumn()
The default constructor creates a null object.
M operator()(rownr_t rownr) const
void get(rownr_t rownr, M &meas) const
Get the Measure contained in the specified row.
void put(rownr_t rownr, const M &meas)
Put a Measure into the given row.
void setDescOffset(const Measure &offset, Bool tableMustBeEmpty=True)
ScalarMeasColumn< M > * itsOffsetCol
M convert(rownr_t rownr, const MeasRef< M > &measRef) const
Get the Measure contained in the specified row and convert it to the given reference.
ArrayColumn< Double > * itsArrDataCol
void reference(const ScalarMeasColumn< M > &that)
Change the reference to another column.
ScalarMeasColumn(const Table &tab, const String &columnName)
Create the ScalarMeasColumn from the table and column Name.
void attach(const Table &tab, const String &columnName)
Attach a column to the object.
MeasRef< M > makeMeasRef(rownr_t rownr) const
Make a MeasRef for the given row.
ScalarMeasColumn(const ScalarMeasColumn< M > &that)
Copy constructor (copy semantics).
void setDescRefCode(uInt refCode, Bool tableMustBeEmpty=True)
Reset the refCode, offset, or units.
ScalarColumn< Double > * itsScaDataCol
ScalarColumn< String > * itsRefStrCol
ScalarMeasColumn & operator=(const ScalarMeasColumn< M > &that)
Assignment makes no sense in a readonly class.
const MeasRef< M > & getMeasRef() const
Returns the column's fixed reference or the reference of the last read Measure if references are vari...
M convert(rownr_t rownr, const M &meas) const
Get the Measure contained in the specified row and convert it to the reference and offset found in th...
ScalarColumn< Int > * itsRefIntCol
String: the storage and methods of handling collections of characters.
Definition String.h:225
const String & columnName() const
Get the name of the column.
this file contains all the compiler specific defines
Definition mainpage.dox:28
unsigned int uInt
Definition aipstype.h:51
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:42
const Bool True
Definition aipstype.h:43
uInt64 rownr_t
Define the type of a row number in a table.
Definition aipsxtype.h:46