Define the structure of an AIPS++ table. More...

#include <TableDesc.h>

Public Types
enum	TDOption { Old, New, NewNoReplace, Scratch, Update, Delete }
Public Member Functions
	TableDesc ()
	The default constructor creates a table description with option = Scratch and a blank name.
	TableDesc (const String &type, TDOption=Old)
	Create a table description object with the given name.
	TableDesc (const String &type, const String &version, TDOption=Old)
	Create a table description object with the given name (i.e.
	TableDesc (const String &type, const String &version, const TabPath &, TDOption=Old)
	Create a table description object.
	TableDesc (const TableDesc &, const String &type, const String &version, TDOption, Bool copyColumns=True)
	Create a table description object with the given name (i.e.
	TableDesc (const TableDesc &, const String &type, const String &version, const TabPath &, TDOption, Bool copyColumns=True)
	Create a table description object with the given name (i.e.
	TableDesc (const TableDesc &, TDOption=Scratch)
	This copy constructor makes a copy of the table description maintaining its name and version.
	~TableDesc ()
	The destructor writes the table description if changed.
const ColumnDescSet &	columnDescSet () const
	Get access to the set of column descriptions.
void	add (const TableDesc &other, Bool addKeywordSet=True)
	Add another table description to this table description.
TableRecord &	rwKeywordSet ()
	Get access to the keyword set.
const TableRecord &	keywordSet () const
const TableRecord &	privateKeywordSet () const
	Get readonly access to the private set of keywords.
ColumnDesc &	addColumn (const ColumnDesc &)
	Add a column to the table description.
ColumnDesc &	addColumn (const ColumnDesc &, const String &newname)
	Add a column to the table description and give it another name.
void	removeColumn (const String &name)
	Remove a column.
void	renameColumn (const String &newname, const String &oldname)
	Rename a column.
uInt	ncolumn () const
	Get number of columns.
Bool	isColumn (const String &name) const
	Test if a column with this name exists.
Vector< String >	columnNames () const
	Get a vector containing all column names.
const ColumnDesc &	columnDesc (const String &name) const
	Get the column description by name or by index.
const ColumnDesc &	operator[] (const String &name) const
const ColumnDesc &	columnDesc (uInt index) const
const ColumnDesc &	operator[] (uInt index) const
ColumnDesc &	rwColumnDesc (const String &name)
ColumnDesc &	rwColumnDesc (uInt index)
const String &	comment () const
	Get comment string.
String &	comment ()
	Get comment string (allowing it to be changed).
void	show () const
	Show the table description on cout.
void	show (ostream &os) const
	Show the table description.
const String &	getType () const
	Get the table type (i.e.
const String &	version () const
	Get the table description version.
Bool	isHypercolumn (const String &hypercolumnName) const
	Test if the given hypercolumn exists.
Vector< String >	hypercolumnNames () const
	Get the names of all hypercolumns.
uInt	hypercolumnDesc (const String &hypercolumnName, Vector< String > &dataColumnNames, Vector< String > &coordColumnNames, Vector< String > &idColumnNames) const
	Get the columns involved in a hypercolumn.
void	adjustHypercolumns (const SimpleOrderedMap< String, String > &old2new, Bool keepUnknownData=False, Bool keepUnknownCoord=False, Bool keppUnknownId=False)
	Adjust the hypercolumn definitions (for a RefTable).
void	removeIDhypercolumns (const Vector< String > &hcNames)
	Remove ID-columns from the given hypercolumn definitions and set their default data manager type to IncrementalStMan and group to ISM_TSM.
void	removeHypercolumnDesc (const String &hypercolumnName)
	Remove given hypercolumn definition.
void	checkSubTableDesc () const
	Check recursively if the descriptions of all subtables are known.
void	renameHypercolumn (const String &newHypercolumnName, const String &hypercolumnName)
void	putFile (AipsIO &, const TableAttr &) const
	Put the table description into the file.
void	getFile (AipsIO &, const TableAttr &)
	Get the table description from the file.

void	defineHypercolumn (const String &hypercolumnName, uInt ndim, const Vector< String > &dataColumnNames)
	Define a hypercolumn.
void	defineHypercolumn (const String &hypercolumnName, uInt ndim, const Vector< String > &dataColumnNames, const Vector< String > &coordColumnNames)
void	defineHypercolumn (const String &hypercolumnName, uInt ndim, const Vector< String > &dataColumnNames, const Vector< String > &coordColumnNames, const Vector< String > &idColumnNames)
Static Public Member Functions
static Bool	isReadable (const String &tableDescName)
	Test if a description file exists (i.e.
Private Member Functions
TableDesc &	operator= (const TableDesc &)
	Assignment is not supported, because it is impossible to define its semantics.
void	init (const TabPath &)
	Initialize the table description.
void	copy (const TableDesc &, const TabPath &, Bool copyColumns)
	Initialize and copy a table description.
void	throwHypercolumn (const String &hyperColumnName, const String &message)
	Throw an invalid hypercolumn exception.
Private Attributes
String	name_p
String	vers_p
String	dir_p
String	comm_p
TableRecord *	key_p
TableRecord *	privKey_p
ColumnDescSet	col_p
Bool	swwrite_p
TDOption	option_p
AipsIO	iofil_p

Detailed Description

Define the structure of an AIPS++ table.

Intended use:

Public interface

Review Status

Reviewed By:: Paul Shannon
Date Reviewed:: 1994/08/11
Test programs:: none

Prerequisite

column description classes
TableRecord

Synopsis

A TableDesc object contains the description, or structure, of a table. This description is required for the creation of a new table. Descriptions are subsequently associated with every table and embedded in them.

A table description consists of the following items:

Name, which cannot be blank if the description is saved in a file. The file name will be this name followed by .tabdsc.
Version, which defaults to a blank string. It serves merely as information for the user.
Comment, which defaults to an empty string. This serves purely as an informational string for the user.
A set of column descriptions which has to be added to the table description. A column description can be created using the classes ScalarColumnDesc, etc.. At table creation it is determined by the user if a column has to be stored using a storage manager or calculated on-the-fly using a so-called virtual column engine.
A keyword set, which is by default empty. When a table is created from the description, it gets a copy of this keyword set as its initial keyword set.

A TableDesc object can be constructed with one of the following options:

Old Open an existing table description file as readonly.
Update Open an existing table description file as read/write The TableDesc destructor will rewrite the possibly changed description.
New Create a new table description file. The TableDesc destructor will write the table description into the file.
NewNoReplace As option New, but an exception will be thrown if the table description file already exists.
Scratch Create a temporary table description. The table description will be lost when the TableDesc object is destructed. This is useful to create a Table object without storing the description separately. Note that the Table object maintains its own description (i.e. it copies the description when being constructed).
Delete Delete the table description file. This gets done by the destructor.

More information is provided in the Tables module documentation.

Example

        // First build the new description of a subtable.
        // Define columns ra and dec (double).
        TableDesc subTableDesc("tTableDesc_sub", "1", TableDesc::New);
        subTableDesc.addColumn (ScalarColumnDesc<double>("ra"));
        subTableDesc.addColumn (ScalarColumnDesc<double>("dec"));
   
        // Now create a new table description
        // Define a comment for the table description.
        // Define a double keyword.
        ColumnDesc colDesc1, colDesc2;
        TableDesc td("tTableDesc", "1", TableDesc::New);
        td.comment() = "A test of class TableDesc";
        td.rwKeywordSet().define ("equinox", 1950.0);
   
        // Define an integer column ab using the TableDesc::addColumn
        // function which creates a scalar column description.
        td.addColumn (ScalarColumnDesc<Int>("ab", "Comment for column ab"));
   
        // Add a scalar integer column ac, define keywords for it
        // and define a default value 0.
        // Overwrite the value of keyword unit.
        ScalarColumnDesc<Int> acColumn("ac");
        acColumn.rwKeywordSet().define ("scale", Complex(0.0f));
        acColumn.rwKeywordSet().define ("unit", "");
        acColumn.setDefault (0);
        td.addColumn (acColumn);
        td["ac"].rwKeywordSet().define ("unit", "DEG");
   
        // Add a scalar string column ad and define its comment string.
        td.addColumn (ScalarColumnDesc<String>("ad","comment for ad"));
   
        // Now define array columns.
        // This one is indirect and has no dimensionality mentioned yet.
        td.addColumn (ArrayColumnDesc<Complex>("Arr1","comment for Arr1"));
        // This one is indirect and has 3-dim arrays.
        td.addColumn (ArrayColumnDesc<Int>("A2r1","comment for Arr1",3));
        // This one is direct and has 2-dim arrays with axes length 4 and 7.
        td.addColumn (ArrayColumnDesc<uInt>("Arr3","comment for Arr1",
                                           IPosition(2,4,7),
                                           ColumnDesc::Direct));
   
        // Add a columns containing tables.
        td.addColumn (SubTableDesc("sub1", "subtable by name",
                                   "tTableDesc_sub"));
   
        // Define hypercolumn "dataCube".
        td.addColumn (ArrayColumnDesc<Complex>("data",2));
        td.addColumn (ArrayColumnDesc<Int>("pol",1));
        td.addColumn (ArrayColumnDesc<float>("freq",1));
        td.addColumn (ScalarColumnDesc<float>("time"));
        td.addColumn (ScalarColumnDesc<float>("baseline"));
        td.defineHypercolumn ("dataCube", 4,
                              stringToVector ("data"),
                              stringToVector ("pol,freq,time,baseline"));
    }

Motivation

A table description specifies the structure, but not the contents, of an aips++ table. Since many tables will have identical structure and different content, it makes good sense to separate structure ("description") from content.

Definition at line 186 of file TableDesc.h.

Member Enumeration Documentation

enum casa::TableDesc::TDOption

Enumerator:

Old
New
NewNoReplace
Scratch
Update
Delete

Definition at line 191 of file TableDesc.h.

Constructor & Destructor Documentation

casa::TableDesc::TableDesc ( )

The default constructor creates a table description with option = Scratch and a blank name.

casa::TableDesc::TableDesc	(	const String &	type,
		TDOption	= `Old`
	)

Create a table description object with the given name.

This name can be seen as the table type in the same way as a class name is the data type of an object. The name can only be blank when option=Scratch. The default table description path is used for the description file.

casa::TableDesc::TableDesc	(	const String &	type,
		const String &	version,
		TDOption	= `Old`
	)

Create a table description object with the given name (i.e.

table type) and version. The name can only be blank when option=Scratch. The default table description path is used for the description file.

casa::TableDesc::TableDesc	(	const String &	type,
		const String &	version,
		const TabPath &	,
		TDOption	= `Old`
	)

Create a table description object.

The given table description path is used for the description file. The name can only be blank with option=Scratch.

casa::TableDesc::TableDesc	(	const TableDesc &	,
		const String &	type,
		const String &	version,
		TDOption	,
		Bool	copyColumns = `True`
	)

Create a table description object with the given name (i.e.

table type) and version by copying the input table description. If the given name or version is blank, it will be copied from the input table description. The default table description path is used for the description file. The only options allowed are New, NewNoReplace and Scratch.

casa::TableDesc::TableDesc	(	const TableDesc &	,
		const String &	type,
		const String &	version,
		const TabPath &	,
		TDOption	,
		Bool	copyColumns = `True`
	)

Create a table description object with the given name (i.e.

table type) and version by copying the input table description. If the given name or version is blank, it will be copied from the input table description. The given table description path is used for the description file. The only options allowed are New, NewNoReplace and Scratch.

casa::TableDesc::TableDesc	(	const TableDesc &	,
		TDOption	= `Scratch`
	)

This copy constructor makes a copy of the table description maintaining its name and version.

By default a Scratch copy is made. It serves as a shorthand for the constructor:
TableDesc (const TableDesc&, "", "", TDOption);

casa::TableDesc::~TableDesc ( )

The destructor writes the table description if changed.

Member Function Documentation

void casa::TableDesc::add	(	const TableDesc &	other,
		Bool	addKeywordSet = `True`
	)

Add another table description to this table description.

It merges the column descriptions, the special keywordSet (containing hypercolumn definitions) and the user keywordSet (this last one is not added if the flag is False). The two table descriptions have to be disjoint, i.e. no column nor keyword should already exist. Otherwise an TableInvOper exception is thrown and nothing gets added.

ColumnDesc & casa::TableDesc::addColumn ( const ColumnDesc & column ) [inline]

Add a column to the table description.

   An exception is thrown if a keyword or column with this name
   already exists.
   Although this function has a <tt>ColumnDesc</tt> as argument,
   it is usually needed to construct a more specialized object like
   <tt>ArrayColumnDesc&lt;float&gt;</tt>. A <tt>ColumnDesc</tt>
   constructor converts that automatically to a <tt>ColumnDesc</tt>
   object.

          tableDesc.addColumn (ArrayColumnDesc<float> ("NAME"));

On the other hand this function can also be used to add a column description from another table as in:

          tableDesc.addColumn (otherTableDesc.columnDesc("NAME"));

Definition at line 565 of file TableDesc.h.

References casa::ColumnDescSet::addColumn(), and col_p.

ColumnDesc & casa::TableDesc::addColumn	(	const ColumnDesc &	column,
		const String &	newname
	)		`[inline]`

Add a column to the table description and give it another name.

This may be useful to use a description of another column.

Definition at line 568 of file TableDesc.h.

References casa::ColumnDescSet::addColumn(), and col_p.

void casa::TableDesc::adjustHypercolumns	(	const SimpleOrderedMap< String, String > &	old2new,
		Bool	keepUnknownData = `False`,
		Bool	keepUnknownCoord = `False`,
		Bool	keppUnknownId = `False`
	)

Adjust the hypercolumn definitions (for a RefTable).

It removes and/or renames columns as necessary. Column names which are not part of the map are removed if keepUnknown==False. If all data columns of a hypercolumn are removed, the entire hypercolumn is removed.

Referenced by casa::SetupNewTable::adjustHypercolumns().

void casa::TableDesc::checkSubTableDesc ( ) const [inline]

Check recursively if the descriptions of all subtables are known.

Definition at line 583 of file TableDesc.h.

References casa::ColumnDescSet::checkSubTableDesc(), and col_p.

const ColumnDesc & casa::TableDesc::columnDesc ( const String & name ) const [inline]

Get the column description by name or by index.

An exception is thrown if the column does not exist. Function isColumn should be used to test if a column exists.

Definition at line 530 of file TableDesc.h.

References col_p, and casa::name().

const ColumnDesc & casa::TableDesc::columnDesc ( uInt index ) const [inline]

Definition at line 534 of file TableDesc.h.

References col_p.

const ColumnDescSet & casa::TableDesc::columnDescSet ( ) const [inline]

Get access to the set of column descriptions.

In this way const ColumnDescSet functions (e.g. isDisjoint) can be used.

Definition at line 561 of file TableDesc.h.

References col_p.

Vector<String> casa::TableDesc::columnNames ( ) const

Get a vector containing all column names.

const String & casa::TableDesc::comment ( ) const [inline]

Get comment string.

Definition at line 577 of file TableDesc.h.

References comm_p.

String & casa::TableDesc::comment ( ) [inline]

Get comment string (allowing it to be changed).

Definition at line 580 of file TableDesc.h.

References comm_p.

void casa::TableDesc::copy	(	const TableDesc &	,
		const TabPath &	,
		Bool	copyColumns
	)		`[private]`

Initialize and copy a table description.

void casa::TableDesc::defineHypercolumn	(	const String &	hypercolumnName,
		uInt	ndim,
		const Vector< String > &	dataColumnNames
	)

Define a hypercolumn.

   A hypercolumn is a group of one or more data columns of which
   the data is treated as one or more (regular) hypercubes.
   The hypercolumn has coordinate axes (e.g. time, frequency)
   which are columns in the table.
   When the entire hypercolumn consists of multiple hypercubes,
   ID-columns can be defined, which uniquely determine the
   hypercube to be used.
    Note that only   \link casa::TiledDataStMan TiledDataStMan \endlink 
   requires the use of ID-columns.
   A hypercolumn definition is needed to be able to use a Tiled
   Storage Manager.

   The following has to be specified:
   <dl>
    <dt> Hypercolumn name
    <dd> which is the name used to refer to the hypercolumn.
    <dt> ndim
    <dd> defining the dimensionality of the hypercolumn (and
         of its hypercube(s)).
    <dt> Data column names
    <dd> which are the columns containing the hypercube data.
         When multiple columns are used, the shapes of the data
         in their cells must be the same in the same row.
         All data columns must contain numeric or Bool scalars or arrays.
         <dl>
          <dt> array:
          <dd> Its dimensionality has to be less than or equal to the
               dimensionality of the hypercolumn. If equal, the
               array itself already forms the hypercube. That would
               mean that each row is a hypercube.
               If less, the arrays from multiple rows form a hypercube,
               adding one or more dimensions to the array dimensionality.
          <dt> scalar:
          <dd> The data from multiple rows form a hypercube.
               Not all tiled storage managers support scalars.
         </dl>
    <dt> Coordinate column names (optional)
    <dd> which are the columns containing the coordinates of the
         hypercubes. They must be (u)Int, float, double or (D)Complex.
         When given, the number of coordinate columns must match the
         dimensionality of the hypercolumn.
         <br>
         When the data column cells contain arrays, the first N coordinate
         columns must contain vector values, where N is the dimensionality
         of the data arrays.
         The remaining coordinate columns must contain scalar values.
    <dt> Id column names (optional)
    <dd> have to be given when a hypercolumn can consist of multiple
         hypercubes. They define the column(s) determining which
         hypercube has to be used for a data array.
         The id columns must contain scalar values ((u)Int, float,
         double, (D)Complex, String and/or Bool).
   </dl>
   It will be checked if the given columns exists and have
   an appropriate type.
   <br>
   The default data manager type of the columns involved will be set
   to TiledColumnStMan if all data columns have a fixed shape.
   Otherwise they are set to TiledShapeStMan.
   The storage manager group of all columns involved will be set to
   the hypercolumn name. In that way binding columns to storage managers
   during the table creation process is easier because a simple
   <code>bindGroup</code> can be used.
   <p>
   For example:<br>
   A table contains data matrices with axes pol and freq.
   Those axes are defined in columns pol and freq containing
   vectors with the same length as the corresponding axis.
   The table also contains scalar columns time and baseline, which
   superimpose dimensions upon the data. So the data will be stored
   in a 4-d hypercube with axes pol,freq,time,baseline.
   It would be defined as follows:

            tableDesc.defineHypercolumn ("dataCube", 4,
                                   stringToVector ("data"),
                                   stringToVector ("pol,freq,time,baseline"));

Note that the function stringToVector is very convenient for creating a vector of Strings.

void casa::TableDesc::defineHypercolumn	(	const String &	hypercolumnName,
		uInt	ndim,
		const Vector< String > &	dataColumnNames,
		const Vector< String > &	coordColumnNames
	)

void casa::TableDesc::defineHypercolumn	(	const String &	hypercolumnName,
		uInt	ndim,
		const Vector< String > &	dataColumnNames,
		const Vector< String > &	coordColumnNames,
		const Vector< String > &	idColumnNames
	)

void casa::TableDesc::getFile	(	AipsIO &	,
		const TableAttr &
	)

Get the table description from the file.

const String & casa::TableDesc::getType ( ) const [inline]

Get the table type (i.e.

name of table description).

Definition at line 545 of file TableDesc.h.

References name_p.

uInt casa::TableDesc::hypercolumnDesc	(	const String &	hypercolumnName,
		Vector< String > &	dataColumnNames,
		Vector< String > &	coordColumnNames,
		Vector< String > &	idColumnNames
	)		const

Get the columns involved in a hypercolumn.

It returns the dimensionality of the hypercolumn. An exception is thrown if the hypercolumn does not exist.

Vector<String> casa::TableDesc::hypercolumnNames ( ) const

Get the names of all hypercolumns.

void casa::TableDesc::init ( const TabPath & ) [private]

Initialize the table description.

Bool casa::TableDesc::isColumn ( const String & name ) const [inline]

Test if a column with this name exists.

Definition at line 526 of file TableDesc.h.

References col_p, and casa::ColumnDescSet::isDefined().

Bool casa::TableDesc::isHypercolumn ( const String & hypercolumnName ) const

Test if the given hypercolumn exists.

static Bool casa::TableDesc::isReadable ( const String & tableDescName ) [static]

Test if a description file exists (i.e.

isReadable).

const TableRecord & casa::TableDesc::keywordSet ( ) const [inline]

Definition at line 555 of file TableDesc.h.

References key_p.

uInt casa::TableDesc::ncolumn ( ) const [inline]

Get number of columns.

Definition at line 522 of file TableDesc.h.

References col_p, and casa::ColumnDescSet::ncolumn().

TableDesc& casa::TableDesc::operator= ( const TableDesc & ) [private]

Assignment is not supported, because it is impossible to define its semantics.

Does the data need to be written into a file before being overwritten? Declaring it private, makes it unusable.

const ColumnDesc & casa::TableDesc::operator[] ( const String & name ) const [inline]

Definition at line 532 of file TableDesc.h.

References col_p, and casa::name().

const ColumnDesc & casa::TableDesc::operator[] ( uInt index ) const [inline]

Definition at line 536 of file TableDesc.h.

References col_p.

const TableRecord & casa::TableDesc::privateKeywordSet ( ) const [inline]

Get readonly access to the private set of keywords.

Definition at line 557 of file TableDesc.h.

References privKey_p.

void casa::TableDesc::putFile	(	AipsIO &	,
		const TableAttr &
	)		const

Put the table description into the file.

The name can be used to write the TableDesc from a Table and is used to set the names of subtables correctly.

void casa::TableDesc::removeColumn ( const String & name ) [inline]

Remove a column.

An exception is thrown if the column does not exist.

Definition at line 573 of file TableDesc.h.

References col_p, and casa::ColumnDescSet::remove().

void casa::TableDesc::removeHypercolumnDesc ( const String & hypercolumnName )

Remove given hypercolumn definition.

An exception is thrown if it is not a hypercolumn.

void casa::TableDesc::removeIDhypercolumns ( const Vector< String > & hcNames )

Remove ID-columns from the given hypercolumn definitions and set their default data manager type to IncrementalStMan and group to ISM_TSM.

void casa::TableDesc::renameColumn	(	const String &	newname,
		const String &	oldname
	)

Rename a column.

An exception is thrown if the old name does not exist or if the name already exists.
Caution: Renaming a column should be done with care, because other columns may be referring this column; Also a hypercolumn definition might be using the old name;