ColumnDesc.h

Class ColumnDesc is an envelope for the letter class BaseColDesc and its derivations like ScalarColumnDesc, ScalarRecordColumnDesc. ArrayColumnDesc, and SubTableDesc. ColumnDesc is meant to examine or slightly modify already existing column descriptions. It allows the retrieval of attributes like name, data type, etc.. For non-const ColumnDesc objects it is possible to modify the attributes comment and keyword set.

Since there are several types of columns, the class ColumnDesc cannot handle all details of those column types. Therefore, to create a column description, an instance of the specialized classes ArrayColumnDesc, etc. has to be constructed. In there column type dependent things like array shape and default value can be defined.

This class also enumerates the possible options which can be used when defining a column via classes like ScalarColumnDesc. These options are:

FixedShape: This is only useful for columns containing arrays and tables. FixedShape means that the shape of the array or table must be the same in each cell of the column. If not given, the array or table shape may vary. Option Direct forces FixedShape.
Direct: This is only useful for columns containing arrays and tables. Direct means that the data is directly stored in the table. Direct forces option FixedShape. If not given, the array or table is indirect, which implies that the data will be stored in a separate file.
Undefined: Undefined is only useful for scalars. If not given, all possible values of the scalar have a meaning. If given, a value equal to the default value in the column description is an undefined value. The function TableColumn::isDefined will return False for such values.

Example

  TableDesc tableDesc("theTableDesc", TableDesc::New);
  // Add a float scalar column.
  tableDesc.addColumn (ScalarColumnDesc<float> ("NAME");
  // Get the description of a column and change the comments.
  // In order to change the comments, a reference must be used
  // (because the ColumnDesc copy constructor and assign have copy
  // semantics).
  ColumnDesc& myColDesc = tableDesc.columnDesc ("aName");
  myColDesc.comment() += "some more comments";

Motivation

When getting the description of an arbitrary column, a pointer to that description is needed to allow proper execution of virtual functions. An envelope class is needed to hide this from the user.

To Do

Member Description

enum Option

Enumerate the possible column options. They can be combined by adding (logical or-ing) them.

ColumnDesc (const BaseColumnDesc&)

Construct from a column description. This constructor is merely for the purpose of the automatic conversion of an object like ScalarColumnDesc to ColumnDesc when adding a column to the table description using the function TableDesc::addColumn.

ColumnDesc (const ColumnDesc& that)

Copy constructor (copy semantics).

ColumnDesc()

Default constructor (needed for ColumnDescSet).

~ColumnDesc()

ColumnDesc& operator= (const ColumnDesc& that)

Assignment (copy semantics).

Bool operator== (const ColumnDesc&) const
Bool operator!= (const ColumnDesc&) const

Comparison. Two descriptions are equal when their data types, value types (scalar, array or table) and possible dimensionalities are equal.

TableRecord& rwKeywordSet()
const TableRecord& keywordSet() const

Get access to the set of keywords.

const String& name() const

Get the name of the column.

DataType dataType() const

Get the data type of the column. This always returns the type of a scalar, even when the column contains arrays.

DataType trueDataType() const

Get the true data type of the column. Unlike dataType, it returns an array data type (e.g. TpArrayInt) when the column contains arrays.

const String& dataTypeId() const

Get the type id for non-standard data types (i.e. for TpOther). For standard data types the returned string is empty.

const String& dataManagerType() const

Get the type name of the default data manager.

String& dataManagerType()

Get the type name of the default data manager (allowing it to be changed).

const String& dataManagerGroup() const

Get the data manager group.

String& dataManagerGroup()

Get the data manager group. (allowing it to be changed).

void setDefaultDataManager (Bool always=True)

If always==True they are always set, otherwise only if empty.

const String& comment() const

Get comment string.

String& comment()

Get comment string (allowing it to be changed).

int options() const

Get the options. The possible options are defined by the enum Option. E.g.

    const ColumnDesc& coldesc = tableDesc.getColumn ("column_name");
    if (coldesc.option() & ColumnDesc::Direct  ==  ColumnDesc::Direct) {
            // the column has the Direct flag set
    }

Bool isFixedShape() const

Check if the column is defined with a fixed shape. This is always true for scalars. For arrays it is true when the FixedShape flag was set when the column was defined.

Bool isScalar() const

Test if column is a scalar.

Bool isArray() const

Test if column is an array.

Bool isTable() const

Test if column is a table.

Int ndim() const

Get the number of dimensions.

const IPosition& shape() const

Get the predefined shape. If not defined, a zero shape will be returned.

void setNdim (uInt ndim)

Set the number of dimensions. This is only allowed for arrays. ndim can be zero to clear the number of dimensions and the shape. Otherwise it can only be used if the dimensionality has not been defined yet.

void setShape (const IPosition& shape)
void setShape (const IPosition& shape, Bool directOption)

Set the predefined shape. This is only allowed for arrays, for which the shape has not been defined yet. If the dimensionality has already been defined, it must match. It will set the option FixedShape if not set yet.
The first version leaves the Direct option as is. The second version sets the Direct option as given.

void setOptions (int options)

Set the options to the given value. Option ColumnDesc::Direct forces FixedShape. If FixedShape is not given (implicitly or explicitly), the column can have no shape, so its shape is cleared.

uInt maxLength() const

Get the maximum value length.

void setMaxLength (uInt maxLength)

Set the maximum value length. So far, this is only possible for columns containing String values. An exception is thrown if the column data type is not TpString. Some storage managers support fixed length strings and can store them more efficiently than variable length strings.

const TableDesc* tableDesc() const
TableDesc* tableDesc()

Get table description (in case column contains subtables).

void show() const

Show the column on cout.

void show (ostream& os) const

Show the column.

friend AipsIO& operator<< (AipsIO& ios, const ColumnDesc& cd)

Write into AipsIO.

friend AipsIO& operator>> (AipsIO& ios, ColumnDesc& cd)

Read from AipsIO.

friend ostream& operator<< (ostream& ios, const ColumnDesc& cd)

Show on ostream.

static BaseColumnDesc* unknownColumnDesc (const String& name)

Serve as default function for registerMap (see below), which catches all unknown xxxColumnDesc class names.

Thrown Exceptions

TableUnknownDesc

ColumnDesc (BaseColumnDesc*)

Construct from a pointer (for class BaseColumn).

void checkAdd (const ColumnDescSet& cds) const

Check if a column can be handled by ColumnDescSet. It is called before the column gets actually added, etc..

Check if the column can be added to the table description. It is implemented for a virtual column to check if the columns it uses really exist.

void checkRename (const ColumnDescSet& cds, const String& newName) const

Check if a column can be handled by ColumnDescSet. It is called before the column gets actually added, etc..

Check when a column gets renamed in a table description. It is not used.

void handleAdd (ColumnDescSet& cds)
void handleRename (ColumnDescSet& cds, const String& oldName)
void handleRemove (ColumnDescSet& cds)

Take action after a column has been handled by ColumnDescSet. It is called after the column has been actually added, etc.. This gives, for instance, the virtual column class the opportunity to update the virtual column list.

void renameAction (const String& newName, const String& oldName)

This function allows each column to act upon a rename of another column. If the old name is used internally, the column can update itself. It is called after handleRename has been called.

PlainColumn* makeColumn (ColumnSet* csp) const

Create a PlainColumn column object out of this column description.

RefColumn* makeRefColumn (RefTable* rtp, BaseColumn* bcp) const

Create a RefColumn column object out of this column description.

void setName (const String& name)

Set the name of the column.

void putFile (AipsIO& ios, const TableAttr&) const

Store the object in AipsIO.

void getFile (AipsIO&, const TableAttr&)

Get the object from AipsIO.