casacore
ArrayQuantColumn.h
Go to the documentation of this file.
1//# ArrayQuantColumn.h: Access to an Array Quantum Column in a table.
2//# Copyright (C) 1997,1998,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_ARRAYQUANTCOLUMN_H
29#define MEASURES_ARRAYQUANTCOLUMN_H
30
31//# Includes
32#include <casacore/casa/aips.h>
33#include <casacore/casa/Arrays/Vector.h>
34#include <casacore/casa/Quanta/Quantum.h>
35
36namespace casacore { //# NAMESPACE CASACORE - BEGIN
37
38//# Forward Declarations
39class Table;
40template <class T> class ArrayColumn;
41template <class T> class ScalarColumn;
42class String;
43
44
45// <summary>
46// Provides read/write access to Array Quantum columns in Tables.
47// </summary>
48
49// <use visibility=export>
50
51// <reviewed reviewer="Bob Garwood" date="1999/12/23" tests="tTableQuantum.cc">
52// </reviewed>
53
54// <prerequisite>
55//# Classes you should understand before using this one.
56// <li> <linkto class=TableQuantumDesc>TableQuantumDesc</linkto>
57// <li> <linkto class=Table>Table</linkto>
58// <li> <linkto class=ArrayColumn>ArrayColumn</linkto>
59// <li> <linkto class=Quantum>Quantum</linkto>
60// </prerequisite>
61
62// <synopsis>
63// The ArrayQuantColumn class provides read/write access to quanta
64// stored in a array Quantum Table column. The Quantum column should
65// already exist in the table and would have been defined by means of a
66// <linkto class=TableQuantumDesc>TableQuantumDesc object</linkto>.
67// In addition,
68// for a ArrayQuantColumn object to be useful the column should
69// contain Quanta.
70//
71// The ArrayQuantColumn class is the array version
72// of the <linkto class=ScalarQuantColumn>ScalarQuantColumn</linkto>
73// class.
74//
75// <h3>Quantum Units</h3></A>
76// Quanta retrieved from the column will normally have the Unit that was
77// specified when the Quantum column was defined.
78// However, it is possible to override the default column Unit by
79// supplying a Unit in the ArrayQuantColumn constructor.
80// When constructed in this fashion the retrieved Quanta will by
81// default be retrieved in this unit, i.e. they will by default be
82// converted to this unit.
83// <br>
84// By giving a unit (as a Unit or Quantum object) to a get function,
85// the data can be retrieved in another unit than the default.
86// </synopsis>
87
88// <example>
89// (See <linkto class=TableQuantumDesc>TableQuantumDesc</linkto> class
90// for an example of how to define a Quantum column).
91// <srcblock>
92// // Create the column object with default units "deg".
93// // It gets the quantum array from row 0 and prints it to stdout.
94// ArrayQuantColumn<Double> roaqCol(qtab, "ArrQuantDouble", "deg");
95// cout << roaqCol(0) << endl;
96// // This retrieves the same array with units converted to "m/s".
97// cout << roaqCol(0, "m/s") << endl;
98// </srcblock>
99// </example>
100
101// <motivation>
102// Add support for Quanta in the Tables system.
103// </motivation>
104
105// <thrown>
106// <li>TableInvOper if the Table column is null.
107// </thrown>
108
109// <todo asof="$DATE:$">
110//# A List of bugs, limitations, extensions or planned refinements.
111// <li> Support for fixed unit per array element (e.g. for positions)
112// In that case #units should match first array dimension.
113// <li> Functions like getColumn, getSlice.
114// <li> get as <src>Quantum<Array<T>></src>.
115// <li> optimize when converting when units are the same for entire array.
116// </todo>
117
118
119template<class T> class ArrayQuantColumn
120{
121public:
122 // The default constructor creates a null object. It is useful for creating
123 // arrays of ArrayQuantColumn objects. Attempting to use a null object
124 // will produce a segmentation fault so care needs to be taken to
125 // initialize the objects by using the attach() member before any attempt
126 // is made to use the object. The isNull() member can be used to test
127 // if a ArrayQuantColumn object is null.
129
130 // Create the ArrayQuantColumn from the supplied table and column name.
131 // The default unit for data retrieved is the unit in which they were stored.
132 ArrayQuantColumn (const Table& tab, const String& columnName);
133
134 // Create the ArrayQuantColumn from the supplied table and column name.
135 // The default unit for data retrieved is the given unit (the data is
136 // converted as needed).
137 // <group>
138 ArrayQuantColumn (const Table& tab, const String& columnName,
139 const Unit&);
140 ArrayQuantColumn (const Table& tab, const String& columnName,
141 const Vector<Unit>&);
142 // </group>
143
144 // Copy constructor (copy semantics).
146
148
149 // Make this object reference the column in "that".
150 void reference (const ArrayQuantColumn<T>& that);
151
152 // Attach a column to the object. Optionally supply a default unit.
153 // which has the same meaning as the constructor unit argument.
154 // <group name="attach">
155 void attach (const Table& tab, const String& columnName);
156 void attach (const Table& tab, const String& columnName,
157 const Unit&);
158 void attach (const Table& tab, const String& columnName,
160 // </group>
161
162 // Get the quantum array in the specified row.
163 // If resize is True the resulting array is resized if its shape
164 // is not correct. Otherwise a "conformance exception" is thrown
165 // if the array is not empty and its shape mismatches.
166 // <group name="get">
167 void get (rownr_t rownr, Array<Quantum<T> >& q, Bool resize = False) const;
168 // Get the quantum array in the specified row. Each quantum is
169 // converted to the given unit.
170 void get (rownr_t rownr, Array<Quantum<T> >& q,
171 const Unit&, Bool resize = False) const;
172 // Get the quantum array in the specified row. Each quantum is
173 // converted to the given units.
174 void get (rownr_t rownr, Array<Quantum<T> >& q,
175 const Vector<Unit>&, Bool resize = False) const;
176 // Get the quantum array in the specified row. Each quantum is
177 // converted to the unit in other.
178 void get (rownr_t rownr, Array<Quantum<T> >& q,
179 const Quantum<T>& other, Bool resize = False) const;
180 // </group>
181
182 // Return the quantum array stored in the specified row.
183 // <group>
185 // Return the quantum array stored in the specified row, converted
186 // to the given unit.
187 Array<Quantum<T> > operator() (rownr_t rownr, const Unit&) const;
188 // Return the quantum array stored in the specified row, converted
189 // to the given units.
191 // Return the quantum array stored in the specified row, converted
192 // to the unit in other.
193 Array<Quantum<T> > operator() (rownr_t rownr, const Quantum<T>& other) const;
194 // </group>
195
196 // Put an array of quanta into the specified row of the table.
197 // If the column supports variable units, the units are stored as well.
198 // Otherwise the quanta are converted to the column's units.
199 void put (rownr_t rownr, const Array<Quantum<T> >& q);
200
201 // Test whether the Quantum column has variable units
203 { return (itsArrUnitsCol || itsScaUnitsCol); }
204
205 // Returns the column's units as a vector of strings.
206 // An empty vector is returned if the column has no fixed units.
208
209 // Test if the object is null.
210 Bool isNull() const
211 { return (itsDataCol == 0); }
212
213 // Throw an exception if the object is null.
214 void throwIfNull() const;
215
216protected:
217 //# Quantum column's units (if units not variable)
219
220 // Get access to itsUnitsCol.
221 // <group>
223 { return itsArrUnitsCol; }
225 { return itsScaUnitsCol; }
226 // </group>
227
228
229private:
230 //# The underlying data column stores the quantum column's data.
232 //# Variable units array column if applicable.
234 //# Variable units scalar column if applicable.
236 //# Units to retrieve the data in.
238 //# Convert unit when getting data?
240
241
242 // Initialize the ArrayQuantColumn from the specified table and column.
243 void init (const Table& tab, const String& columnName);
244
245 // Deletes allocated memory etc. Called by ~tor and any member which needs
246 // to reallocate data.
247 void cleanUp();
248
249 // Get the data without possible conversion.
250 void getData (rownr_t rownr, Array<Quantum<T> >& q, Bool resize) const;
251
252 // Assignment makes no sense in a read only class.
253 // Declaring this operator private makes it unusable.
255
256 // Comparison is not defined, since its semantics are unclear.
258};
259
260} //# NAMESPACE CASACORE - END
261
262
263//# Make old name ROArrayMeasColumn still available.
264#define ROArrayQuantColumn ArrayQuantColumn
265
266
267#ifndef CASACORE_NO_AUTO_TEMPLATES
268#include <casacore/measures/TableMeasures/ArrayQuantColumn.tcc>
269#endif //# CASACORE_NO_AUTO_TEMPLATES
270#endif
ArrayQuantColumn(const Table &tab, const String &columnName)
Create the ArrayQuantColumn from the supplied table and column name.
ArrayQuantColumn()
The default constructor creates a null object.
Bool isUnitVariable() const
Test whether the Quantum column has variable units.
Bool isNull() const
Test if the object is null.
ArrayColumn< String > * itsArrUnitsCol
void getData(rownr_t rownr, Array< Quantum< T > > &q, Bool resize) const
Get the data without possible conversion.
void get(rownr_t rownr, Array< Quantum< T > > &q, const Quantum< T > &other, Bool resize=False) const
Get the quantum array in the specified row.
Vector< String > getUnits() const
Returns the column's units as a vector of strings.
void get(rownr_t rownr, Array< Quantum< T > > &q, Bool resize=False) const
Get the quantum array in the specified row.
void attach(const Table &tab, const String &columnName)
Attach a column to the object.
Bool operator==(const ArrayQuantColumn< T > &that)
Comparison is not defined, since its semantics are unclear.
ArrayQuantColumn & operator=(const ArrayQuantColumn< T > &that)
Assignment makes no sense in a read only class.
void get(rownr_t rownr, Array< Quantum< T > > &q, const Unit &, Bool resize=False) const
Get the quantum array in the specified row.
void put(rownr_t rownr, const Array< Quantum< T > > &q)
Put an array of quanta into the specified row of the table.
void get(rownr_t rownr, Array< Quantum< T > > &q, const Vector< Unit > &, Bool resize=False) const
Get the quantum array in the specified row.
void cleanUp()
Deletes allocated memory etc.
void attach(const Table &tab, const String &columnName, const Vector< Unit > &)
void throwIfNull() const
Throw an exception if the object is null.
ArrayColumn< T > * itsDataCol
const ScalarColumn< String > * scaUnitsCol() const
void reference(const ArrayQuantColumn< T > &that)
Make this object reference the column in "that".
ArrayQuantColumn(const Table &tab, const String &columnName, const Unit &)
Create the ArrayQuantColumn from the supplied table and column name.
void init(const Table &tab, const String &columnName)
Initialize the ArrayQuantColumn from the specified table and column.
void attach(const Table &tab, const String &columnName, const Unit &)
ScalarColumn< String > * itsScaUnitsCol
ArrayQuantColumn(const Table &tab, const String &columnName, const Vector< Unit > &)
Array< Quantum< T > > operator()(rownr_t rownr) const
Return the quantum array stored in the specified row.
ArrayQuantColumn(const ArrayQuantColumn< T > &that)
Copy constructor (copy semantics).
const ArrayColumn< String > * arrUnitsCol() const
Get access to itsUnitsCol.
String: the storage and methods of handling collections of characters.
Definition: String.h:225
this file contains all the compiler specific defines
Definition: mainpage.dox:28
const Bool False
Definition: aipstype.h:44
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
uInt64 rownr_t
Define the type of a row number in a table.
Definition: aipsxtype.h:46