casacore
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 
36 namespace casacore { //# NAMESPACE CASACORE - BEGIN
37 
38 //# Forward Declarations
39 template <class T> class ArrayColumn;
40 template <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 
143 template <class M> class ScalarMeasColumn : public TableMeasColumn
144 {
145 public:
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.
155  ScalarMeasColumn (const Table& tab, const String& columnName);
156 
157  // Copy constructor (copy semantics).
159 
160  virtual ~ScalarMeasColumn();
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 
216 protected:
217  // Make a MeasRef for the given row.
219 
220 private:
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).
MeasRef< M > makeMeasRef(rownr_t rownr) const
Make a MeasRef for the given row.
void setDescUnits(const Vector< Unit > &units, Bool tableMustBeEmpty=True)
ScalarMeasColumn()
The default constructor creates a null object.
M operator()(rownr_t rownr) const
ScalarMeasColumn & operator=(const ScalarMeasColumn< M > &that)
Assignment makes no sense in a readonly class.
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.
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
const MeasRef< M > & getMeasRef() const
Returns the column's fixed reference or the reference of the last read Measure if references are vari...
ScalarColumn< String > * itsRefStrCol
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