Package uk.ac.starlink.votable

## Interface TabularData

    public interface TabularData

Contains the actual cell contents of a VOTable TABLE element.

The cell data may always be retrieved sequentially from the table by acquiring a `RowSequence` object (method `getRowSequence()`) - this allows you to read all the data from the first row to the last. Multiple `RowSequences` may be simultaneously active. In some cases random access may also be available; if `isRandom()` returns true, then the `getRow(long)` and `getCell(long, int)` methods can be used to retrieve cell values in any order.

The objects retrieved from cells in a given column are of course determined by the corresponding FIELD element (`FieldElement` object), in particular its `arraysize` and `datatype` attributes. What object is returned from each column is described by the following rules:

- If the element is a scalar or (fixed-dimension) 1-element array, a primitive wrapper object (`Integer`, `Float` etc) will be normally be returned
- If the element is an array, a java array of primitives (`int[]`, `float[]` etc) will normally be returned. This is stored in column-major order, where that makes a difference (for arrays with more than one dimension).
- Complex types types are treated by adding an extra dimension to the shape of the data, the most rapidly varying, of size 2.
- Character (`char` and `unicodeChar`) arrays are automatically turned into Strings or String arrays, with dimensionality one less than that suggested by the `arraysize` attribute
- The element may be `null`

In any case the class of returned objects in a given column may be determined by calling the `getContentClass(int)` method.

Author:
  Mark Taylor

### Method Summary

All Methods Instance Methods Abstract Methods
`java.lang.Object` `getCell​(long irow, int icol)` Returns the contents of a given table cell (optional).
`int` `getColumnCount()` Returns the number of columns in the table data.
`java.lang.Class<?>` `getContentClass​(int icol)` Returns a class to which all elements in a given column can be cast.
`java.lang.Object[]` `getRow​(long irow)` Returns the contents of a given table row (optional).
`long` `getRowCount()` Returns the number of rows in the table data.
`uk.ac.starlink.table.RowSequence` `getRowSequence()` Returns an object which can iterate over all the rows in the table data sequentially.
`boolean` `isRandom()` Indicates whether random access is provided by this table.

### Method Detail

#### getColumnCount

    int getColumnCount()

Returns the number of columns in the table data.

Returns:
  number of cells in each row

#### getRowCount

    long getRowCount()

Returns the number of rows in the table data. If this cannot be determined (easily), the value -1 may be returned. The result will always be positive if `isRandom()` returns true.

Returns:
  number of rows, or -1 if unknown

#### getContentClass

    java.lang.Class<?> getContentClass​(int icol)

Returns a class to which all elements in a given column can be cast.

Parameters:
  `icol` - the column (0-based)
Returns:
  a class to which any non-null element returned by this object in column `icol` will belong

#### getRowSequence

    uk.ac.starlink.table.RowSequence getRowSequence()
                                             throws java.io.IOException

Returns an object which can iterate over all the rows in the table data sequentially.

Returns:
  an object providing sequential access to the data
Throws:
  `java.io.IOException`

#### isRandom

    boolean isRandom()

Indicates whether random access is provided by this table. Only if the result is true may the `getRow(long)` and `getCell(long, int)` methods be used.

Returns:
  `true` iff random access methods are available

#### getCell

    java.lang.Object getCell​(long irow,
                             int icol)
                      throws java.io.IOException

Returns the contents of a given table cell (optional). The class of the returned object will be compatible with that returned by `getContentClass(icol)`. Only provided if `getRandom` returns true.

Parameters:
  `irow` - row index
  `icol` - column index
Returns:
  contents of the cell at `irow`, `icol`
Throws:
  `java.io.IOException` - if there is I/O trouble
  `java.lang.UnsupportedOperationException` - if `isRandom` returns false

#### getRow

    java.lang.Object[] getRow​(long irow)
                       throws java.io.IOException

Returns the contents of a given table row (optional). Only provided if `getRandom` returns true.

Parameters:
  `irow` - row index
Returns:
  array of objects giving the cells in row `irow` (one cell per column)
Throws:
  `java.io.IOException` - if there is I/O trouble
  `java.lang.UnsupportedOperationException` - if `isRandom` returns false