00001 //# ArrayQuantColumn.h: Access to an Array Quantum Column in a table. 00002 //# Copyright (C) 1997,1998,1999,2000,2001 00003 //# Associated Universities, Inc. Washington DC, USA. 00004 //# 00005 //# This library is free software; you can redistribute it and/or modify it 00006 //# under the terms of the GNU Library General Public License as published by 00007 //# the Free Software Foundation; either version 2 of the License, or (at your 00008 //# option) any later version. 00009 //# 00010 //# This library is distributed in the hope that it will be useful, but WITHOUT 00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 00012 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public 00013 //# License for more details. 00014 //# 00015 //# You should have received a copy of the GNU Library General Public License 00016 //# along with this library; if not, write to the Free Software Foundation, 00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA. 00018 //# 00019 //# Correspondence concerning AIPS++ should be addressed as follows: 00020 //# Internet email: aips2-request@nrao.edu. 00021 //# Postal address: AIPS++ Project Office 00022 //# National Radio Astronomy Observatory 00023 //# 520 Edgemont Road 00024 //# Charlottesville, VA 22903-2475 USA 00025 //# 00026 //# $Id$ 00027 00028 #ifndef MEASURES_ARRAYQUANTCOLUMN_H 00029 #define MEASURES_ARRAYQUANTCOLUMN_H 00030 00031 //# Includes 00032 #include <casacore/casa/aips.h> 00033 #include <casacore/casa/Arrays/Vector.h> 00034 #include <casacore/casa/Quanta/Quantum.h> 00035 00036 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00037 00038 //# Forward Declarations 00039 class Table; 00040 template <class T> class ArrayColumn; 00041 template <class T> class ScalarColumn; 00042 class String; 00043 00044 00045 // <summary> 00046 // Provides read/write access to Array Quantum columns in Tables. 00047 // </summary> 00048 00049 // <use visibility=export> 00050 00051 // <reviewed reviewer="Bob Garwood" date="1999/12/23" tests="tTableQuantum.cc"> 00052 // </reviewed> 00053 00054 // <prerequisite> 00055 //# Classes you should understand before using this one. 00056 // <li> <linkto class=TableQuantumDesc>TableQuantumDesc</linkto> 00057 // <li> <linkto class=Table>Table</linkto> 00058 // <li> <linkto class=ArrayColumn>ArrayColumn</linkto> 00059 // <li> <linkto class=Quantum>Quantum</linkto> 00060 // </prerequisite> 00061 00062 // <synopsis> 00063 // The ArrayQuantColumn class provides read/write access to quanta 00064 // stored in a array Quantum Table column. The Quantum column should 00065 // already exist in the table and would have been defined by means of a 00066 // <linkto class=TableQuantumDesc>TableQuantumDesc object</linkto>. 00067 // In addition, 00068 // for a ArrayQuantColumn object to be useful the column should 00069 // contain Quanta. 00070 // 00071 // The ArrayQuantColumn class is the array version 00072 // of the <linkto class=ScalarQuantColumn>ScalarQuantColumn</linkto> 00073 // class. 00074 // 00075 // <h3>Quantum Units</h3></A> 00076 // Quanta retrieved from the column will normally have the Unit that was 00077 // specified when the Quantum column was defined. 00078 // However, it is possible to override the default column Unit by 00079 // supplying a Unit in the ArrayQuantColumn constructor. 00080 // When constructed in this fashion the retrieved Quanta will by 00081 // default be retrieved in this unit, i.e. they will by default be 00082 // converted to this unit. 00083 // <br> 00084 // By giving a unit (as a Unit or Quantum object) to a get function, 00085 // the data can be retrieved in another unit than the default. 00086 // </synopsis> 00087 00088 // <example> 00089 // (See <linkto class=TableQuantumDesc>TableQuantumDesc</linkto> class 00090 // for an example of how to define a Quantum column). 00091 // <srcblock> 00092 // // Create the column object with default units "deg". 00093 // // It gets the quantum array from row 0 and prints it to stdout. 00094 // ArrayQuantColumn<Double> roaqCol(qtab, "ArrQuantDouble", "deg"); 00095 // cout << roaqCol(0) << endl; 00096 // // This retrieves the same array with units converted to "m/s". 00097 // cout << roaqCol(0, "m/s") << endl; 00098 // </srcblock> 00099 // </example> 00100 00101 // <motivation> 00102 // Add support for Quanta in the Tables system. 00103 // </motivation> 00104 00105 // <thrown> 00106 // <li>TableInvOper if the Table column is null. 00107 // </thrown> 00108 00109 // <todo asof="$DATE:$"> 00110 //# A List of bugs, limitations, extensions or planned refinements. 00111 // <li> Support for fixed unit per array element (e.g. for positions) 00112 // In that case #units should match first array dimension. 00113 // <li> Functions like getColumn, getSlice. 00114 // <li> get as <src>Quantum<Array<T>></src>. 00115 // <li> optimize when converting when units are the same for entire array. 00116 // </todo> 00117 00118 00119 template<class T> class ArrayQuantColumn 00120 { 00121 public: 00122 // The default constructor creates a null object. It is useful for creating 00123 // arrays of ArrayQuantColumn objects. Attempting to use a null object 00124 // will produce a segmentation fault so care needs to be taken to 00125 // initialize the objects by using the attach() member before any attempt 00126 // is made to use the object. The isNull() member can be used to test 00127 // if a ArrayQuantColumn object is null. 00128 ArrayQuantColumn(); 00129 00130 // Create the ArrayQuantColumn from the supplied table and column name. 00131 // The default unit for data retrieved is the unit in which they were stored. 00132 ArrayQuantColumn (const Table& tab, const String& columnName); 00133 00134 // Create the ArrayQuantColumn from the supplied table and column name. 00135 // The default unit for data retrieved is the given unit (the data is 00136 // converted as needed). 00137 // <group> 00138 ArrayQuantColumn (const Table& tab, const String& columnName, 00139 const Unit&); 00140 ArrayQuantColumn (const Table& tab, const String& columnName, 00141 const Vector<Unit>&); 00142 // </group> 00143 00144 // Copy constructor (copy semantics). 00145 ArrayQuantColumn (const ArrayQuantColumn<T>& that); 00146 00147 ~ArrayQuantColumn(); 00148 00149 // Make this object reference the column in "that". 00150 void reference (const ArrayQuantColumn<T>& that); 00151 00152 // Attach a column to the object. Optionally supply a default unit. 00153 // which has the same meaning as the constructor unit argument. 00154 // <group name="attach"> 00155 void attach (const Table& tab, const String& columnName); 00156 void attach (const Table& tab, const String& columnName, 00157 const Unit&); 00158 void attach (const Table& tab, const String& columnName, 00159 const Vector<Unit>&); 00160 // </group> 00161 00162 // Get the quantum array in the specified row. 00163 // If resize is True the resulting array is resized if its shape 00164 // is not correct. Otherwise a "conformance exception" is thrown 00165 // if the array is not empty and its shape mismatches. 00166 // <group name="get"> 00167 void get (uInt rownr, Array<Quantum<T> >& q, Bool resize = False) const; 00168 // Get the quantum array in the specified row. Each quantum is 00169 // converted to the given unit. 00170 void get (uInt rownr, Array<Quantum<T> >& q, 00171 const Unit&, Bool resize = False) const; 00172 // Get the quantum array in the specified row. Each quantum is 00173 // converted to the given units. 00174 void get (uInt rownr, Array<Quantum<T> >& q, 00175 const Vector<Unit>&, Bool resize = False) const; 00176 // Get the quantum array in the specified row. Each quantum is 00177 // converted to the unit in other. 00178 void get (uInt rownr, Array<Quantum<T> >& q, 00179 const Quantum<T>& other, Bool resize = False) const; 00180 // </group> 00181 00182 // Return the quantum array stored in the specified row. 00183 // <group> 00184 Array<Quantum<T> > operator() (uInt rownr) const; 00185 // Return the quantum array stored in the specified row, converted 00186 // to the given unit. 00187 Array<Quantum<T> > operator() (uInt rownr, const Unit&) const; 00188 // Return the quantum array stored in the specified row, converted 00189 // to the given units. 00190 Array<Quantum<T> > operator() (uInt rownr, const Vector<Unit>&) const; 00191 // Return the quantum array stored in the specified row, converted 00192 // to the unit in other. 00193 Array<Quantum<T> > operator() (uInt rownr, const Quantum<T>& other) const; 00194 // </group> 00195 00196 // Put an array of quanta into the specified row of the table. 00197 // If the column supports variable units, the units are stored as well. 00198 // Otherwise the quanta are converted to the column's units. 00199 void put (uInt rownr, const Array<Quantum<T> >& q); 00200 00201 // Test whether the Quantum column has variable units 00202 Bool isUnitVariable() const 00203 { return (itsArrUnitsCol || itsScaUnitsCol); } 00204 00205 // Returns the column's units as a vector of strings. 00206 // An empty vector is returned if the column has no fixed units. 00207 Vector<String> getUnits() const; 00208 00209 // Test if the object is null. 00210 Bool isNull() const 00211 { return (itsDataCol == 0); } 00212 00213 // Throw an exception if the object is null. 00214 void throwIfNull() const; 00215 00216 protected: 00217 //# Quantum column's units (if units not variable) 00218 Vector<Unit> itsUnit; 00219 00220 // Get access to itsUnitsCol. 00221 // <group> 00222 const ArrayColumn<String>* arrUnitsCol() const 00223 { return itsArrUnitsCol; } 00224 const ScalarColumn<String>* scaUnitsCol() const 00225 { return itsScaUnitsCol; } 00226 // </group> 00227 00228 00229 private: 00230 //# The underlying data column stores the quantum column's data. 00231 ArrayColumn<T>* itsDataCol; 00232 //# Variable units array column if applicable. 00233 ArrayColumn<String>* itsArrUnitsCol; 00234 //# Variable units scalar column if applicable. 00235 ScalarColumn<String>* itsScaUnitsCol; 00236 //# Units to retrieve the data in. 00237 Vector<Unit> itsUnitOut; 00238 //# Convert unit when getting data? 00239 Bool itsConvOut; 00240 00241 00242 // Initialize the ArrayQuantColumn from the specified table and column. 00243 void init (const Table& tab, const String& columnName); 00244 00245 // Deletes allocated memory etc. Called by ~tor and any member which needs 00246 // to reallocate data. 00247 void cleanUp(); 00248 00249 // Get the data without possible conversion. 00250 void getData (uInt rownr, Array<Quantum<T> >& q, Bool resize) const; 00251 00252 // Assignment makes no sense in a read only class. 00253 // Declaring this operator private makes it unusable. 00254 ArrayQuantColumn& operator= (const ArrayQuantColumn<T>& that); 00255 00256 // Comparison is not defined, since its semantics are unclear. 00257 Bool operator== (const ArrayQuantColumn<T>& that); 00258 }; 00259 00260 } //# NAMESPACE CASACORE - END 00261 00262 00263 //# Make old name ROArrayMeasColumn still available. 00264 #define ROArrayQuantColumn ArrayQuantColumn 00265 00266 00267 #ifndef CASACORE_NO_AUTO_TEMPLATES 00268 #include <casacore/measures/TableMeasures/ArrayQuantColumn.tcc> 00269 #endif //# CASACORE_NO_AUTO_TEMPLATES 00270 #endif