uk.ac.starlink.table

## Class Tables

- java.lang.Object
- - uk.ac.starlink.table.Tables

-     public class Tables
      extends java.lang.Object

  Utility class for miscellaneous table-related functionality.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static DefaultValueInfo` | `DEC_INFO` ValueInfo representing Declination.
    `static ValueInfo` | `NULL_VALUE_INFO` ValueInfo which may be used as part of a column's metadata to indicate a special value (preferably a `Number` that should be interpreted as a null (blank).
    `static DefaultValueInfo` | `RA_INFO` ValueInfo representing Right Ascension.
    `static ValueInfo` | `UBYTE_FLAG_INFO` ValueInfo which may be used as part of a column's auxiliary metadata to indicate that the column's data represents, and can be serialised as, unsigned byte values.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Tables()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static TableSequence` | `arrayTableSequence(StarTable[] tables)` Convenience method to construct a TableSequence for a supplied array of tables.
    `static int` | `assertLongToInt(long lval)` Casts a long to an int, with an assertion that no truncation occurs.
    `static int` | `checkedLongToInt(long lval)` Convenience method to get an `int` value from a `long`.
    `static void` | `checkTable(StarTable table)` Diagnostic method which tests the invariants of a StarTable.
    `static java.lang.String` | `collapseWhitespace(java.lang.String txt)` Collapses whitespace in a string.
    `static StarTable` | `deleteColumn(StarTable startab, int icol)` Returns a table equivalent to the original but with a given column deleted.
    `static void` | `fixColumns(ColumnInfo[][] infoLists, JoinFixAction[] fixActs)` Performs deduplication of column names for N lists of column metadata objects that will be combined to form a new table.
    `static <T> T` | `getAuxDatumValue(ValueInfo info, ValueInfo auxKey, java.lang.Class<T> auxClazz)` Utility method to return an auxiliary metadata item from a ValueInfo.
    `static ColumnInfo[]` | `getColumnInfos(StarTable startab)` Convenience method to return an array of all the column headers in a given table.
    `static RowSplittable` | `getDefaultRowSplittable(StarTable table)` Returns a RowSplittable object with generic characteristics for a given table.
    `static DescribedValue` | `getDescribedValueByName(java.util.Collection<DescribedValue> dvals, java.lang.String name)` Utility method to locate an element in a list of DescribedValue given the name of its ValueInfo member.
    `static java.lang.String[]` | `getElementLabels(int[] shape)` Returns an array of strings suitable as labels or label suffixes for elements of an array as returned by `ValueInfo.getShape()`.
    `static <T> T` | `getTypedValue(DescribedValue dval, java.lang.Class<T> clazz)` Utility method to get a typed value from a, possibly null, described value.
    `static java.lang.String` | `getUtype(ValueInfo info)` Deprecated. use `ValueInfo.getUtype()` instead
    `static java.lang.Object` | `getValue(java.util.Collection<DescribedValue> dvals, ValueInfo info)` Returns the value from a list of `DescribedValue` objects which corresponds to a given info key.
    `static java.lang.String` | `getXtype(ValueInfo info)` Deprecated. use `ValueInfo.getXtype()` instead
    `static boolean` | `isBlank(java.lang.Object value)` Indicates whether a given value is conventionally regarded as a blank value.
    `static StarTable` | `randomTable(StarTable startab)` Returns a table based on a given table and guaranteed to have random access.
    `static void` | `setDescribedValue(java.util.Collection<DescribedValue> dvals, DescribedValue dval)` Utility method to update a list of DescribedValues with a new entry.
    `static void` | `setUtype(ValueInfo info, java.lang.String utype)` Deprecated. use `DefaultValueInfo.setUtype(java.lang.String)` instead
    `static void` | `setXtype(ValueInfo info, java.lang.String xtype)` Deprecated. use `DefaultValueInfo.setXtype(java.lang.String)` instead
    `static TableSequence` | `singleTableSequence(StarTable table)` Convenience method to construct a TableSequence for a single table.
    `static StarTable` | `sortTable(StarTable table, int[] colIndices, boolean up, boolean nullsLast)` Returns a sorted version of a table.
    `static void` | `streamStarTable(StarTable source, TableSink sink)` Copies the data and metadata from a `StarTable` into a table sink.
    `static StarTable[]` | `tableArray(TableSequence tseq)` Convenience method to construct an array of StarTables from a TableSequence.
    `static java.lang.String` | `tableToString(StarTable table, java.lang.String ofmt)` Returns the contents of a table as a string.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### NULL_VALUE_INFO

          public static final ValueInfo NULL_VALUE_INFO

      ValueInfo which may be used as part of a column's metadata to indicate a special value (preferably a `Number` that should be interpreted as a null (blank). This should only be used on nullable columns, and really only on ones with a contentClass which is an integer (or possibly boolean) type; for other types, there is usually a value which can conventionally be understood to mean blank. Note this is here as a standard key to use when software components wish to communicate this information; the table system does not guarantee to honour instances of this value in a column's auxiliary data. It is the job of a StarTable instance to ensure that a `null` is returned from the table interrogation methods if that is what is meant.

    - #### UBYTE_FLAG_INFO

          public static final ValueInfo UBYTE_FLAG_INFO

      ValueInfo which may be used as part of a column's auxiliary metadata to indicate that the column's data represents, and can be serialised as, unsigned byte values. If so, the value is set to `Boolean.TRUE` (other values are treated as if absent). Data representing unsigned byte values will normally be represented within STIL by Short (16-bit integer) signed values, since there is no unsigned byte type in java. However, this flag may be used to indicate that the values can be serialised to unsigned-byte-capable output formats (for instance FITS and VOTable) using an unsigned byte serialisation. This annotation will normally only be honoured if the data type of the column is (scalar or array) short integer (16-bit) values. Some care should be exercised in applying this flag or (especially) modifying values in columns it applies to, that the actual column value range remains in the unsigned byte data range (0..255), since otherwise problems will result if it is serialised.

    - #### RA_INFO

          public static final DefaultValueInfo RA_INFO

      ValueInfo representing Right Ascension. The units are radians and it is non-nullable.

    - #### DEC_INFO

          public static final DefaultValueInfo DEC_INFO

      ValueInfo representing Declination. The units are radians and it is non-nullable.

  - ### Constructor Detail

    - #### Tables

          public Tables()

  - ### Method Detail

    - #### randomTable

          public static StarTable randomTable(StarTable startab)
                                       throws java.io.IOException

      Returns a table based on a given table and guaranteed to have random access. If the original table `stab` has random access then it is returned, otherwise a new random access table is built using its data.

      This convenience method is equivalent to calling `StoragePolicy.getDefaultPolicy().randomTable(startab)`.

      Parameters:
        `startab` - original table
      Returns:
        a table with the same data as `startab` and with `isRandom()==true`
      Throws:
        `java.io.IOException`

    - #### getColumnInfos

          public static ColumnInfo[] getColumnInfos(StarTable startab)

      Convenience method to return an array of all the column headers in a given table. Modifying this array will not affect the table.
      Parameters:
        `startab` - the table being enquired about
      Returns:
        an array of all the column headers

    - #### deleteColumn

          public static StarTable deleteColumn(StarTable startab,
                                               int icol)

      Returns a table equivalent to the original but with a given column deleted. The result may or may not be the same object as the input table.
      Parameters:
        `startab` - the table from which to delete a column
        `icol` - the index of the column to be deleted
      Throws:
        `java.lang.IndexOutOfBoundsException` - if `startab` has no column at `icol`

    - #### streamStarTable

          public static void streamStarTable(StarTable source,
                                             TableSink sink)
                                      throws java.io.IOException

      Copies the data and metadata from a `StarTable` into a table sink. This method is supplied for convenience; its implementation is very straightforward.
      Parameters:
        `source` - table to be copied
        `sink` - table destination
      Throws:
        `java.io.IOException`

    - #### getDefaultRowSplittable

          public static RowSplittable getDefaultRowSplittable(StarTable table)
                                                       throws java.io.IOException

      Returns a RowSplittable object with generic characteristics for a given table. For a random-access table the splitting will be based on `RowAccess` objects, and for a non-random table it will not be capable of splits.
      Parameters:
        `table` - table
      Returns:
        splittable for potentially parallel iteration over rows
      Throws:
        `java.io.IOException`

    - #### checkTable

          public static void checkTable(StarTable table)
                                 throws java.io.IOException

      Diagnostic method which tests the invariants of a StarTable. This method returns no value, and throws an exception if a table is illegal in some way. If this method throws an exception when called on a given StarTable, that table is deemed to be bad in some way (buggy implementation or I/O trouble during access). This method is provided for convenience and diagnostics because there are a number of ways, some of them subtle, in which a StarTable can fail to fulfil its general contract.

      That a table passes this test does not guarantee that the table has no bugs. This method should not generally be used in production code, since it may be expensive in time and/or memory.

      Parameters:
        `table` - table to test
      Throws:
        `java.lang.AssertionError` - if an invariant is violated
        `java.io.IOException` - if there is an I/O error

    - #### isBlank

          public static boolean isBlank(java.lang.Object value)

      Indicates whether a given value is conventionally regarded as a blank value. For most objects this is equivalent to testing whether it is equall to `null`, but some classes have additional non-`null` values which count as blanks, for instance zero-length Strings and floating Not-A-Number values.
      Parameters:
        `value` - value to test
      Returns:
        true iff `value` counts as a blank value

    - #### collapseWhitespace

          public static java.lang.String collapseWhitespace(java.lang.String txt)

      Collapses whitespace in a string. This normalises the text in the sense of the XML Schema facet `whitespace='collapse'`: leading and trailing whitespace is removed, and any other run of whitespace is replaced by a single space character.
      Parameters:
        `txt` - input string (may be null)
      Returns:
        string with whitespaces collapsed

    - #### singleTableSequence

          public static TableSequence singleTableSequence(StarTable table)

      Convenience method to construct a TableSequence for a single table.
      Parameters:
        `table` - table
      Returns:
        table sequence with just one element

    - #### arrayTableSequence

          public static TableSequence arrayTableSequence(StarTable[] tables)

      Convenience method to construct a TableSequence for a supplied array of tables.
      Parameters:
        `tables` - table array
      Returns:
        table sequence containing input tables

    - #### tableArray

          public static StarTable[] tableArray(TableSequence tseq)
                                        throws java.io.IOException

      Convenience method to construct an array of StarTables from a TableSequence.
      Parameters:
        `tseq` - table sequence
      Returns:
        array containing tables from sequence
      Throws:
        `java.io.IOException`

    - #### sortTable

          public static StarTable sortTable(StarTable table,
                                            int[] colIndices,
                                            boolean up,
                                            boolean nullsLast)
                                     throws java.io.IOException

      Returns a sorted version of a table. The sorting is done on the values of one or more columns, as specified by the `colIndices` argument; the first element is the primary sort key, but in case of a tie the second element is used, and so on. The original table is not affected. The natural comparison order of the values in the table is used, and blank values may be ranked at the start or end of the collation order.
      Parameters:
        `table` - table to sort - must be random access
        `colIndices` - indices of the columns which are to act as sort keys; first element is primary key etc
        `up` - true for sorting into ascending order, false for descending order
        `nullsLast` - true if blank values should be considered last in the collation order, false if they should be considered first
      Returns:
        a table with the same rows as `table` but in an order determined by the other arguments
      Throws:
        `java.io.IOException` - if `table.isRandom` is not true

    - #### tableToString

          public static java.lang.String tableToString(StarTable table,
                                                       java.lang.String ofmt)

      Returns the contents of a table as a string. Only intended for small tables, for instance during debugging.
      Parameters:
        `table` - input table
        `ofmt` - output format specifier, or null for plain text output
      Returns:
        stringified table

    - #### checkedLongToInt

          public static int checkedLongToInt(long lval)

      Convenience method to get an `int` value from a `long`. If the supplied long integer `lval` is out of the range which can be represented in an `int`, then unlike a typecast, this method will throw an `IllegalArgumentException`.
      Parameters:
        `lval` - the `long` value to convert
      Returns:
        an `int` value which has the same value as `lval`
      Throws:
        `java.lang.IllegalArgumentException` - if the conversion cannot be done

    - #### assertLongToInt

          public static int assertLongToInt(long lval)

      Casts a long to an int, with an assertion that no truncation occurs.
      Parameters:
        `lval` - long value, asserted to be in the range Integer.MIN_VALUE..Integer.MAX_VALUE
      Returns:
        truncated version of `lval`

    - #### getElementLabels

          public static java.lang.String[] getElementLabels(int[] shape)

      Returns an array of strings suitable as labels or label suffixes for elements of an array as returned by `ValueInfo.getShape()`. If the given `shape` cannot be decomposed into a fixed size array, returns `null`.
      Parameters:
        `shape` - vector giving dimensions of an array value
      Returns:
        array with one element for each element of the array values (in their natural order), or null for non-array shapes

    - #### getUtype

          @Deprecated
          public static java.lang.String getUtype(ValueInfo info)

      Deprecated. use `ValueInfo.getUtype()` instead
      Returns the Utype associated with a given metadata item.
      Parameters:
        `info` - metadata item
      Returns:
        utype string, or null if none is available
      See Also:
        `setUtype(uk.ac.starlink.table.ValueInfo, java.lang.String)`

    - #### setUtype

          @Deprecated
          public static void setUtype(ValueInfo info,
                                                  java.lang.String utype)

      Deprecated. use `DefaultValueInfo.setUtype(java.lang.String)` instead
      Tries to set the Utype for a given metadata item.
      Parameters:
        `info` - metadata item
        `utype` - new utype value
      See Also:
        `getUtype(uk.ac.starlink.table.ValueInfo)`

    - #### getXtype

          @Deprecated
          public static java.lang.String getXtype(ValueInfo info)

      Deprecated. use `ValueInfo.getXtype()` instead
      Returns the extended type value associated with a given metadata item. The XType corresponds to the `xtype` attribute of the VOTable format. Other table formats may or may not be able to represent it.
      Parameters:
        `info` - metadata item
      Returns:
        xtype string, or null if none is available

    - #### setXtype

          @Deprecated
          public static void setXtype(ValueInfo info,
                                                  java.lang.String xtype)

      Deprecated. use `DefaultValueInfo.setXtype(java.lang.String)` instead
      Tries to set the Xtype for a given metadata item.
      Parameters:
        `info` - metadata item
        `xtype` - new xtype value
      See Also:
        `getXtype(uk.ac.starlink.table.ValueInfo)`

    - #### setDescribedValue

          public static void setDescribedValue(java.util.Collection<DescribedValue> dvals,
                                               DescribedValue dval)

      Utility method to update a list of DescribedValues with a new entry. If an item with the same name as the new entry already exists, it is removed.
      Parameters:
        `dvals` - list to modify
        `dval` - new entry to add

    - #### getDescribedValueByName

          public static DescribedValue getDescribedValueByName(java.util.Collection<DescribedValue> dvals,
                                                               java.lang.String name)

      Utility method to locate an element in a list of DescribedValue given the name of its ValueInfo member.
      Parameters:
        `dvals` - list to query
        `name` - required value of name
      Returns:
        element of `dvals` for which `getInfo().getName()` matches `name`

    - #### getAuxDatumValue

          public static <T> T getAuxDatumValue(ValueInfo info,
                                               ValueInfo auxKey,
                                               java.lang.Class<T> auxClazz)

      Utility method to return an auxiliary metadata item from a ValueInfo.
      Parameters:
        `info` - metadata item
        `auxKey` - info identifying aux metadata entry in `info`
        `auxClazz` - required result type
      Returns:
        typed aux metadata item requested, or null if it doesn't exist or has the wrong type

    - #### getTypedValue

          public static <T> T getTypedValue(DescribedValue dval,
                                            java.lang.Class<T> clazz)

      Utility method to get a typed value from a, possibly null, described value.
      Parameters:
        `dval` - described value, or null
        `clazz` - required return type
      Returns:
        typed value of `dval`, or null if dval is null, or if dval's value has the wrong type

    - #### getValue

          public static java.lang.Object getValue(java.util.Collection<DescribedValue> dvals,
                                                  ValueInfo info)

      Returns the value from a list of `DescribedValue` objects which corresponds to a given info key. If the key is not represented in the list, or if its value is null, then null is returned.
      Parameters:
        `dvals` - list of DescribedValue objects
        `info` - key giving the value you want
      Returns:
        matching value

    - #### fixColumns

          public static void fixColumns(ColumnInfo[][] infoLists,
                                        JoinFixAction[] fixActs)

      Performs deduplication of column names for N lists of column metadata objects that will be combined to form a new table. The arguments are matched arrays; each list of column infos has a corresponding renaming policy. The ColumnInfo objects are renamed in place as required.
      Parameters:
        `infoLists` - array of N arrays of column metadata objects
        `fixActs` - array of N policies for renaming columns