Table.h

Classes

Table -- Main interface class to a read/write table (full description)

class Table : public Cleanup

Types

enum TableOption

Old = 1
New
existing table
NewNoReplace
create table
Scratch
create table (may not exist)
Update
scratch table
Delete
update existing table

Interface

Public Members
Table()
Table (const String& tableName, TableOption = Table::Old)
Table (const String& tableName, const String& tableDescName, TableOption = Table::Old)
Table (SetupNewTable&, uInt nrrow = 0, Bool initialize = False)
Table (const Table&)
~Table()
void cleanup()
Table& operator= (const Table&)
Bool isNull() const
void throwIfNull() const
void writeRefTable (const String& fileName) const
static Bool fileExists (const String& tableFileName)
static Bool fileIsWritable (const String& tableFileName)
Bool isWritable() const
Bool isWritable (const String& columnName) const
Bool isWritable (uInt columnIndex) const
const TableKeywordSet& keywordSet() const
TableKeywordSet& keywordSet()
const TableDesc& tableDesc() const
const String& tableName() const
int tableOption() const
uInt nrow() const
Bool canAddRow() const
void addRow (uInt nrrow = 1, Bool initialize = False)
Bool canRemoveRow() const
void removeRow (uInt rownr)
void removeRow (const Vector<uInt>& rownrs)
TableExprNode& key (const String& keywordName) const
TableExprNode& col (const String& columnName) const
TableExprNode& keyCol (const String& name) const
Table operator() (TableExprNode&) const
Table operator() (const Vector<uInt>& rownrs) const
Table operator() (const Block<Bool>& mask) const
Table project (const Block<String>& columnNames) const
Table operator& (const Table&) const
Table operator| (const Table&) const
Table operator- (const Table&) const
Table operator! () const
Table sort (const String& columnName, int = Sort::Ascending, int = Sort::HeapSort) const
Table sort (const Block<String>& columnNames, int = Sort::Ascending, int = Sort::HeapSort) const
Table sort (const Block<String>& columnNames, const Block<Int>& sortOrders, int = Sort::HeapSort) const
Table sort (const Block<String>& columnNames, const Block<ObjCompareFunc*>& compareFunctionPointers, const Block<Int>& sortOrders, int = Sort::HeapSort) const
Vector<uInt> rowNumbers() const
Bool canAddColumn() const
void addColumn (const ColumnDesc&)
Bool canRemoveColumn() const
void removeColumn (const String& columnName)
Bool canRenameColumn() const
void renameColumn (const String& newName, const String& oldName)
friend AipsIO& operator<< (AipsIO&, const Table&)
friend AipsIO& operator>> (AipsIO&, Table&)
void getTableKeyword (AipsIO&, Bool openWritable)
friend ostream& operator<< (ostream&, const Table&)
Protected Members
Table (BaseTable*, Bool countIt = True)
void open (const String& nam, const String& type, int tableOption)
Private Members
BaseTable* baseTablePtr() const
BaseTable* lookCache (const String& name, int tableOption)

Description

Review Status

Reviewed By:
TPPR
Date Reviewed:
08.11.94
Programs:
Tests:

Prerequisite

Synopsis

Class Table can be used to create a new table or to access an existing table in read/write or readonly mode.

To access the data in a Table, objects have to be created to access the columns. These objects are TableColumn, ScalarColumn and ArrayColumn, which can be created via their constructors. Furthermore the Table has a TableKeywordSet object which can be read or written using the appropriate functions.

To open an existing table, a simple Table constructor can be used. The possible construct options are:

Creating a new table requires more work, because columns have to be bound to storage managers or virtual column engines. Class SetupNewTable is needed for this purpose. The Tables module documentation explains in more detail how to create a table.

Other Table objects can be created from a Table using the select, project and sort functions. In that way a subset of the table can be created and it can be read/written in the same way as a normal Table. However, writing has the effect that the underlying table gets written.

See the Tables module for more information.

Example

    // Open a table to be updated.
    Table myTable ("theTable", Table::Update);
    // Write the column containing the scalar RA.
    ScalarColumn<double> raColumn(myTable, "RA");
    uInt nrrow = myTable.nrow();
    for (uInt i=0; i<nrrow; i++) {
       raColumn.put (i, i+10);    // Put value i+10 into row i
    }
    

Motivation

Table is the envelope for the underlying counted referenced classes derived from BaseTable. In this way no pointers have to be used to get polymorphism.

To Do

Member Description

enum TableOption

Table()

Create a null Table object (i.e. no table is attached yet). The sole purpose of this constructor is to allow construction of an array of Table objects. The assignment operator can be used to make a null object reference a column. Note that sort functions, etc. will cause a segmentation fault when operating on a null object. It was felt it was too expensive to test on null over and over again. The user should use the isNull or throwIfNull function in case of doubt.

Table (const String& tableName, const String& tableDescName, TableOption = Table::Old)

Create a table object for an existing writable table. The only options allowed are Old, Update, and Delete.

Check if the table description has the given name.

Table (const String& tableName, TableOption = Table::Old)

Create a table object for an existing writable table. The only options allowed are Old, Update, and Delete.

Table (SetupNewTable&, uInt nrrow = 0, Bool initialize = False)

Make a table object for a new table, which can thereafter be used for reading and writing. If there are unbound columns, default storage managers an/ord virtual column engines will be created and bound to those columns. Create the table with the given nr of rows. If a storage manager is used which does not allow addition of rows, the number of rows in the table must already be given here. Optionally the rows can be initialized with the default values as defined in the column descriptions.

Table (const Table&)

Copy constructor (reference semantics).

~Table()

The destructor writes the table if necessary.

void cleanup()

This function is used by the exception handling mechanism we have defined. It merely calls the destructor. When real exceptions are available it will be unnecessary.

Table& operator= (const Table&)

Assignment (reference semantics).

Bool isNull() const

Test if the object is null, i.e. does not reference a table yet. This is the case if the default constructor is used.

void throwIfNull() const

Throw an exception if the object is null, i.e. if function isNull() is True.

void writeRefTable (const String& fileName) const

Write a reference table (i.e. the result of a sort or select) into a file with the given name. This can be read back as a normal table.

static Bool fileExists (const String& tableFileName)

Test if a table file with the given name exists.

static Bool fileIsWritable (const String& tableFileName)

Test if the table file with the given name is writable. It throws an exception if the table does not exist.

Bool isWritable() const

Test if this table is writable.

Bool isWritable (const String& columnName) const
Bool isWritable (uInt columnIndex) const

Test if the given column is writable.

const TableKeywordSet& keywordSet() const

Get access to the table keyword set.

TableKeywordSet& keywordSet()

const TableDesc& tableDesc() const

Get access to the table description. This can be used to get nr of columns, etc..

Tip The keyword set in the table description is not the same set as the keyword set in the table itself.

const String& tableName() const

Get the table name.

int tableOption() const

Get the table option.

uInt nrow() const

Get nr of rows.

Bool canAddRow() const

Test if it is possible to add a row to this table. It is possible if all storage managers used for the table support it.

void addRow (uInt nrrow = 1, Bool initialize = False)

Add one or more rows at the end of the table. This will fail for tables not supporting addition of rows. Optionally the rows can be initialized with the default values as defined in the column descriptions.

Bool canRemoveRow() const

Test if it is possible to remove a row from this table. It is possible if all storage managers used for the table support it.

void removeRow (uInt rownr)

Remove rows. This will fail for tables not supporting removal of rows.

Remove the given row.

void removeRow (const Vector<uInt>& rownrs)

Remove rows. This will fail for tables not supporting removal of rows.

Remove multiple rows. This can be useful with the select and rowNumbers functions to remove some selected rows from the table.

TableExprNode& col (const String& columnName) const

Select rows from a table using an select expression consisting of TableExprNode objects. For example:

    Table result = tab(tab.col("columnName") > 10);
All rows for which the expression is true will be selected and "stored" in the result. You need to include ExprNode.h for this purpose.

Create a TableExprNode object for a column

TableExprNode& keyCol (const String& name) const

Select rows from a table using an select expression consisting of TableExprNode objects. For example:

    Table result = tab(tab.col("columnName") > 10);
All rows for which the expression is true will be selected and "stored" in the result. You need to include ExprNode.h for this purpose.

It will be determined if the name is a keyword or column.

Table operator() (TableExprNode&) const

Select rows from a table using an select expression consisting of TableExprNode objects. For example:

    Table result = tab(tab.col("columnName") > 10);
All rows for which the expression is true will be selected and "stored" in the result. You need to include ExprNode.h for this purpose.

Select rows using the given table select expression.

TableExprNode& key (const String& keywordName) const

Select rows from a table using an select expression consisting of TableExprNode objects. For example:

    Table result = tab(tab.col("columnName") > 10);
All rows for which the expression is true will be selected and "stored" in the result. You need to include ExprNode.h for this purpose.

Table operator() (const Vector<uInt>& rownrs) const

Select rows using a vector of row numbers. This can, for instance, be used to select the same rows as were selected in another table (using the rowNumbers function).

     Table result = thisTable (otherTable.rowNumbers());

Table operator() (const Block<Bool>& mask) const

Select rows using a mask block. The length of the block must match the number of rows in the table. If an element in the mask is True, the corresponding row will be selected.

Table project (const Block<String>& columnNames) const

Project the given columns (i.e. select the columns).

Table operator& (const Table&) const

Do logical operations on a table. It can be used for row-selected or projected (i.e. column-selected) tables. The tables involved must come from the same root table or be the root table themselves.

Intersection with another table.

Table operator| (const Table&) const

Do logical operations on a table. It can be used for row-selected or projected (i.e. column-selected) tables. The tables involved must come from the same root table or be the root table themselves.

Union with another table.

Table operator- (const Table&) const

Do logical operations on a table. It can be used for row-selected or projected (i.e. column-selected) tables. The tables involved must come from the same root table or be the root table themselves.

Subtract another table.

Table operator! () const

Do logical operations on a table. It can be used for row-selected or projected (i.e. column-selected) tables. The tables involved must come from the same root table or be the root table themselves.

Take complement.

Table sort (const Block<String>& columnNames, const Block<Int>& sortOrders, int = Sort::HeapSort) const

Sort a table on one or more columns of scalars. Per column a compare function can be provided. By default the standard compare function defined in Compare.h will be used. Default sort order is ascending. Default sorting algorithm is the heap sort.

Sort on multiple columns. The principal column has to be the first element in the Block of column names.

You can give the order per column.

Table sort (const Block<String>& columnNames, const Block<ObjCompareFunc*>& compareFunctionPointers, const Block<Int>& sortOrders, int = Sort::HeapSort) const

Sort a table on one or more columns of scalars. Per column a compare function can be provided. By default the standard compare function defined in Compare.h will be used. Default sort order is ascending. Default sorting algorithm is the heap sort.

Sort on multiple columns. The principal column has to be the first element in the Block of column names.

Provide some special compare functions via a function pointer. A zero function pointer means using the standard compare function from Compare.h.

Table sort (const String& columnName, int = Sort::Ascending, int = Sort::HeapSort) const

Sort a table on one or more columns of scalars. Per column a compare function can be provided. By default the standard compare function defined in Compare.h will be used. Default sort order is ascending. Default sorting algorithm is the heap sort.

Table sort (const Block<String>& columnNames, int = Sort::Ascending, int = Sort::HeapSort) const

Sort on multiple columns. The principal column has to be the first element in the Block of column names.

Vector<uInt> rowNumbers() const

Get a vector of row numbers. In case the table is a subset of the root table, this tells which rows of the root table are part of the subset. In case the table is the root table itself, the result is a vector containing the row numbers 0 .. #rows-1.

Bool canAddColumn() const

Test if a column can be added.

void addColumn (const ColumnDesc&)

Add a column to the table.

Bool canRemoveColumn() const

Test if a column can be removed.

void removeColumn (const String& columnName)

Remove a column.

Bool canRenameColumn() const

Test if a column can be renamed.

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

Rename a column.

friend AipsIO& operator<< (AipsIO&, const Table&)

Write a table to AipsIO (for TypedKeywords). This will only write the table name.

friend AipsIO& operator>> (AipsIO&, Table&)

Read a table from AipsIO (for TypedKeywords

). This will read the table name and open the table as writable if the table file is writable, otherwise as readonly.

void getTableKeyword (AipsIO&, Bool openWritable)

Read a table from AipsIO (for TableKeywords). This will read the table name and open the table as writable if the switch is set and if the table file is writable. otherwise it is opened as readonly.

friend ostream& operator<< (ostream&, const Table&)

Write a table to ostream (for TypedKeywords

). This only shows its name and number of columns and rows.

Table (BaseTable*, Bool countIt = True)

Construct a Table object from a BaseTable*. By default the object gets counted.

void open (const String& nam, const String& type, int tableOption)

Open an existing table.

BaseTable* baseTablePtr() const

Get the pointer to the underlying BaseTable. This is needed for some friend classes.

BaseTable* lookCache (const String& name, int tableOption)

Look in the cache if the table is already open. If so, check if table option matches.


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