SubTabDesc.h

SubTableDesc describes a table column containing subtables. The semantics of subtables are described below. The column description is constructed using a table description describing the subtable. This subtable decription or its name is stored with the column description. When a table containing this column gets created, the subtable description gets copied and this copy is thereafter frozen.

Constructing a column description for a subtable can be done in 3 ways:

It can be constructed with the name of a table description kept in a file. Only this name will be stored with the column description. Only when the table column gets created, it will read the newest version of this table description. This is a completely dynamic way of defining the column. When the subtable description in the file changes, this column in newly created tables gets the latest version.
It can be constructed with a given table description. This means that a copy of that description will be made. The frozen subtable description will be stored with the column description. This is a completely static way of defining the column.
It can be constructed with a pointer to a table description. This means that a copy will only be made when the column description gets written. Thus changes to the subtable description will as long as possible be reflected in the column description. This is a mix of the first two ways.

A column can be direct or indirect. Direct columns will be written directly in the table file. All cells in the column must have the same description and it is therefore not possible to change a description. The subtables in indirect columns will be stored in separate files. The cells in indirect columns can contain different tables.

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.keywordSet().keysInt()("subkey") = 10;
     subTableDesc.addColumn (TpDouble, "ra");
     subTableDesc.addColumn (TpDouble, "dec");

     // Now create a new table description
     TableDesc td("tTableDesc", "1", TableDesc::New);

     // Add columns containing subtables.
     // This is done in 3 slighty different ways, which all have
     // their own (dis)advantages.
     // This is described in detail at the SubTableDesc constructors.
     td.addColumn (SubTableDesc("sub1", "subtable by name","tTableDesc_sub"));
     td.addColumn (SubTableDesc("sub2", "subtable copy",    subTableDesc));
     td.addColumn (SubTableDesc("sub3", "subtable pointer", &subTableDesc));

Motivation

Several column description classes are needed to allow the user to define attributes which are special for each column type. For columns containing a table this is the table description.

To Do

Probably only direct table descriptions should be allowed. Indirect arrays can have a shape in the description (although they can have #dim), so tables should behave similarly.

Member Description

SubTableDesc (const String& columnName, const String& comment, const String& tableDescName, int options = 0)

Construct from a table description with the given name. The description does not need to exist yet. Only when the table gets created, the description will be read and must exist. This means that the table description is not frozen; the most recent description will be used when creating the column.

SubTableDesc (const String& columnName, const String& comment, const TableDesc&, int options = 0)

Construct from the given table description, which will be copied and frozen.

SubTableDesc (const String& columnName, const String& comment, TableDesc*, int options = 0)

Construct from the given table description, which will be used directly. The description gets frozen when the column is written. Care should be taken, because the given table description must not be deleted before the column description gets destructed.