astTable

Create a Table

Description:

This function creates a new empty Table and optionally initialises its attributes.

The Table class is a type of KeyMap that represents a two-dimensional table of values. The astMapGet... and astMapPut... methods provided by the KeyMap class should be used for storing and retrieving values from individual cells within a Table. Each entry in the KeyMap represents a single cell of the table and has an associated key of the form " $<$COL$>$(i)" where " $<$COL$>$" is the name of a table column and " i" is the row index (the first row is row 1). Keys of this form should always be used when using KeyMap methods to access entries within a Table.

Columns must be declared using the astAddColumn method before values can be stored within them. This also fixes the type and shape of the values that may be stored in any cell of the column. Cells may contain scalar or vector values of any data type supported by the KeyMap class. Multi-dimensional arrays may also be stored, but these must be vectorised when storing and retrieving them within a table cell. All cells within a single column must have the same type and shape (specified when the column is declared).

Tables may have parameters that describe global properties of the entire table. These are stored as entries in the parent KeyMap and can be access using the get and set method of the KeyMap class. However, parameters must be declared using the astAddParameter method before being accessed.

Note - since accessing entries within a KeyMap is a relatively slow process, it is not recommended to use the Table class to store very large tables.

Synopsis

AstTable $\ast$astTable( const char $\ast$options, ... )

Parameters:

options
Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Table. The syntax used is identical to that for the astSet function and may include " printf" format specifiers identified by " %" symbols in the normal way.
...
If the " options" string contains " %" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C " printf" function).

Returned Value

astTable()
A pointer to the new Table.

Notes:

• A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason.

Status Handling

The protected interface to this function includes an extra parameter at the end of the parameter list described above. This parameter is a pointer to the integer inherited status variable: " int $\ast$status" .