casacore
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 
37 namespace casacore { //# NAMESPACE CASACORE - BEGIN
38 
39 //# Forward Declarations
40 template <class T> class ArrayColumn;
41 template <class T> class ScalarColumn;
42 template <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 
171 template<class M> class ArrayMeasColumn : public TableMeasColumn
172 {
173 public:
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.
183  ArrayMeasColumn (const Table& tab, const String& columnName);
184 
185  // Copy constructor (copy semantics).
187 
188  virtual ~ArrayMeasColumn();
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 
243 protected:
244  //# Its measure reference when the MeasRef is constant per row.
246 
247 private:
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
ArrayMeasColumn()
The default constructor creates a null object.
ArrayMeasColumn & operator=(const ArrayMeasColumn< M > &that)
Assignment makes no sense in a read only class.
ArrayMeasColumn(const ArrayMeasColumn< M > &that)
Copy constructor (copy semantics).
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.
const MeasRef< M > & getMeasRef() const
Get the column's reference.
Array< M > convert(rownr_t rownr, uInt refCode) const
void setDescOffset(const Measure &offset, Bool tableMustBeEmpty=True)
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.
ArrayMeasColumn(const Table &tab, const String &columnName)
Create the ArrayMeasColumn from the table and column Name.
Array< M > operator()(rownr_t rownr) const
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 > doConvert(rownr_t rownr, typename M::Convert &conv) const
Get the data and convert using conversion engine.
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.
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...
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