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 
36 namespace casacore { //# NAMESPACE CASACORE - BEGIN
37 
38 //# Forward Declarations
39 class Table;
40 template <class T> class ArrayColumn;
41 template <class T> class ScalarColumn;
42 class 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 
119 template<class T> class ArrayQuantColumn
120 {
121 public:
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,
159  const Vector<Unit>&);
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 
216 protected:
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 
229 private:
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.
const ScalarColumn< String > * scaUnitsCol() const
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, 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.
Vector< String > getUnits() const
Returns the column's units as a vector of strings.
void put(rownr_t rownr, const Array< Quantum< T > > &q)
Put an array of quanta into the specified row of the table.
void cleanUp()
Deletes allocated memory etc.
void throwIfNull() const
Throw an exception if the object is null.
ArrayColumn< T > * itsDataCol
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.
ScalarColumn< String > * itsScaUnitsCol
ArrayQuantColumn(const Table &tab, const String &columnName, const Vector< Unit > &)
ArrayQuantColumn(const ArrayQuantColumn< T > &that)
Copy constructor (copy semantics).
ArrayQuantColumn & operator=(const ArrayQuantColumn< T > &that)
Assignment makes no sense in a read only class.
const ArrayColumn< String > * arrUnitsCol() const
Get access to itsUnitsCol.
Array< Quantum< T > > operator()(rownr_t rownr) const
Return the quantum array stored in the specified row.
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