A class for defining Quantum columns in Tables. More...

#include <TableQuantumDesc.h>

Public Member Functions
	TableQuantumDesc (const TableDesc &td, const String &column)
	Constructs a Quantum column descriptor with null units (Unit == "").
	TableQuantumDesc (const TableDesc &td, const String &column, const Unit &)
	Constructs a Quantum column descriptor with the specified Quantum unit.
	TableQuantumDesc (const TableDesc &td, const String &column, const Vector< String > &unitNames)
	Constructs a Quantum column descriptor with the specified Quantum units.
	TableQuantumDesc (const TableDesc &td, const String &column, const Vector< Unit > &)
	TableQuantumDesc (const TableDesc &td, const String &column, const String &unitCol)
	Constructs a Quantum column descriptor with variable units stored in unitCol.
	TableQuantumDesc (const TableDesc &td, const String &column, const Char *unitCol)
	TableQuantumDesc (const TableQuantumDesc &that)
	Copy constructor (copy semantics).
	~TableQuantumDesc ()
TableQuantumDesc &	operator= (const TableQuantumDesc &that)
	Assignment.
const Vector< String > &	getUnits () const
	Returns the Quantum column descriptor's units.
Bool	isUnitVariable () const
	Returns True if descriptor set for variable units (one per row)
const String &	columnName () const
	Returns the name of the quantum column.
const String &	unitColumnName () const
	Returns the name of the units column (an empty String is returned if the units are not variable).
void	write (TableDesc &)
	Makes the TableQuantumDesc persistent (updates the Table Descriptor).
void	write (Table &)
Static Public Member Functions
static TableQuantumDesc *	reconstruct (const TableDesc &td, const String &column)
	Reconstructs a previously constructed TableQuantumDesc.
static Bool	hasQuanta (const TableColumn &column)
	Does this column contain table quanta?
Private Member Functions
void	writeKeys (TableRecord &columnKeyset)
	Write the actual keywords.
void	checkColumn (const TableDesc &td) const
	Throw an exception if the quantum column doesn't exist.
void	checkUnitsColumn (const TableDesc &td) const
	Throw an exception if the variable units column isn't a string column.
Private Attributes
String	itsColName
	Name of column which stores the Quantum's values.
Vector< String >	itsUnitsName
	The Quantum's unit as a string.
String	itsUnitsColName
	Name of units column if units are variable.

Detailed Description

A class for defining Quantum columns in Tables.

Intended use:

Public interface

Review Status

Reviewed By:: Bob Garwood
Date Reviewed:: 1999/12/23
Test programs:: tTableQuantum

Prerequisite

Synopsis

A TableQuantumDesc object is used to define a Quantum column in a Table. The use of this object and the associated Scalar- and ArrayQuantColumn objects make it possible to store (and retrieve) Quanta in Tables.

TableQuantumDesc objects are analogous to ColumnDesc objects in that they add information, describing the characteristics of a column, to the Table Descriptor before the Table is created. However, rather than replacing the use of a ColumnDesc object, a TableQuantumDesc is used in conjunction with a ColumnDesc in the definition of Quantum columns.

Caution: A good understanding of the Table system is essential before attempting to use this class;

Defining a Quantum column requires the following steps:

Use a normal Scalar- or ArrayColumnDesc to define a column to use for the Quanta.
If needed (see below) define a column for the Quantum Units.
Add the columns to the Table Descriptor.
Declare a TableQuantumDesc to associate the column defined in step 1 and the Unit column from step 2 and update the Table Descriptor.
Setup and create the Table.

It is also possible to define a Quantum column after the table is created. which is useful when columns (to be used for quanta) are added to an already existing table.

The type of the quantum columns must match the type of the underlying Quanta that are to be stored in the column. Hence, for a column of Quantum<Complex> a ScalarColumnDesc<Complex> must be used.

As with standard Table Columns Quanta can be stored in Scalar and Array columns. This must be specified in advance by using either a Scalar- or ArrayColumnDesc.

After the Table has be created a Quantum column can be accessed for writing and reading of Quanta via the (RO)ScalarQuantColumn<T> and (RO)ArrayQuantColumn<T> objects.

Quantum Units

The treatment of the Unit component of a Quantum in the TableQuantumDesc class varies depending on your needs. The main consideration is whether the Quanta to be stored in a specific column are to have the same Unit or whether their Units could differ. In the simple case, where the Quanta have the same unit, a TableQuantumDesc is declared with the Unit value specified as a parameter. The following defines a Quantum column with units "deg":

         ScalarColumnDesc<Double> scd("QuantumCol");
         ..\.
         // defines QuantumCol as a Quantum column with fix Units "deg"
         TableQuantumDesc tqd(td, "QuantumCol", Unit("deg"));

This constructor stores the value for the Unit as a column keyword. In situations, however, where it is necessary to store a distinct Unit with each Quantum, it is necessary to define an additional column for storing the Unit component of each Quantum. The TableQuantumDesc constructor for this takes the name of the Unit column as a parameter. Hence an additional column must be defined for storing the Units and its type must be string. The following example shows how to set up a Quantum column with support for Quantum unit variability:

         // the quanta values stored here
         ScalarColumnDesc<Double> scd("QuantumCol");
         // a String column for the Units
         ScalarColumnDesc<String> scd("QuantumUnitCol");
         ..\.
         TableQuantumDesc tqd(td, "QuantumCol", "QuantumUnitCol");

One further consideration is that for Array Quantum Columns it is necessary to decide on a level of granularity for the Unit storage you would like. In Array Quantum columns it is possible to store a distinct Unit per row or per array element per row. This distinction is established when the Unit column is declared. Defining a ScalarColumn for Units specifies per row variability, that is, each row in an array column of Quanta will have the same unit. Alternatively, use of an ArrayColumn for the Unit column specifies that every Quantum stored will have its unit stored as well. In both cases the Unit column's type must be String. The following defines an Array Quantum Column with per row Unit storage:

         // for the Quanta values
         ArrayColumnDesc<Double> scd("ArrayQuantumCol");
         // per row storage of units
         ScalarColumnDesc<String> scd("QuantumUnitCol");
         ..\.
         TableQuantumDesc tqd(td, "ArrayQuantumCol", "QuantumUnitCol");

And finally, an array Quantum Column with an Array Unit Column:

         // for Quanta values
         ArrayColumnDesc<Double> scd("ArrayQuantumCol");
         // per element storage of Units
         ArrayColumnDesc<String> scd("ArrayUnitCol");
         ..\.
         TableQuantumDesc tqd(td, "ArrayQuantumCol", "ArrayUnitCol");

After constructing an TableQuantumDesc object use of the write() member updates the Table Descriptor or Table object. (RO)ScalarQuantColumn<T> and (RO)ArrayQuantColumn<T> are subsequently used to read-only and read/write access the Quantum Columns.

Example

        // create a table descriptor as normal
        TableDesc td("measTD", "1", TableDesc::New);
        td.comment() = "A table containing measures and quantums";
   
        // This example sets up a Quantum<Complex> column but any valid Quantum
        // type can be specified.  However, the type of the Quantums to be
        // stored must match the type of the underlying table column.
        ScalarColumnDesc<Complex> tcdQCplx("Quant", "A quantum complex column");
   
        // For a Quantum array column an ArrayColumnDesc is first defined
        ArrayColumnDesc<Double> tcdQDoub("QuantArray", "A quantum array col");
   
        // The QuantumArray column has variable units.  A string is needed
        // for these.  This could be done in two ways depending on what is
        // wanted.  Units can vary per element of array per row or
        // just per row.  In the first instance an ArrayColumn<String> would be
        // require.  Here we want to vary units only per row.
        ScalarColumnDesc<String> tcdUnits("VarQuantUnits", "Quantum units");
   
        // Add the columns to the Table Descriptor
        td.addColumn(tcdQplx);
        td.addColumn(tcdQDoub);
        td.addColumn(tcdUnits);
   
        // Create the TableQuantumDesc with units "deg" and an Array Quantum
        // Column with per row Unit granularity
        TableQuantumDesc tqdS(td, "Quant", unit("deg"));
        TableQuantumDesc tqdA(td, "QuantArray", "VarQuantUnits");
   
        // Update the Table Descriptor
        tqdA.write(td);
        tqdS.write(td);
   
        // Setup and create the new table as usual.
        SetupNewTable newtab("mtab", td, Table::New);
        Table qtab(newtab);
   
        // Now ScalarQuantColumn and ArrayQuantColumn objects could be
        // constructed to access the columns..\.

Note that writing the Quantum description could also be done after the table is created. It is meaningless in this case, but it is useful when columns (to be used for quanta) are added to an already existing table. be used as

        // Setup and create the new table as usual.
        SetupNewTable newtab("mtab", td, Table::New);
        Table qtab(newtab);
   
        // Update the Table Descriptor
        tqdA.write(qtab);
        tqdS.write(qtab);

Motivation

This class assists in the definition of a Quantum Table Column.

Thrown Exceptions

AipsError during construction if the column doesn't exist.
AipsError during construction if the unit's column doesn't exist (when variable units).
AipsError during construction if the type of the variable unit's column is not String.
AipsError during a reconstruct if the column doesn't have a Unit.

Definition at line 264 of file TableQuantumDesc.h.

Constructor & Destructor Documentation

casa::TableQuantumDesc::TableQuantumDesc	(	const TableDesc &	td,
		const String &	column
	)

Constructs a Quantum column descriptor with null units (Unit == "").

The column should have already been added to the TableDesc. An exception is thrown if the column doesn't exist.

casa::TableQuantumDesc::TableQuantumDesc	(	const TableDesc &	td,
		const String &	column,
		const Unit &
	)

Constructs a Quantum column descriptor with the specified Quantum unit.

The column should have already been added to the TableDesc. An exception is thrown if the column doesn't exist.

casa::TableQuantumDesc::TableQuantumDesc	(	const TableDesc &	td,
		const String &	column,
		const Vector< String > &	unitNames
	)

Constructs a Quantum column descriptor with the specified Quantum units.

The column should have already been added to the TableDesc. An exception is thrown if the column doesn't exist.

casa::TableQuantumDesc::TableQuantumDesc	(	const TableDesc &	td,
		const String &	column,
		const Vector< Unit > &
	)

casa::TableQuantumDesc::TableQuantumDesc	(	const TableDesc &	td,
		const String &	column,
		const String &	unitCol
	)

Constructs a Quantum column descriptor with variable units stored in unitCol.

Both the quantum and unit column should exist in the TableDesc.

casa::TableQuantumDesc::TableQuantumDesc	(	const TableDesc &	td,
		const String &	column,
		const Char *	unitCol
	)

casa::TableQuantumDesc::TableQuantumDesc ( const TableQuantumDesc & that )

Copy constructor (copy semantics).

casa::TableQuantumDesc::~TableQuantumDesc ( )

Member Function Documentation

void casa::TableQuantumDesc::checkColumn ( const TableDesc & td ) const [private]

Throw an exception if the quantum column doesn't exist.

void casa::TableQuantumDesc::checkUnitsColumn ( const TableDesc & td ) const [private]

Throw an exception if the variable units column isn't a string column.

const String& casa::TableQuantumDesc::columnName ( ) const [inline]

Returns the name of the quantum column.

Definition at line 322 of file TableQuantumDesc.h.

References itsColName.

const Vector<String>& casa::TableQuantumDesc::getUnits ( ) const [inline]

Returns the Quantum column descriptor's units.

A empty vector is returned if units have not been specified. This could be because the null unit constructor was used or because the units are variable.

Definition at line 314 of file TableQuantumDesc.h.

References itsUnitsName.

static Bool casa::TableQuantumDesc::hasQuanta ( const TableColumn & column ) [static]