00001 //# ScalarQuantColumn.h: Access to a Scalar 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_SCALARQUANTCOLUMN_H 00029 #define MEASURES_SCALARQUANTCOLUMN_H 00030 00031 //# Includes 00032 #include <casacore/casa/aips.h> 00033 #include <casacore/casa/Quanta/Quantum.h> 00034 00035 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00036 00037 //# Forward Declarations 00038 class Table; 00039 template <class T> class ScalarColumn; 00040 class String; 00041 class Unit; 00042 00043 00044 // <summary> 00045 // Provides access to Scalar Quantum Columns in Tables. 00046 // </summary> 00047 00048 // <use visibility=export> 00049 00050 // <reviewed reviewer="Bob Garwood" date="1999/12/23" tests="tTableQuantum.cc"> 00051 // </reviewed> 00052 00053 // <prerequisite> 00054 //# Classes you should understand before using this one. 00055 // <li> <linkto class=TableQuantumDesc>TableQuantumDesc</linkto> 00056 // <li> <linkto class=Table>Table</linkto> 00057 // <li> <linkto class=ScalarColumn>ScalarColumn</linkto> 00058 // <li> <linkto class=Quantum>Quantum</linkto> 00059 // </prerequisite> 00060 00061 // <synopsis> 00062 // The ScalarQuantColumn class provides read/write access to quanta 00063 // stored in a scalar Quantum Table column. The Quantum column should 00064 // already exist in the table and would have been defined by means of a 00065 // <linkto class=TableQuantumDesc>TableQuantumDesc object</linkto>. 00066 // In addition, 00067 // for a ScalarQuantColumn object to be useful the column should 00068 // contain Quanta. 00069 // 00070 // A ScalarQuantColumn object is used much in the same way as a 00071 // <linkto class=ScalarColumn>ScalarColumn</linkto> object. 00072 // 00073 // <h3>Quantum Units</h3></A> 00074 // Quanta retrieved from the column will normally have the Unit that was 00075 // specified when the Quantum column was defined. 00076 // However, it is possible to override the default column Unit by 00077 // supplying a Unit in the ScalarQuantColumn constructor. 00078 // When constructed in this fashion the retrieved Quanta will by 00079 // default be retrieved in this unit, i.e. they will by default be 00080 // converted to this unit. 00081 // <br> 00082 // By giving a unit (as a Unit or Quantum object) to a get function, 00083 // the data can be retrieved in another unit than the default. 00084 // </synopsis> 00085 00086 // <example> 00087 // <srcblock> 00088 // Quantum<Double> q(5.3, "keV"); 00089 // // "QuantScalar" has previously been defined as a Quantum column 00090 // // by means of a TableQuantumDesc. This example assumes the column 00091 // // already contains quanta. 00092 // ScalarQuantColumn<Double> qCol(qtab, "QuantScalar"); 00093 // // return and print quanta as stored in the column 00094 // for (i = 0; i < qtab.nrow(); i++) { 00095 // cout << qCol(i) << endl; 00096 // } 00097 // // The following retrieves and converts the quanta to GHz. They 00098 // // are then divided by the Quantum constant QC::h (Planck). 00099 // for (i=0; i < qtab.nrow(); i++) { 00100 // cout << (qCol(i, "GHz"))/(QC::h); 00101 // } 00102 // </srcblock> 00103 // </example> 00104 00105 // <motivation> 00106 // Add support for Quanta in the Tables system. 00107 // </motivation> 00108 00109 // <thrown> 00110 // <li>TableInvOper if the Table column is null. 00111 // </thrown> 00112 00113 // <todo asof="$DATE:$"> 00114 //# A List of bugs, limitations, extensions or planned refinements. 00115 // <li> Functions like getColumn 00116 // </todo> 00117 00118 00119 template<class T> class ScalarQuantColumn 00120 { 00121 public: 00122 // The default constructor creates a null object. It is useful for creating 00123 // arrays of ScalarQuantColumn objects. Attempting to use a null object 00124 // will produce a segmentation fault so care needs to be taken to 00125 // initialise 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 ScalarQuantColumn object is null. 00128 ScalarQuantColumn(); 00129 00130 // Create the ScalarQuantColumn from the specified table and column name. 00131 // The default unit for data retrieved is the unit in which they were stored. 00132 ScalarQuantColumn (const Table& tab, const String& columnName); 00133 00134 // Create the ScalarQuantColumn from the specified table and column name. 00135 // The default unit for data retrieved is the given unit (the data is 00136 // converted as needed). 00137 ScalarQuantColumn (const Table& tab, const String& columnName, 00138 const Unit&); 00139 00140 // Copy constructor (copy semantics). 00141 ScalarQuantColumn (const ScalarQuantColumn<T>& that); 00142 00143 ~ScalarQuantColumn(); 00144 00145 // Change the reference to another column. 00146 void reference (const ScalarQuantColumn<T>& that); 00147 00148 // Attach a column to the object. Optionally supply a default unit 00149 // which has the same meaning as the constructor unit argument. 00150 // <group name="attach"> 00151 void attach (const Table& tab, const String& columnName); 00152 void attach (const Table& tab, const String& columnName, const Unit&); 00153 // </group> 00154 00155 // Get the quantum stored in the specified row. 00156 // <group name="get"> 00157 void get (uInt rownr, Quantum<T>& q) const; 00158 // Get the quantum in the specified row, converted to the given unit. 00159 void get (uInt rownr, Quantum<T>& q, const Unit&) const; 00160 // Get the quantum in the specified row, converted to the unit in other. 00161 void get (uInt rownr, Quantum<T>& q, const Quantum<T>& other) const; 00162 // </group> 00163 00164 // Return the quantum stored in the specified row. 00165 // <group> 00166 Quantum<T> operator() (uInt rownr) const; 00167 // Return the quantum stored in the specified row, converted to the 00168 // given unit. 00169 Quantum<T> operator() (uInt rownr, const Unit&) const; 00170 // Return the quantum in the specified row, converted to the unit in 00171 // other. 00172 Quantum<T> operator() (uInt rownr, const Quantum<T>& other) const; 00173 // </group> 00174 00175 // Put a quantum into the table. If the column supports variable units 00176 // the q's unit is stored into the unit column defined in the 00177 // TableQuantumDesc object. If units are fixed for the column, the 00178 // quantum is converted as needed. 00179 void put (uInt rownr, const Quantum<T>& q); 00180 00181 // Test whether the Quantum column has variable units 00182 Bool isUnitVariable() const 00183 { return (itsUnitsCol != 0); } 00184 00185 // Returns the column's value for Units as a string. 00186 // An empty string is returned if the column has variable units. 00187 const String& getUnits() const 00188 { return itsUnit.getName(); } 00189 00190 // Test if the object is null. 00191 Bool isNull() const 00192 { return (itsDataCol == 0); } 00193 00194 // Throw an exception if the object is null. 00195 void throwIfNull() const; 00196 00197 // get the column as a Quantum<Vector<T> >. If <src>unit</src> is 00198 // not empty, the returned Quantum will have that unit. Else if 00199 // the units are variable, the values in the returned Vector 00200 // have been converted to the unit of the 0th row entry. Otherwise, 00201 // the units of the returned Quantum are the units specified in 00202 // the column descriptor. 00203 SHARED_PTR<Quantum<Vector<T> > > getColumn(const Unit& unit="") const; 00204 00205 protected: 00206 //# Quantum column's units (if units not variable) 00207 Unit itsUnit; 00208 00209 // Get access to itsUnitsCol. 00210 const ScalarColumn<String>* unitsCol() const 00211 { return itsUnitsCol; } 00212 00213 private: 00214 //# The underlying data column stores the quantum column's data. 00215 ScalarColumn<T>* itsDataCol; 00216 //# Variable units column if applicable. 00217 ScalarColumn<String>* itsUnitsCol; 00218 //# Unit to retrieve the data in. 00219 Unit itsUnitOut; 00220 //# Convert unit when getting data? 00221 Bool itsConvOut; 00222 00223 00224 // Assignment makes no sense in a read only class. 00225 // Declaring this operator private makes it unusable. 00226 ScalarQuantColumn& operator= (const ScalarQuantColumn<T>& that); 00227 00228 // Comparison is not defined, since its semantics are unclear. 00229 Bool operator== (const ScalarQuantColumn<T>& that); 00230 00231 // Initialize the ScalarQuantColumn from the specified table and column. 00232 void init (const Table& tab, const String& columnName); 00233 00234 // Deletes allocated memory etc. Called by destructor and any member 00235 // which needs to reallocate data. 00236 void cleanUp(); 00237 00238 // Get the data without possible conversion. 00239 void getData (uInt rownr, Quantum<T>& q) const; 00240 }; 00241 00242 } //# NAMESPACE CASACORE - END 00243 00244 00245 //# Make old name ROScalarMeasColumn still available. 00246 #define ROScalarQuantColumn ScalarQuantColumn 00247 00248 00249 #ifndef CASACORE_NO_AUTO_TEMPLATES 00250 #include <casacore/measures/TableMeasures/ScalarQuantColumn.tcc> 00251 #endif //# CASACORE_NO_AUTO_TEMPLATES 00252 #endif