casacore
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Member Functions | Static Public Member Functions | Private Member Functions | Private Attributes | List of all members
casacore::TableQuantumDesc Class Reference

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 == ""). More...
 
 TableQuantumDesc (const TableDesc &td, const String &column, const Unit &)
 Constructs a Quantum column descriptor with the specified Quantum unit. More...
 
 TableQuantumDesc (const TableDesc &td, const String &column, const Vector< String > &unitNames)
 Constructs a Quantum column descriptor with the specified Quantum units. More...
 
 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. More...
 
 TableQuantumDesc (const TableDesc &td, const String &column, const Char *unitCol)
 
 TableQuantumDesc (const TableQuantumDesc &that)
 Copy constructor (copy semantics). More...
 
 ~TableQuantumDesc ()
 
TableQuantumDescoperator= (const TableQuantumDesc &that)
 Assignment. More...
 
const Vector< String > & getUnits () const
 Returns the Quantum column descriptor's units. More...
 
Bool isUnitVariable () const
 Returns True if descriptor set for variable units (one per row) More...
 
const StringcolumnName () const
 Returns the name of the quantum column. More...
 
const StringunitColumnName () const
 Returns the name of the units column (an empty String is returned if the units are not variable). More...
 
void write (TableDesc &)
 Makes the TableQuantumDesc persistent (updates the Table Descriptor). More...
 
void write (Table &)
 

Static Public Member Functions

static TableQuantumDescreconstruct (const TableDesc &td, const String &column)
 Reconstructs a previously constructed TableQuantumDesc. More...
 
static Bool hasQuanta (const TableColumn &column)
 Does this column contain table quanta? More...
 

Private Member Functions

void writeKeys (TableRecord &columnKeyset)
 Write the actual keywords. More...
 
void checkColumn (const TableDesc &td) const
 Throw an exception if the quantum column doesn't exist. More...
 
void checkUnitsColumn (const TableDesc &td) const
 Throw an exception if the variable units column isn't a string column. More...
 

Private Attributes

String itsColName
 Name of column which stores the Quantum's values. More...
 
Vector< StringitsUnitsName
 The Quantum's unit as a string. More...
 
String itsUnitsColName
 Name of units column if units are variable. More...
 

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:

  1. Use a normal Scalar- or ArrayColumnDesc to define a column to use for the Quanta.
  2. If needed (see below) define a column for the Quantum Units.
  3. Add the columns to the Table Descriptor.
  4. Declare a TableQuantumDesc to associate the column defined in step 1 and the Unit column from step 2 and update the Table Descriptor.
  5. 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

Definition at line 265 of file TableQuantumDesc.h.

Constructor & Destructor Documentation

casacore::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.

casacore::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.

casacore::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.

casacore::TableQuantumDesc::TableQuantumDesc ( const TableDesc td,
const String column,
const Vector< Unit > &   
)
casacore::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.

casacore::TableQuantumDesc::TableQuantumDesc ( const TableDesc td,
const String column,
const Char unitCol 
)
casacore::TableQuantumDesc::TableQuantumDesc ( const TableQuantumDesc that)

Copy constructor (copy semantics).

casacore::TableQuantumDesc::~TableQuantumDesc ( )

Member Function Documentation

void casacore::TableQuantumDesc::checkColumn ( const TableDesc td) const
private

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

void casacore::TableQuantumDesc::checkUnitsColumn ( const TableDesc td) const
private

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

const String& casacore::TableQuantumDesc::columnName ( ) const
inline

Returns the name of the quantum column.

Definition at line 323 of file TableQuantumDesc.h.

References itsColName.

const Vector<String>& casacore::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 315 of file TableQuantumDesc.h.

References itsUnitsName.

static Bool casacore::TableQuantumDesc::hasQuanta ( const TableColumn column)
static

Does this column contain table quanta?

Bool casacore::TableQuantumDesc::isUnitVariable ( ) const
inline

Returns True if descriptor set for variable units (one per row)

Definition at line 319 of file TableQuantumDesc.h.

References casacore::String::empty(), and itsUnitsColName.

TableQuantumDesc& casacore::TableQuantumDesc::operator= ( const TableQuantumDesc that)

Assignment.

static TableQuantumDesc* casacore::TableQuantumDesc::reconstruct ( const TableDesc td,
const String column 
)
static

Reconstructs a previously constructed TableQuantumDesc.

const String& casacore::TableQuantumDesc::unitColumnName ( ) const
inline

Returns the name of the units column (an empty String is returned if the units are not variable).

Definition at line 328 of file TableQuantumDesc.h.

References itsUnitsColName.

void casacore::TableQuantumDesc::write ( TableDesc )

Makes the TableQuantumDesc persistent (updates the Table Descriptor).

void casacore::TableQuantumDesc::write ( Table )
void casacore::TableQuantumDesc::writeKeys ( TableRecord columnKeyset)
private

Write the actual keywords.

Member Data Documentation

String casacore::TableQuantumDesc::itsColName
private

Name of column which stores the Quantum's values.

Definition at line 342 of file TableQuantumDesc.h.

Referenced by columnName().

String casacore::TableQuantumDesc::itsUnitsColName
private

Name of units column if units are variable.

Definition at line 346 of file TableQuantumDesc.h.

Referenced by isUnitVariable(), and unitColumnName().

Vector<String> casacore::TableQuantumDesc::itsUnitsName
private

The Quantum's unit as a string.

Definition at line 344 of file TableQuantumDesc.h.

Referenced by getUnits().


The documentation for this class was generated from the following file: