Package nom.tam.fits

Interface TableData

All Known Implementing Classes:
AbstractTableData, AsciiTable, BinaryTable, CompressedImageData, CompressedTableData
public interface TableData

Interface for accessing binary and ASCII table data.

Note, that this interface is the big sister DataTable, with nearly identical method signstures. But there are differences too, such as the type of argument of setting row data, and when and what excpetions are thrown. This one also has includes additional methods for table manipulation. Overall it would have been a more prudent design to consolidate the two interfaces but this is what we have so we stick to it. However, mabe this is something an upcoming major release may address...

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    addColumn(Object newCol)
    Add a column to the table, without updating the header of an encompassing HDU.
    int
    addRow(Object[] newRow)
    Add a row at the end of the table without updating the header of an encompassing HDU.
    default int
    addRowEntries(Object... entries)
    Like addRow(Object[]), but with a vararg list of row entries.
    void
    deleteColumns(int col, int len)
    Removes a set of consecutive columns from this table, without updating assocu=iated the header information for the columns that were removed.
    void
    deleteRows(int row, int len)
    Removes a set of consecutive rows from this table without updating any associated header information for an encompassing HDU.
    Object
    getColumn(int col)
    Returns the data for a particular column in as an array of elements.
    Object
    getElement(int row, int col)
    Returns the data element in this table.
    int
    getNCols()
    Returns the number of columns contained in this table.
    int
    getNRows()
    Returns the number of columns contained in this table.
    Object[]
    getRow(int row)
    Returns an array of elements in a particualr table row.
    void
    setColumn(int col, Object newCol)
    Sets new data for a table column.
    void
    setElement(int row, int col, Object element)
    Sets new data element in this table.
    void
    setRow(int row, Object[] newRow)
    Sets new data for a table row.
    default void
    setRowEntries(int row, Object... entries)
    Like setRow(int, Object[]) but with vararg list of entries.
    void
    updateAfterDelete(int oldNcol, Header hdr)
    Deprecated.
    It is not entirely foolproof for keeping the header in sync -- it is better to (re)wrap tables in a new HDU after column deletions, and then edit the new header as necessary to incorporate custom entries.

  • Method Details

    • addColumn

      int addColumn(Object newCol) throws FitsException
      Add a column to the table, without updating the header of an encompassing HDU. You should not use this method on tables already in an HDU, since it will not update the HDUs headers. Instead you can either use TableHDU.addColumn(Object) or else create a new HDU for the table once the editing is copmleted -- adding or migrating any custom header entries as necessary after.
      Parameters:
      newCol - the new column information. it should be either a primitive array, in which each element stores a scalar value for every row, or else an Object[] where type of all of the constituents is identical. Multidimensional data should have the same layout in each row, but varied length one-dimensional arrays are OK. The arrat's length must match the number of rows already contained in the table, unless the table is still empty.
      Returns:
      the number of columns in the adapted table
      Throws:
      FitsException - if the operation failed
      See Also:

    • addRow

      int addRow(Object[] newRow) throws FitsException
      Add a row at the end of the table without updating the header of an encompassing HDU. You should not use this method on tables already in an HDU, since it will not update the HDUs headers. Instead you can use TableHDU.addRow(Object[]) or else create a new HDU for the table once the editing is completed -- adding or migrating any custom header entries as necessary after.
      Parameters:
      newRow - An array of elements to be added. Each element of o should be an array of primitives or a String.
      Returns:
      the number of rows in the adapted table
      Throws:
      FitsException - if the operation failed
      See Also:

    • addRowEntries

      default int addRowEntries(Object... entries) throws FitsException
      Like addRow(Object[]), but with a vararg list of row entries.
      Parameters:
      entries - A vararg list of elements to be added. Each element of o should be an array of primitives or a String.
      Returns:
      the number of rows in the adapted table
      Throws:
      FitsException - if the operation failed
      See Also:

    • deleteColumns

      void deleteColumns(int col, int len) throws FitsException
      Removes a set of consecutive columns from this table, without updating assocu=iated the header information for the columns that were removed. You should not use this method on tables already in an HDU, since it will not update the HDUs headers. Instead you should always create a new HDU for the table after editing, adding or migrating any custom header entries as necessary after.
      Parameters:
      col - the 0-based index of the first column to remove
      len - the number of subsequent columns to remove
      Throws:
      FitsException - if the table could not be modified
      See Also:

    • deleteRows

      void deleteRows(int row, int len) throws FitsException
      Removes a set of consecutive rows from this table without updating any associated header information for an encompassing HDU. You should not use this method on tables already in an HDU, since it will not update the HDUs headers. Instead you should always create a new HDU for the table after editing, adding or migrating any custom header entries as necessary after.
      Parameters:
      row - the 0-based index of the first row to remove
      len - the number of subsequent rows to remove
      Throws:
      FitsException - if the table could not be modified
      See Also:

    • getColumn

      Object getColumn(int col) throws FitsException

      Returns the data for a particular column in as an array of elements. See addColumn(Object) for more information about the format of data elements in general.

      Parameters:
      col - The 0-based column index.
      Returns:
      an array of primitives (for scalar columns), or else an Object[] array, or possibly null
      Throws:
      FitsException - if the table could not be accessed
      See Also:

    • getElement

      Object getElement(int row, int col) throws FitsException

      Returns the data element in this table. Elements are always stored as arrays even when scalar types. Thus a single double value will be returned as a double[1]. For most column types the storage type of the array matches that of their native Java type, but there are exceptions:

      • Character arrays in FITS are stored as byte[] or short[], depending on the FitsFactory.setUseUnicodeChars(boolean) setting, not unicode Java char[]. Therefore, this call will return byte[] or short[], the same as for a byte or 16-bit integer array. As a result if a new table is created with the returned data, the new table column will change its FITS column type from A to B or I.
      • Complex values in FITS are stored as float[2] or double[2], not as a ComplexValue type. Therefore, this call will return float[] or double[], the same as for a float array. As a result if a new table is created with the returned data, the new table column will change it's FITS column type from C to F, or from M to D,.
      Parameters:
      row - the 0-based row index of the element
      col - the 0-based column index of the element
      Returns:
      A primitive array containing the data for the the specified (row, col) entry in the table.
      Throws:
      FitsException - if the table could not be accessed
      See Also:

    • getNCols

      int getNCols()
      Returns the number of columns contained in this table.
      Returns:
      the current number of columns in the table.
      See Also:

    • getNRows

      int getNRows()
      Returns the number of columns contained in this table.
      Returns:
      the current number of columns in the table.
      See Also:

    • getRow

      Object[] getRow(int row) throws FitsException
      Returns an array of elements in a particualr table row. See getElement(int, int) for more information about the format of each element in the row.
      Parameters:
      row - the 0-based row index
      Returns:
      an object containing the row data (for all column) of the specified row, or possubly null. See getElement(int, int) for more information about the format of each element in the row.
      Throws:
      FitsException - if the table could not be accessed
      See Also:

    • setColumn

      void setColumn(int col, Object newCol) throws FitsException
      Sets new data for a table column. See addColumn(Object) for more information on the column data format.
      Parameters:
      col - the 0-based column index
      newCol - an object containing the new column data (for all rows) of the specified column. See getColumn(int) for more information on the column data format.
      Throws:
      FitsException - if the table could not be modified
      See Also:

    • setElement

      void setElement(int row, int col, Object element) throws FitsException
      Sets new data element in this table. See getElement(int, int) for more information about the format of elements.
      Parameters:
      row - the 0-based row index of the element
      col - the 0-based column index of the element
      element - the new element at the specified table location as a primitive array.
      Throws:
      FitsException - if the table could not be modified
      See Also:

    • setRow

      void setRow(int row, Object[] newRow) throws FitsException
      Sets new data for a table row. See getElement(int, int) for more information about the format of elements.
      Parameters:
      row - the 0-based row index
      newRow - an object containing the row data (for all column) of the specified row. See getElement(int, int) for more information about the format of each element in the row.
      Throws:
      FitsException - if the table could not be modified
      See Also:

    • setRowEntries

      default void setRowEntries(int row, Object... entries) throws FitsException
      Like setRow(int, Object[]) but with vararg list of entries.
      Parameters:
      row - the 0-based row index
      entries - an object containing the row data (for all column) of the specified row. See getElement(int, int) for more information about the format of each element in the row.
      Throws:
      FitsException - if the table could not be modified
      See Also:

    • updateAfterDelete

      void updateAfterDelete(int oldNcol, Header hdr) throws FitsException
      Deprecated.
      It is not entirely foolproof for keeping the header in sync -- it is better to (re)wrap tables in a new HDU after column deletions, and then edit the new header as necessary to incorporate custom entries. May be removed from the API in the future.
      Updates the table dimensions in the header following deletion. Whoever calls deleteColumns(int, int) on this table should call this method after the deletion(s), at least once after all desired column deletions have been processed).
      Parameters:
      oldNcol - The number of columns in the table before the first call to deleteColumns(int, int).
      hdr - The table header
      Throws:
      FitsException - if the header could not be updated