Package nom.tam.fits

Class AsciiTable

java.lang.Object
nom.tam.fits.Data
nom.tam.fits.AbstractTableData
nom.tam.fits.AsciiTable
All Implemented Interfaces:
FitsElement, TableData
public class AsciiTable extends AbstractTableData
ASCII table data. ASCII tables are meant for human readability without any special tools. However, they are far less flexible or compact than BinaryTable. As such, users are generally discouraged from using this type of table to represent FITS table data. This class only supports scalar entries of type int, long, float, double, or else String types.
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    AsciiTable()
    Create an empty ASCII table
    AsciiTable(Header hdr)
    Deprecated.
    (for internal use) Visibility may be reduced to the package level in the future.
    AsciiTable(Header hdr, boolean preferInt)
    Deprecated.
    Use setI10PreferInt(boolean) instead prior to reading ASCII tables.

  • 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
    addColumn(Object newCol, int width)
    Adds an ASCII table column with the specified ASCII text width for storing its elements.
    int
    addRow(Object[] newRow)
    Beware that adding rows to ASCII tables may be very inefficient.
    void
    deleteColumns(int start, 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 start, int len)
    Beware that repeatedly deleting rows from ASCII tables may be very inefficient.
    static AsciiTable
    fromColumnMajor(Object[] columns)
    Creates an ASCII table from existing data in column-major format order.
    Object
    getColumn(int col)
    Returns the data for a particular column in as a flattened 1D array of elements.
    final Class<?>
    getColumnType(int col)
    Return the data type in the specified column, such as int.class or String.class.
    Object[]
    getData()
    Returns the underlying Java representation of the data contained in this HDU's data segment.
    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.
    int
    getRowLen()
    Get the number of bytes in a row
    static boolean
    isI10PreferInt()
    Checks if I10 columns should be treated as containing 32-bit int values, rather than 64-bit long values, when possible.
    boolean
    isNull(int row, int col)
    Checks if an element is null.
    void
    read(ArrayDataInput in)
    Reads the data or skips over it for reading later, depending on whether reading from a stream or a random acessible input, respectively.
    void
    setColumn(int col, Object newData)
    Sets new data for a table column.
    void
    setElement(int row, int col, Object newData)
    Sets new data element in this table.
    static void
    setI10PreferInt(boolean value)
    Controls how columns with format "I10" are handled; this is tricky because some, but not all, integers that can be represented in 10 characters form 32-bit integers.
    void
    setNull(int row, int col, boolean flag)
    Mark (or unmark) an element as null.
    void
    setRow(int row, Object[] newData)
    Sets new data for a table row.
    AsciiTableHDU
    toHDU()
    Returns an approprotae HDU object that encapsulates this FITS data, and contains the minimal mandatory header description for that data.
    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 and editing the header as necessary to incorporate custom entries.
    void
    write(ArrayDataOutput str)
    Writes the contents of the element to a data sink, adding padding as necessary if the element (such as a header or data segment) is expected to complete the FITS block of 2880 bytes.

    Methods inherited from class nom.tam.fits.Data

    calcChecksum, detach, getFileOffset, getKernel, getSize, isDeferred, isEmpty, reset, rewrite, rewriteable

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface nom.tam.fits.TableData

    addRowEntries, setRowEntries

  • Constructor Details

    • AsciiTable

      public AsciiTable()
      Create an empty ASCII table

    • AsciiTable

      public AsciiTable(Header hdr) throws FitsException
      Deprecated.
      (for internal use) Visibility may be reduced to the package level in the future.
      Creates an ASCII table given a header. For tables that contain integer-valued columns of format I10, the setI10PreferInt(boolean) mayb be used to control whether to treat them as int or as long values (the latter is the default).
      Parameters:
      hdr - The header describing the table
      Throws:
      FitsException - if the operation failed

    • AsciiTable

      public AsciiTable(Header hdr, boolean preferInt) throws FitsException
      Deprecated.
      Use setI10PreferInt(boolean) instead prior to reading ASCII tables.

      Create an ASCII table given a header, with custom integer handling support.

      The preferInt parameter controls how columns with format "I10" are handled; this is tricky because some, but not all, integers that can be represented in 10 characters can be represented as 32-bit integers. Setting it true may make it more likely to avoid unexpected type changes during round-tripping, but it also means that some (large number) data in I10 columns may be impossible to read.

      Parameters:
      hdr - The header describing the table
      preferInt - if true, format "I10" columns will be assumed int.class, provided TLMINn/TLMAXn or TDMINn/TDMAXn limits (if defined) allow it. if false, I10 columns that have no clear indication of data range will be assumed long.class.
      Throws:
      FitsException - if the operation failed

  • Method Details

    • fromColumnMajor

      public static AsciiTable fromColumnMajor(Object[] columns) throws FitsException
      Creates an ASCII table from existing data in column-major format order.
      Parameters:
      columns - The data for scalar-valued columns. Each column must be an array of int[], long[], float[], double[], or else String[], containing the same number of elements in each column (the number of rows).
      Returns:
      a new ASCII table with the data. The tables data may be partially independent from the argument. Modifications to the table data, or that to the argument have undefined effect on the other object. If it is important to decouple them, you can use a ArrayFuncs.deepClone(Object) of your original data as an argument.
      Throws:
      FitsException - if the argument is not a suitable representation of FITS data in columns
      Since:
      1.19
      See Also:

    • getColumnType

      public final Class<?> getColumnType(int col)
      Return the data type in the specified column, such as int.class or String.class.
      Parameters:
      col - The 0-based column index
      Returns:
      the class of data in the specified column.
      Since:
      1.16

    • addColumn

      public int addColumn(Object newCol) throws FitsException, IllegalArgumentException
      Description copied from interface: TableData
      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
      IllegalArgumentException
      See Also:

    • addColumn

      public int addColumn(Object newCol, int width) throws FitsException, IllegalArgumentException
      Adds an ASCII table column with the specified ASCII text width for storing its elements.
      Parameters:
      newCol - The new column data, which must be one of: int[], long[], float[], double[], or else String[]. If the table already contains data, the length of the array must match the number of rows already contained in the table.
      width - the ASCII text width of the for the column entries (without the string termination).
      Returns:
      the number of columns after this one is added.
      Throws:
      IllegalArgumentException - if the column data is not an array or the specified text width is ≤1.
      FitsException - if the column us of an unsupported data type or if the number of entries does not match the number of rows already contained in the table.
      See Also:

    • addRow

      public int addRow(Object[] newRow) throws FitsException
      Beware that adding rows to ASCII tables may be very inefficient. Avoid addding more than a few rows if you can.
      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:

    • deleteColumns

      public void deleteColumns(int start, int len) throws FitsException
      Description copied from interface: TableData
      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:
      start - 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

      public void deleteRows(int start, int len) throws FitsException
      Beware that repeatedly deleting rows from ASCII tables may be very inefficient. Avoid calling this more than once (or a few times) if you can.
      Parameters:
      start - 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:

    • read

      public void read(ArrayDataInput in) throws FitsException
      Description copied from class: Data

      Reads the data or skips over it for reading later, depending on whether reading from a stream or a random acessible input, respectively.

      In case the argument is a an instance of RandomAccess input (such as a FitsFile, the call will simply note where in the file the data segment can be found for reading at a later point, only when the data content is accessed. This 'deferred' reading behavior make it possible to process large HDUs even with small amount of RAM, and can result in a significant performance boost when inspectring large FITS files, or using only select content from large FITS files.

      Specified by:
      read in interface FitsElement
      Overrides:
      read in class Data
      Parameters:
      in - The input data stream
      Throws:
      PaddingException - if there is missing padding between the end of the data segment and the enf-of-file.
      FitsException - if the data appears to be corrupted.
      See Also:

    • getColumn

      public Object getColumn(int col) throws FitsException

      Returns the data for a particular column in as a flattened 1D 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.
      Throws:
      FitsException - if the table could not be accessed
      See Also:

    • getData

      public Object[] getData() throws FitsException
      Description copied from class: Data
      Returns the underlying Java representation of the data contained in this HDU's data segment. Typically it will return a Java array of some kind.
      Overrides:
      getData in class Data
      Returns:
      the underlying Java representation of the data core object, such as a multi-dimensional Java array.
      Throws:
      FitsException - if the data could not be gathered.
      See Also:

    • getElement

      public Object getElement(int row, int col) throws FitsException
      Description copied from interface: TableData

      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

      public int getNCols()
      Description copied from interface: TableData
      Returns the number of columns contained in this table.
      Returns:
      the current number of columns in the table.
      See Also:

    • getNRows

      public int getNRows()
      Description copied from interface: TableData
      Returns the number of columns contained in this table.
      Returns:
      the current number of columns in the table.
      See Also:

    • getRow

      public Object[] getRow(int row) throws FitsException
      Description copied from interface: TableData
      Returns an array of elements in a particualr table row. See TableData.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 TableData.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:

    • getRowLen

      public int getRowLen()
      Get the number of bytes in a row
      Returns:
      The number of bytes for a single row in the table.

    • isNull

      public boolean isNull(int row, int col)
      Checks if an element is null.
      Parameters:
      row - The 0-based row
      col - The 0-based column
      Returns:
      if the given element has been nulled.

    • setColumn

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

    • setElement

      public void setElement(int row, int col, Object newData) throws FitsException
      Description copied from interface: TableData
      Sets new data element in this table. See TableData.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
      newData - the new element at the specified table location as a primitive array.
      Throws:
      FitsException - if the table could not be modified
      See Also:

    • setNull

      public void setNull(int row, int col, boolean flag)
      Mark (or unmark) an element as null. Note that if this FITS file is latter written out, a TNULL keyword needs to be defined in the corresponding header. This routine does not add an element for String columns.
      Parameters:
      row - The 0-based row.
      col - The 0-based column.
      flag - True if the element is to be set to null.

    • setRow

      public void setRow(int row, Object[] newData) throws FitsException
      Description copied from interface: TableData
      Sets new data for a table row. See TableData.getElement(int, int) for more information about the format of elements.
      Parameters:
      row - the 0-based row index
      newData - an object containing the row data (for all column) of the specified row. See TableData.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

      public 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 and editing the header as necessary to incorporate custom entries. May be removed from the API in the future.
      Description copied from interface: TableData
      Updates the table dimensions in the header following deletion. Whoever calls TableData.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 TableData.deleteColumns(int, int).
      hdr - The table header
      Throws:
      FitsException - if the header could not be updated

    • write

      public void write(ArrayDataOutput str) throws FitsException
      Description copied from interface: FitsElement
      Writes the contents of the element to a data sink, adding padding as necessary if the element (such as a header or data segment) is expected to complete the FITS block of 2880 bytes.
      Specified by:
      write in interface FitsElement
      Specified by:
      write in class Data
      Parameters:
      str - The data sink.
      Throws:
      FitsException - if the write was unsuccessful.

    • toHDU

      public AsciiTableHDU toHDU()
      Description copied from class: Data
      Returns an approprotae HDU object that encapsulates this FITS data, and contains the minimal mandatory header description for that data.
      Specified by:
      toHDU in class Data
      Returns:
      a HDU object ocntaining the data and its minimal required header description

    • setI10PreferInt

      public static void setI10PreferInt(boolean value)

      Controls how columns with format "I10" are handled; this is tricky because some, but not all, integers that can be represented in 10 characters form 32-bit integers. Setting it true may make it more likely to avoid unexpected type changes during round-tripping, but it also means that some values in I10 columns may be impossible to read. The default behavior is to assume true, and thus to treat I10 columns as int values.

      Parameters:
      value - if true, format "I10" columns will be assumed int.class, provided TLMINn/TLMAXn or TDMINn/TDMAXn limits (if defined) allow it. if false, I10 columns that have no clear indication of data range will be assumed long.class.
      Since:
      1.19
      See Also:

    • isI10PreferInt

      public static boolean isI10PreferInt()
      Checks if I10 columns should be treated as containing 32-bit int values, rather than 64-bit long values, when possible.
      Returns:
      true if I10 columns should be treated as containing 32-bit int values, otherwise false.
      Since:
      1.19
      See Also: