Each column in a StarTable is assumed to contain the
same sort of thing. More specifically, for each table column there is
a ColumnInfo object
associated with each column which holds metadata describing
the values contained in that column
(the value associated with that column for each row in the table).
A ColumnInfo contains information about the
name,
units,
UCD,
class
etc of a column, as well as a mechanism for storing additional
('auxiliary') user-defined metadata.
It also provides methods for rendering the values in the column
under various circumstances.
The class associated with a column, obtained from the
getContentClass method,
is of particular importance. Every object in the column described
by that metadata should be an instance of the
Class that
getContentClass returns
(or of one of its subtypes), or null.
There is nothing in the tables infrastructure which can enforce
this, but a table which doesn't follow this rule is considered broken,
and application code is within its rights to behave unpredictably
in this case.
Such a broken table might result from a bug in the I/O handler used
to obtain the table in the first place, or a badly formed table that
it has read, or a bug in one of the wrapper classes upstream from
the table instance being used.
Because of the extensible nature of the infrastructure,
such bugs are not necessarily STIL's fault.
Any (non-primitive) class can be used
but most table I/O handlers can only
cope with certain types of value - typically the primitive wrapper classes
(numeric ones like
Integer,
Double and
Boolean) and
Strings, so these
are the most important ones to deal with. The contents of a table
cell must always (as far as the access methods are concerned) be
an Object or
null, so primitive values cannot be used directly.
The general rule for primitive-like (numeric or boolean) values
is that a scalar should be represented by the appropriate wrapper class
(Integer,
Float,
Boolean etc)
and an array by an array of primitives
(int[],
float[],
boolean[] etc).
Non-primitive-like objects
(of which String is the most important example)
should be represented by their own class (for scalars) or an array
of their own class (for arrays).
Note that it is not recommended to use multidimensional arrays
(i.e. arrays of arrays like int[][]);
a 1-dimensional Java array should be used, and information about
the dimensionality should be stored in the ColumnInfo's
shape attribute.
Thus to store a 3x2 array of integers, a 6-element array of type
int[] would be used, and the ColumnInfo's
getShape
method would return a two-element array (3,2).
In the case of floating point values
(columns with class Float or Double),
STIL implementation code treats null and NaN (Not-a-Number)
values somewhat interchangeably.
Typically where STIL encounters a null floating point value,
arising either from a file format that can represent blanks,
or from processing that fails to provide a definite value,
it will be represented internally as a NaN for reasons of efficiency.
In general therefore, client code is advised not to rely on
distinguishing these cases.