casacore
Loading...
Searching...
No Matches
ArrayMeasColumn.h
Go to the documentation of this file.
1//# ArrayMeasColumn.h: Access to array 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_ARRAYMEASCOLUMN_H
29#define MEASURES_ARRAYMEASCOLUMN_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#include <casacore/casa/Arrays/ArrayFwd.h>
36
37namespace casacore { //# NAMESPACE CASACORE - BEGIN
38
39//# Forward Declarations
40template <class T> class ArrayColumn;
41template <class T> class ScalarColumn;
42template <class M> class ScalarMeasColumn;
43
44
45// <summary>
46// Access table array Measure columns.
47// </summary>
48
49// <use visibility=export>
50
51// <reviewed reviewer="Bob Garwood" date="1999/12/23" tests="tTableMeasures.cc">
52// </reviewed>
53
54// <prerequisite>
55// <li> <linkto module=Measures>Measures</linkto>
56// <li> <linkto module=Tables>Tables</linkto>
57// <li> TableMeasDesc
58// </prerequisite>
59
60// <synopsis>
61// ArrayMeasColumn objects can be used to access array Measure Columns
62// in tables, both for reading and writing (if the table is writable).
63//
64// Before a column can be accessed it must have previously been defined as
65// a Measure column by use of the
66// <linkto class="TableMeasDesc">TableMeasDesc</linkto> object.
67//
68// The ArrayMeasColumn class is templated on Measure type and MeasValue
69// type but typedefs exist for making declaration less long winded. The
70// Measure classes (like MEpoch) have typedefs <src>ArrayColumn</src>
71// to assist in creating ArrayMeasColumn objects.
72//
73// Constructing array Measure column objects using these typedefs looks like
74// this:
75// <srcblock>
76// // Read/write MEpoch array column
77// MEpoch::ArrayColumn ec(table, "ColumnName);
78// </srcblock>
79//
80// <h3>Reading and writing Measures</h3>
81//
82// The reading and writing of Measures columns is very similar to reading and
83// writing of "ordinary" Table columns.
84// <linkto class="ArrayMeasColumn#get">get()</linkto>
85// and <linkto class="ArrayMeasColumn#get">operator()</linkto>
86// exist for reading Measures and the
87// <linkto class="ArrayMeasColumn#put">put()</linkto> member for adding
88// Measures to a column. (put() is obviously not defined for
89// ScalarMeasColumn objects.) Each of these members accepts a row number
90// as an argument.
91//
92// Care needs to be taken when adding Measures to a column. The user needs
93// to be aware that Measures are not checked for consistency, with respect to
94// a Measure's reference, between the Measures being added to a column and
95// the column's predefined Measure reference. This is only an issue if the
96// Measure column was defined to have a fixed reference. For such columns
97// the reference component of Measures added to a column is silently
98// ignored, that is, there is no warning nor is there any sort of conversion
99// to the column's reference should the reference of the added Measure be
100// different from the column's reference. The functions
101// <linkto class="TableMeasDescBase#isRefCodeVariable()">
102// TableMeasDescBase::isRefVariable()</linkto>
103// and
104// <linkto class="ArrayMeasColumn#getMeasRef()">
105// ArrayMeasColumn::getMeasRef()</linkto> can be
106// used to discover a Measure column's Measure reference characteristics.
107// </synopsis>
108
109// <example>
110// <srcblock>
111// // create an MEpoch array column object
112// ArrayMeasColumn<MEpoch> arrayCol;
113//
114// // should be null. Can test this and attach a real MEpoch column
115// // The column Time1Arr should exist in the table and would have been
116// // defined by using a TableMeasDesc
117// if (arrayCol.isNull()) {
118// arrayCol.attach(tab, "Time1Arr");
119// }
120//
121// // This would throw an Exception if the object is still null....but
122// // hopefully won't
123// arrayCol.throwIfNull();
124//
125// // create a vector of MEpochs
126// MEpoch last(Quantity(13.45, "h"), MEpoch::Ref(MEpoch::TAI));
127// Vector<MEpoch> ev(10);
128// for (uInt i=0; i<10; i++) {
129// last.set(Quantity(13.45 + i, "h"));
130// ev(i) = last;
131// }
132//
133// // before adding something check the isDefined() member
134// if (!arrayCol.isDefined(0)) {
135// cout << "PASS - nothing in the measure array column row yet\n";
136// } else {
137// cout << "FAIL - there shouldn't be a valid value in the row!\n";
138// }
139//
140// // add the MEpoch vector to the array Measure column at row 0
141// arrayCol.put(0, ev);
142//
143// // now read the array from the row. Could use same object to do this
144// // but here we'll create a ArrayMeasColumn<MEpoch> to do this
145// ArrayMeasColumn<MEpoch> roArrCol(tab, "Time1Arr");
146//
147// // need a vector to put the MEpochs into
148// Vector<MEpoch> ew;
149//
150// // setting the resize parameter to True automatically sets ew to the
151// // same shape as the array contained in the row
152// arrayCol.get(0, ew, True);
153// </srcblock>
154// </example>
155
156// <motivation>
157// The standard Casacore Table system does not support array Measure columns.
158// This class overcomes this limitation.
159// </motivation>
160
161// <thrown>
162// <li>ArrayConformanceError during get() if supplied array is the wrong
163// shape.
164// </thrown>
165
166//# <todo asof="$DATE:$">
167//# A List of bugs, limitations, extensions or planned refinements.
168//# </todo>
169
170
171template<class M> class ArrayMeasColumn : public TableMeasColumn
172{
173public:
174 // The default constructor creates a null object. Useful for creating
175 // arrays of ArrayMeasColumn objects. Attempting to use a null object
176 // will produce a segmentation fault so care needs to be taken to
177 // initialise the objects by using the attach() member before any attempt
178 // is made to use the object. A ArrayMeasColumn object can be tested
179 // if it is null by using the isNull() member.
181
182 // Create the ArrayMeasColumn from the table and column Name.
184
185 // Copy constructor (copy semantics).
187
189
190 // Change the reference to another column.
191 void reference (const ArrayMeasColumn<M>& that);
192
193 // Attach a column to the object.
194 void attach (const Table& tab, const String& columnName);
195
196 // Get the Measure array in the specified row. For get() the supplied
197 // array's shape should match the shape in the row unless resize is True.
198 // <group name=get>
199 void get (rownr_t rownr, Array<M>& meas, Bool resize = False) const;
201 // </group>
202
203 // Get the Measure array contained in the specified row and convert
204 // it to the reference and offset found in the given measure.
205 Array<M> convert (rownr_t rownr, const M& meas) const
206 { return convert (rownr, meas.getRef()); }
207
208 // Get the Measure array contained in the specified row and convert
209 // it to the given reference.
210 // <group>
211 Array<M> convert (rownr_t rownr, const MeasRef<M>& measRef) const;
212 Array<M> convert (rownr_t rownr, uInt refCode) const;
213 // </group>
214
215 // Get the column's reference.
216 const MeasRef<M>& getMeasRef() const
217 { return itsMeasRef; }
218
219 // Reset the refCode, offset, or units.
220 // It overwrites the value used when defining the TableMeasDesc.
221 // Resetting the refCode and offset can only be done if they were
222 // defined as fixed in the description.
223 // <note role=tip>
224 // In principle the functions can only be used if the table is empty,
225 // otherwise already written values have thereafter the incorrect
226 // reference, offset, or unit.
227 // However, it is possible that part of the table is already
228 // written and that the entire measure column is filled in later.
229 // In that case the reference, offset, or units can be set by using
230 // a False <src>tableMustBeEmpty</src> argument.
231 // </note>
232 // <group>
233 void setDescRefCode (uInt refCode, Bool tableMustBeEmpty=True);
234 void setDescOffset (const Measure& offset, Bool tableMustBeEmpty=True);
235 void setDescUnits (const Vector<Unit>& units, Bool tableMustBeEmpty=True);
236 // </group>
237
238 // Add a Measure array to the specified row.
239 // <group name=put>
240 void put (rownr_t rownr, const Array<M>&);
241 // </group>
242
243protected:
244 //# Its measure reference when the MeasRef is constant per row.
246
247private:
248 //# Column which contains the Measure's actual data.
250 //# Its MeasRef code column when references are variable.
253 //# Its MeasRef column when references are variable and stored as Strings.
256 //# Column containing its variable offsets. Only applicable if the
257 //# measure references have offsets and they are variable.
260
261
262 // Assignment makes no sense in a read only class.
263 // Declaring this operator private makes it unusable.
265
266 // Deletes allocated memory etc. Called by ~tor and any member which needs
267 // to reallocate data.
268 void cleanUp();
269
270 // Get the data and convert using conversion engine.
271 Array<M> doConvert (rownr_t rownr, typename M::Convert& conv) const;
272};
273
274
275} //# NAMESPACE CASACORE - END
276
277
278//# Make old name ROArrayMeasColumn still available.
279#define ROArrayMeasColumn ArrayMeasColumn
280
281
282#ifndef CASACORE_NO_AUTO_TEMPLATES
283#include <casacore/measures/TableMeasures/ArrayMeasColumn.tcc>
284#endif //# CASACORE_NO_AUTO_TEMPLATES
285#endif
void cleanUp()
Deletes allocated memory etc.
ScalarColumn< Int > * itsRefIntCol
Array< M > convert(rownr_t rownr, const M &meas) const
Get the Measure array contained in the specified row and convert it to the reference and offset found...
ArrayMeasColumn()
The default constructor creates a null object.
Array< M > convert(rownr_t rownr, uInt refCode) const
ArrayMeasColumn(const ArrayMeasColumn< M > &that)
Copy constructor (copy semantics).
void setDescOffset(const Measure &offset, Bool tableMustBeEmpty=True)
ArrayMeasColumn & operator=(const ArrayMeasColumn< M > &that)
Assignment makes no sense in a read only class.
ArrayColumn< Double > * itsDataCol
void setDescUnits(const Vector< Unit > &units, Bool tableMustBeEmpty=True)
ScalarMeasColumn< M > * itsOffsetCol
ArrayMeasColumn< M > * itsArrOffsetCol
void reference(const ArrayMeasColumn< M > &that)
Change the reference to another column.
void attach(const Table &tab, const String &columnName)
Attach a column to the object.
Array< M > convert(rownr_t rownr, const MeasRef< M > &measRef) const
Get the Measure array contained in the specified row and convert it to the given reference.
ArrayMeasColumn(const Table &tab, const String &columnName)
Create the ArrayMeasColumn from the table and column Name.
Array< M > doConvert(rownr_t rownr, typename M::Convert &conv) const
Get the data and convert using conversion engine.
const MeasRef< M > & getMeasRef() const
Get the column's reference.
void get(rownr_t rownr, Array< M > &meas, Bool resize=False) const
Get the Measure array in the specified row.
ArrayColumn< Int > * itsArrRefIntCol
ScalarColumn< String > * itsRefStrCol
ArrayColumn< String > * itsArrRefStrCol
Array< M > operator()(rownr_t rownr) const
void put(rownr_t rownr, const Array< M > &)
Add a Measure array to the specified row.
void setDescRefCode(uInt refCode, Bool tableMustBeEmpty=True)
Reset the refCode, offset, or units.
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
const Bool False
Definition aipstype.h:44
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