casacore
Loading...
Searching...
No Matches
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
36namespace casacore { //# NAMESPACE CASACORE - BEGIN
37
38//# Forward Declarations
39class TableDesc;
40class Table;
41class TableRecord;
42class TableColumn;
43class 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{
267public:
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.
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>
334 void write (Table&);
335 // </group>
336
337 // Does this column contain table quanta?
338 static Bool hasQuanta (const TableColumn& column);
339
340private:
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.
const Vector< String > & getUnits() const
Returns the Quantum column descriptor's units.
TableQuantumDesc(const TableDesc &td, const String &column, const Unit &)
Constructs a Quantum column descriptor with the specified Quantum unit.
const String & unitColumnName() const
Returns the name of the units column (an empty String is returned if the units are not variable).
String itsColName
Name of column which stores the Quantum's values.
TableQuantumDesc(const TableQuantumDesc &that)
Copy constructor (copy semantics).
const String & columnName() const
Returns the name of the quantum column.
void checkUnitsColumn(const TableDesc &td) const
Throw an exception if the variable units column isn't a string column.
TableQuantumDesc(const TableDesc &td, const String &column, const Vector< String > &unitNames)
Constructs a Quantum column descriptor with the specified Quantum 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 == "").
static TableQuantumDesc * reconstruct(const TableDesc &td, const String &column)
Reconstructs a previously constructed TableQuantumDesc.
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