TableDesc.h

Classes

TableDesc -- specify the structure of an AIPS++ table (full description)

class TableDesc

Types

enum TDOption

Old = 1
New
NewNoReplace
Scratch
Update
Delete

Interface

Public Members
TableDesc()
TableDesc (const String& type, TDOption = Old)
TableDesc (const String& type, const String& version, TDOption = Old)
TableDesc (const String& type, const String& version, const TabPath&, TabPath = Old)
TableDesc (const TableDesc&, const String& type, const String& version, TDOption)
TableDesc (const TableDesc&, const String& type, const String& version, const TabPath&, TabPath)
TableDesc (const TableDesc&, TDOption = Scratch)
~TableDesc()
const ColumnDescSet& columnDescSet() const
void add (const ColumnDescSet&)
ScalarKeywordSet& keywordSet()
const ScalarKeywordSet& keywordSet() const
ColumnDesc& addColumn (const ColumnDesc&)
ColumnDesc& addColumn (const ColumnDesc&, const String& newname)
void removeColumn (const String& name)
void renameColumn (const String& newname, const String& oldname)
Int ncolumn() const
Bool isColumn (const String& name) const
ColumnDesc& columnDesc (const String& name)
const ColumnDesc& columnDesc (const String& name) const
ColumnDesc& operator[] (const String& name)
const ColumnDesc& operator[] (const String& name) const
ColumnDesc& columnDesc (uInt index)
const ColumnDesc& columnDesc (uInt index) const
ColumnDesc& operator[] (uInt index)
const ColumnDesc& operator[] (uInt index) const
const String& comment() const
String& comment()
void show() const
const String& getType() const
const String& version() const
void checkSubTableDesc() const
Private Members
TableDesc& operator= (const TableDesc&)
void init (const TabPath&)
void copy (const TableDesc&, const TabPath&)
Public Members
void putFile (AipsIO&, Bool) const
void getFile (AipsIO&)

Description

Review Status

Reviewed By:
Paul Shannon
Date Reviewed:
1994/08/11
Programs:
Tests:

Prerequisite

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:

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

More information is provided in the Tables module documentation.

Example

// First build the new description of a subtable. // Define keyword subkey (integer) having value 10. // Define columns ra and dec (double). TableDesc subTableDesc("tTableDesc_sub", "1", TableDesc::New); subTableDesc.addColumn (ScalarColumnDesc("ra")); subTableDesc.addColumn (ScalarColumnDesc("dec"));

// Now create a new table description // Define a comment for the table description. // Define some keywords. ColumnDesc colDesc1, colDesc2; TableDesc td("tTableDesc", "1", TableDesc::New); td.comment() = "A test of class TableDesc"; td.keywordSet().keysdouble()("equinox") = 1950;

// Define an integer column ab using the TableDesc::addColumn // function which creates a scalar column description. td.addColumn (ScalarColumnDesc("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 acColumn("ac"); acColumn.keywordSet().keysComplex()("scale") = 0; acColumn.keywordSet().keysString()("unit") = ""; acColumn.setDefault (0); td.addColumn (acColumn); td["ac"].keywordSet().keysString()("unit") = "DEG";

// Add a scalar string column ad and define its comment string. td.addColumn (ScalarColumnDesc("ad","comment for ad"));

// Now define array columns. // This one is indirect and has no dimensionality mentioned yet. td.addColumn (ArrayColumnDesc("Arr1","comment for Arr1")); // This one is indirect and has 3-dim arrays. td.addColumn (ArrayColumnDesc("A2r1","comment for Arr1",3)); // This one is direct and has 2-dim arrays with axes length 4 and 7. td.addColumn (ArrayColumnDesc("Arr3","comment for Arr1", IPosition(2,4,7), ColumnDesc::Direct));

// Add a columns containing tables. td.addColumn (SubTableDesc("sub1", "subtable by name","tTableDesc_sub")); }

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.

To Do

Member Description

enum TDOption

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

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.

TableDesc (const String& type, const String& version, const TabPath&, TabPath = 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.

TableDesc (const TableDesc&, const String& type, const String& version, TDOption)

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.

TableDesc (const TableDesc&, const String& type, const String& version, const TabPath&, TabPath)

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.

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);

~TableDesc()

The destructor writes the table description if changed.

const ColumnDescSet& columnDescSet() const

Get access to the set of column descriptions. This can be used to add it to another TableDesc (see function add). ColumnDescSet is derived from KeywordSet, so all const KeywordSet functions (merge, etc.) can be used (e.g. isEqual to test if 2 table descriptions are the same).

void add (const ColumnDescSet&)

Add an existing column set to this description. The two column sets have to be disjoint.

Thrown Exceptions

ScalarKeywordSet& keywordSet()
const ScalarKeywordSet& keywordSet() const

Get access to the keyword set.

ColumnDesc& addColumn (const ColumnDesc&, const String& newname)

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 ColumnDesc as argument, it is usually needed to construct a more specialized object like ArrayColumnDesc. A ColumnDesc constructor converts that automatically to a ColumnDesc 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"));

Add a column to the table description and rename it. This may be useful to use a description of another column.

ColumnDesc& addColumn (const ColumnDesc&)

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 ColumnDesc as argument, it is usually needed to construct a more specialized object like ArrayColumnDesc. A ColumnDesc constructor converts that automatically to a ColumnDesc 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"));

void removeColumn (const String& name)

Remove a column. An exception is thrown if the column does not exist.

void 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.

Int ncolumn() const

Get number of columns.

Bool isColumn (const String& name) const

Test if a column with this name exists.

ColumnDesc& columnDesc (const String& name)
const ColumnDesc& columnDesc (const String& name) const
ColumnDesc& operator[] (const String& name)
const ColumnDesc& operator[] (const String& name) const
ColumnDesc& columnDesc (uInt index)
const ColumnDesc& columnDesc (uInt index) const
ColumnDesc& operator[] (uInt index)
const ColumnDesc& operator[] (uInt index) const

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.

const String& comment() const

Get comment string.

String& comment()

Get comment string (allowing it to be changed).

void show() const

Show the table description.

const String& getType() const

Get the table type (i.e. name of table description).

const String& version() const

Get the table description version.

void checkSubTableDesc() const

Check recursively if the descriptions of all subtables are known.

TableDesc& operator= (const TableDesc&)

File

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.

void init (const TabPath&)

Initialize the table description.

void copy (const TableDesc&, const TabPath&)

Initialize and copy a table description.

void putFile (AipsIO&, Bool) const

This function is not really meant for public use, but only for other Table classes.

Put the table description into the file. The flag determines if descriptions of nested tables will also be written. False= write only nested desc. with name=="" This is for saving a description in a file. In that way descriptions referred via a name are not saved with this description. True = write all nested descriptions. This is for writing a table, which should contain the descriptions of all nested tables.

void getFile (AipsIO&)

This function is not really meant for public use, but only for other Table classes.

Get the table description from the file.


Copyright © 1995 Associated Universities Inc., Washington, D.C.