casacore
TableQuantumDesc.h
Go to the documentation of this file.
1 //# TableQuantumDesc.h: Defines a 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_TABLEQUANTUMDESC_H
29 #define MEASURES_TABLEQUANTUMDESC_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/casa/Arrays/Vector.h>
34 #include <casacore/casa/BasicSL/String.h>
35 
36 namespace casacore { //# NAMESPACE CASACORE - BEGIN
37 
38 //# Forward Declarations
39 class TableDesc;
40 class Table;
41 class TableRecord;
42 class TableColumn;
43 class Unit;
44 
45 
46 // <summary>
47 // A class for defining Quantum columns in Tables.
48 // </summary>
49 
50 // <use visibility=export>
51 
52 // <reviewed reviewer="Bob Garwood" date="1999/12/23" tests="tTableQuantum.cc">
53 // </reviewed>
54 
55 // <prerequisite>
56 //# Classes you should understand before using this one.
57 // <li> <linkto class=Table>Table</linkto>
58 // <li> <linkto class=Quantum>Quantum</linkto>
59 // </prerequisite>
60 
61 // <synopsis>
62 // A TableQuantumDesc object is used to define a Quantum column in a Table.
63 // The use of this object and the associated Scalar- and ArrayQuantColumn
64 // objects make it possible to store (and retrieve) Quanta in Tables.<br>
65 //
66 // TableQuantumDesc objects are analogous to ColumnDesc objects in that they
67 // add information, describing the characteristics of a column, to the Table
68 // Descriptor before the Table is created. However, rather than
69 // replacing the use of a ColumnDesc object, a TableQuantumDesc is
70 // used in conjunction with a ColumnDesc in the definition of
71 // Quantum columns.<br>
72 //
73 // <note role=caution>
74 // A good understanding of the Table system is essential
75 // before attempting to use this class.
76 // </note>
77 //
78 // Defining a Quantum column requires the following steps:
79 // <ol>
80 // <li> Use a normal Scalar- or ArrayColumnDesc to define a column to use for
81 // the Quanta.
82 // <li> If needed (see
83 // <A HREF="#TableQuantumDesc:Quantum Units">below</A>) define a column
84 // for the Quantum Units.
85 // <li> Add the columns to the Table Descriptor.
86 // <li> Declare a TableQuantumDesc to associate the column defined in step 1
87 // and the Unit column from step 2 and update the Table Descriptor.
88 // <li> Setup and create the Table.
89 // </ol>
90 // It is also possible to define a Quantum column after the table is created.
91 // which is useful when columns (to be used for quanta) are added to
92 // an already existing table. <br>
93 //
94 // The type of the quantum columns must match the type of the underlying
95 // Quanta that are to be stored in the column. Hence, for a column of
96 // Quantum&lt;Complex&gt; a ScalarColumnDesc&lt;Complex&gt; must be used.<br>
97 //
98 // As with standard Table Columns Quanta can be stored in Scalar and Array
99 // columns. This must be specified in advance by using either a
100 // Scalar- or ArrayColumnDesc.<br>
101 //
102 // After the Table has be created a Quantum column can be accessed for writing
103 // and reading of Quanta via the
104 // <linkto class="ScalarQuantColumn">(RO)ScalarQuantColumn&lt;T&gt;</linkto>
105 // and
106 // <linkto class="ArrayQuantColumn">(RO)ArrayQuantColumn&lt;T&gt;</linkto>
107 // objects.
108 //
109 // <ANCHOR NAME="TableQuantumDesc:Quantum Units">
110 // <h3>Quantum Units</h3></ANCHOR>
111 // The treatment of the Unit component of a Quantum in the TableQuantumDesc
112 // class varies depending on your needs. The main consideration
113 // is whether the Quanta to be stored in a specific column are to have the
114 // same Unit or whether their Units could differ. In the simple case,
115 // where the
116 // Quanta have the same unit, a TableQuantumDesc is declared with the
117 // Unit value specified as a parameter. The following defines a Quantum
118 // column with units "deg":
119 //
120 // <srcblock>
121 // ScalarColumnDesc<Double> scd("QuantumCol");
122 // ...
123 // // defines QuantumCol as a Quantum column with fix Units "deg"
124 // TableQuantumDesc tqd(td, "QuantumCol", Unit("deg"));
125 // </srcblock>
126 //
127 // This constructor stores the value for the Unit as a
128 // column keyword. In situations, however, where it is necessary to
129 // store a distinct Unit with each Quantum, it is necessary to define
130 // an additional column for storing the Unit component of each Quantum.
131 // The TableQuantumDesc constructor for this takes the name of
132 // the Unit column as
133 // a parameter. Hence an additional column must be defined for storing the
134 // Units and its type must be string. The following
135 // example shows how to set up a Quantum column with support for Quantum
136 // unit variability:
137 //
138 // <srcblock>
139 // // the quanta values stored here
140 // ScalarColumnDesc<Double> scd("QuantumCol");
141 // // a String column for the Units
142 // ScalarColumnDesc<String> scd("QuantumUnitCol");
143 // ...
144 // TableQuantumDesc tqd(td, "QuantumCol", "QuantumUnitCol");
145 // </srcblock>
146 //
147 // One further consideration is that for Array Quantum Columns it is
148 // necessary to
149 // decide on a level of granularity for the Unit storage you would like.
150 // In Array Quantum columns it is possible to store a distinct Unit per row or
151 // per array element per row. This distinction is established when the
152 // Unit column is declared. Defining a ScalarColumn for Units specifies per
153 // row variability, that is, each row in an array column of Quanta will
154 // have the same unit. Alternatively, use of an ArrayColumn for the Unit
155 // column
156 // specifies that every Quantum stored will have its unit stored as well.
157 // In both cases the Unit column's type must be String. The following
158 // defines an Array Quantum Column with per row Unit storage:
159 //
160 // <srcblock>
161 // // for the Quanta values
162 // ArrayColumnDesc<Double> scd("ArrayQuantumCol");
163 // // per row storage of units
164 // ScalarColumnDesc<String> scd("QuantumUnitCol");
165 // ...
166 // TableQuantumDesc tqd(td, "ArrayQuantumCol", "QuantumUnitCol");
167 // </srcblock>
168 //
169 // And finally, an array Quantum Column with an Array Unit Column:
170 //
171 // <srcblock>
172 // // for Quanta values
173 // ArrayColumnDesc<Double> scd("ArrayQuantumCol");
174 // // per element storage of Units
175 // ArrayColumnDesc<String> scd("ArrayUnitCol");
176 // ...
177 // TableQuantumDesc tqd(td, "ArrayQuantumCol", "ArrayUnitCol");
178 // </srcblock>
179 //
180 //
181 // After constructing an TableQuantumDesc object use of the write() member
182 // updates the Table Descriptor or Table object.
183 // <linkto class="ScalarQuantColumn">(RO)ScalarQuantColumn&lt;T&gt;</linkto>
184 // and
185 // <linkto class="ArrayQuantColumn">(RO)ArrayQuantColumn&lt;T&gt;</linkto>
186 // are subsequently used to read-only and read/write access the Quantum
187 // Columns.
188 // </synopsis>
189 //
190 // <example>
191 // <srcblock>
192 // // create a table descriptor as normal
193 // TableDesc td("measTD", "1", TableDesc::New);
194 // td.comment() = "A table containing measures and quantums";
195 //
196 // // This example sets up a Quantum<Complex> column but any valid Quantum
197 // // type can be specified. However, the type of the Quantums to be
198 // // stored must match the type of the underlying table column.
199 // ScalarColumnDesc<Complex> tcdQCplx("Quant", "A quantum complex column");
200 //
201 // // For a Quantum array column an ArrayColumnDesc is first defined
202 // ArrayColumnDesc<Double> tcdQDoub("QuantArray", "A quantum array col");
203 //
204 // // The QuantumArray column has variable units. A string is needed
205 // // for these. This could be done in two ways depending on what is
206 // // wanted. Units can vary per element of array per row or
207 // // just per row. In the first instance an ArrayColumn<String> would be
208 // // require. Here we want to vary units only per row.
209 // ScalarColumnDesc<String> tcdUnits("VarQuantUnits", "Quantum units");
210 //
211 // // Add the columns to the Table Descriptor
212 // td.addColumn(tcdQplx);
213 // td.addColumn(tcdQDoub);
214 // td.addColumn(tcdUnits);
215 //
216 // // Create the TableQuantumDesc with units "deg" and an Array Quantum
217 // // Column with per row Unit granularity
218 // TableQuantumDesc tqdS(td, "Quant", unit("deg"));
219 // TableQuantumDesc tqdA(td, "QuantArray", "VarQuantUnits");
220 //
221 // // Update the Table Descriptor
222 // tqdA.write(td);
223 // tqdS.write(td);
224 //
225 // // Setup and create the new table as usual.
226 // SetupNewTable newtab("mtab", td, Table::New);
227 // Table qtab(newtab);
228 //
229 // // Now ScalarQuantColumn and ArrayQuantColumn objects could be
230 // // constructed to access the columns...
231 // </srcblock>
232 // Note that writing the Quantum description could also be done
233 // after the table is created. It is meaningless in this case, but
234 // it is useful when columns (to be used for quanta) are added to
235 // an already existing table.
236 // be used as
237 // <srcblock>
238 // // Setup and create the new table as usual.
239 // SetupNewTable newtab("mtab", td, Table::New);
240 // Table qtab(newtab);
241 //
242 // // Update the Table Descriptor
243 // tqdA.write(qtab);
244 // tqdS.write(qtab);
245 // </srcblock>
246 // </example>
247 
248 // <motivation>
249 // This class assists in the definition of a Quantum Table Column.
250 // </motivation>
251 
252 // <thrown>
253 // <li>AipsError during construction if the column doesn't exist.
254 // <li>AipsError during construction if the unit's column doesn't
255 // exist (when variable units).
256 // <li>AipsError during construction if the type of the variable unit's
257 // column is not String.
258 // <li>AipsError during a reconstruct if the column doesn't have a Unit.
259 // </thrown>
260 
261 //# <todo asof="$DATE:$">
262 //# A List of bugs, limitations, extensions or planned refinements.
263 //# </todo>
264 
266 {
267 public:
268  // Constructs a Quantum column descriptor with null units (Unit == "").
269  // The column should have already been added to the TableDesc.
270  // An exception is thrown if the column doesn't exist.
271  TableQuantumDesc (const TableDesc& td, const String& column);
272 
273  // Constructs a Quantum column descriptor with the specified Quantum unit.
274  // The column should have already been added to the TableDesc.
275  // An exception is thrown if the column doesn't exist.
276  TableQuantumDesc (const TableDesc& td, const String& column, const Unit&);
277 
278  // Constructs a Quantum column descriptor with the specified Quantum units.
279  // The column should have already been added to the TableDesc.
280  // An exception is thrown if the column doesn't exist.
281  // <group>
282  TableQuantumDesc (const TableDesc& td, const String& column,
283  const Vector<String>& unitNames);
284  TableQuantumDesc (const TableDesc& td, const String& column,
285  const Vector<Unit>&);
286  // </group>
287 
288  // Constructs a Quantum column descriptor with variable units stored in
289  // unitCol. Both the quantum and unit column should exist in the
290  // TableDesc.
291  //# Note that the Char* constructor is needed, otherwise the compiler
292  //# cannot choose between String and Unit.
293  //<group>
294  TableQuantumDesc (const TableDesc& td, const String& column,
295  const String& unitCol);
296  TableQuantumDesc (const TableDesc& td, const String& column,
297  const Char* unitCol);
298  //</group>
299 
300  // Copy constructor (copy semantics).
302 
304 
305  // Reconstructs a previously constructed TableQuantumDesc.
307  const String& column);
308 
309  // Assignment.
311 
312  // Returns the Quantum column descriptor's units. A empty vector is
313  // returned if units have not been specified. This could be because the null
314  // unit constructor was used or because the units are variable.
315  const Vector<String>& getUnits() const
316  { return itsUnitsName; }
317 
318  // Returns True if descriptor set for variable units (one per row)
320  { return (! itsUnitsColName.empty()); }
321 
322  // Returns the name of the quantum column.
323  const String& columnName() const
324  { return itsColName; }
325 
326  // Returns the name of the units column (an empty String is returned
327  // if the units are not variable).
328  const String& unitColumnName() const
329  { return itsUnitsColName; }
330 
331  // Makes the TableQuantumDesc persistent (updates the Table Descriptor).
332  // <group>
333  void write (TableDesc&);
334  void write (Table&);
335  // </group>
336 
337  // Does this column contain table quanta?
338  static Bool hasQuanta (const TableColumn& column);
339 
340 private:
341  // Name of column which stores the Quantum's values.
343  // The Quantum's unit as a string.
345  // Name of units column if units are variable.
347 
348 
349  // Write the actual keywords.
350  void writeKeys (TableRecord& columnKeyset);
351 
352  // Throw an exception if the quantum column doesn't exist.
353  void checkColumn (const TableDesc& td) const;
354 
355  // Throw an exception if the variable units column isn't a string column.
356  void checkUnitsColumn (const TableDesc& td) const;
357 };
358 
359 
360 
361 } //# NAMESPACE CASACORE - END
362 
363 #endif
String: the storage and methods of handling collections of characters.
Definition: String.h:225
Bool empty() const
Test for empty.
Definition: String.h:377
TableQuantumDesc(const TableDesc &td, const String &column, const String &unitCol)
Constructs a Quantum column descriptor with variable units stored in unitCol.
Vector< String > itsUnitsName
The Quantum's unit as a string.
void writeKeys(TableRecord &columnKeyset)
Write the actual keywords.
String itsUnitsColName
Name of units column if units are variable.
void write(TableDesc &)
Makes the TableQuantumDesc persistent (updates the Table Descriptor).
static Bool hasQuanta(const TableColumn &column)
Does this column contain table quanta?
TableQuantumDesc(const TableDesc &td, const String &column, const Char *unitCol)
TableQuantumDesc & operator=(const TableQuantumDesc &that)
Assignment.
TableQuantumDesc(const TableDesc &td, const String &column, const Unit &)
Constructs a Quantum column descriptor with the specified Quantum unit.
String itsColName
Name of column which stores the Quantum's values.
TableQuantumDesc(const TableQuantumDesc &that)
Copy constructor (copy semantics).
static TableQuantumDesc * reconstruct(const TableDesc &td, const String &column)
Reconstructs a previously constructed TableQuantumDesc.
const String & unitColumnName() const
Returns the name of the units column (an empty String is returned if the units are not variable).
void checkUnitsColumn(const TableDesc &td) const
Throw an exception if the variable units column isn't a string column.
const String & columnName() const
Returns the name of the quantum column.
TableQuantumDesc(const TableDesc &td, const String &column, const Vector< String > &unitNames)
Constructs a Quantum column descriptor with the specified Quantum units.
const Vector< String > & getUnits() const
Returns the Quantum column descriptor's units.
void checkColumn(const TableDesc &td) const
Throw an exception if the quantum column doesn't exist.
TableQuantumDesc(const TableDesc &td, const String &column)
Constructs a Quantum column descriptor with null units (Unit == "").
TableQuantumDesc(const TableDesc &td, const String &column, const Vector< Unit > &)
Bool isUnitVariable() const
Returns True if descriptor set for variable units (one per row)
this file contains all the compiler specific defines
Definition: mainpage.dox:28
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
char Char
Definition: aipstype.h:46