Package nom.tam.fits

Class TableHDU<T extends AbstractTableData>

java.lang.Object

nom.tam.fits.BasicHDU<T>

nom.tam.fits.TableHDU<T>

Type Parameters:

T - the generic type of table data contained in this HDU instance.

All Implemented Interfaces:

FitsElement

Direct Known Subclasses:

AsciiTableHDU, BinaryTableHDU

public abstract class TableHDU<T extends AbstractTableData>
extends BasicHDU<T>

Base class for binary and ASCII table implementations.

Field Summary

Fields inherited from class nom.tam.fits.BasicHDU

BITPIX_BYTE, BITPIX_DOUBLE, BITPIX_FLOAT, BITPIX_INT, BITPIX_LONG, BITPIX_SHORT

Method Summary

Modifier and Type	Method	Description
int	addColumn(Object newCol)	Add a column to the table without any associated header information.
int	addRow(Object[] newRows)	Add a row to the end of the table.
void	deleteColumnsIndexOne(int column, int len)	Deprecated. It is not entirely foolproof for keeping the header in sync -- it is better to use TableData.deleteColumns(int, int) to edit tables before wrapping them in an HDU and editing the header as necessary to incorporate custom entries.
void	deleteColumnsIndexOne(int column, int len, String[] fields)	Deprecated. It is not entirely foolproof for keeping the header in sync -- it is better to use TableData.deleteColumns(int, int) to edit tables before wrapping them in an HDU and editing the header as necessary to incorporate custom entries.
void	deleteColumnsIndexZero(int column, int len)	Deprecated. It is not entirely foolproof for keeping the header in sync -- it is better to use TableData.deleteColumns(int, int) to edit tables before wrapping them in an HDU and editing the header as necessary to incorporate custom entries.
void	deleteColumnsIndexZero(int column, int len, IFitsHeader[] fields)	Deprecated. It is not entirely foolproof for keeping the header in sync -- it is better to use TableData.deleteColumns(int, int) to edit tables before wrapping them in an HDU and editing the header as necessary to incorporate custom entries.
void	deleteRows(int row)	Deprecated. It is not entirely foolproof for keeping the header in sync -- it is better to use TableData.deleteRows(int, int) to edit tables before wrapping them in an HDU and editing the header as necessary to incorporate custom entries.
void	deleteRows(int firstRow, int nRow)	Deprecated. It is not entirely foolproof for keeping the header in sync -- it is better to use TableData.deleteRows(int, int) to edit tables before wrapping them in an HDU and editing the header as necessary to incorporate custom entries.
int	findColumn(String colName)	Find the 0-based column index corresponding to a particular column name.
Object	getColumn(int col)	Returns the data for a particular column in as an array of elements.
Object	getColumn(String colName)	Returns the data for a particular column in as an array of elements.
String	getColumnFormat(int index)	Get the FITS type of a column in the table.
String	getColumnMeta(int index, String type)	Convenience method for getting column data.
String	getColumnName(int index)	Gets the name of a column in the table, as it appears in this HDU's header.
Object[]	getColumns()	Returns the data for all columns in as an array.
static String	getDefaultColumnName(int col)	Returns the default name for a columns with the specified index, to use if no column name was explicitly defined
Object	getElement(int row, int col)	Returns a specific element from this table
int	getNCols()	Get the number of columns for this table
int	getNRows()	Get the number of rows for this table
Object[]	getRow(int row)	Returns a specific row from this table
void	setColumn(int col, Object newCol)	Update a column within a table.
void	setColumn(String colName, Object newCol)	Update a column within a table.
void	setColumnMeta(int index, String key, Boolean value, String comment, boolean after)	Specify column metadata for a given column in a way that allows all of the column metadata for a given column to be organized together.
void	setColumnMeta(int index, String key, Number value, int precision, String comment, boolean after)	Specify column metadata for a given column in a way that allows all of the column metadata for a given column to be organized together.
void	setColumnMeta(int index, String key, Number value, String comment, boolean after)	Specify column metadata for a given column in a way that allows all of the column metadata for a given column to be organized together.
void	setColumnMeta(int index, String key, String value, String comment)	Specify column metadata for a given column in a way that allows all of the column metadata for a given column to be organized together.
void	setColumnMeta(int index, String key, String value, String comment, boolean after)	Deprecated. use setColumnMeta(int, IFitsHeader, String, String, boolean)
void	setColumnMeta(int index, IFitsHeader key, Number value, String comment, boolean after)	Specify column metadata for a given column in a way that allows all of the column metadata for a given column to be organized together.
void	setColumnMeta(int index, IFitsHeader key, String value, String comment, boolean after)	Specify column metadata for a given column in a way that allows all of the column metadata for a given column to be organized together.
void	setColumnName(int index, String name, String comment)	Sets the name / ID of a specific column in this table.
void	setCurrentColumn(int col)	Deprecated. (for internal use) Will be removed int the future (no longer used).
void	setCurrentColumn(int col, boolean after)	Deprecated. (for internal use) Will have private access in the future.
void	setElement(int row, int col, Object element)	Update a single element within the table.
void	setRow(int row, Object[] newRow)	Update a row within a table.

Methods inherited from class nom.tam.fits.BasicHDU

addValue, addValue, addValue, addValue, addValue, addValue, addValue, addValue, calcChecksum, card, getAuthor, getAxes, getBitpix, getBitPix, getBlankValue, getBScale, getBUnit, getBZero, getCreationDate, getData, getDummyHDU, getEpoch, getEquinox, getFileOffset, getGroupCount, getHeader, getInstrument, getKernel, getMaximumValue, getMinimumValue, getObject, getObservationDate, getObserver, getOrigin, getParameterCount, getReference, getSize, getStoredChecksum, getStoredDatasum, getTelescope, getTrimmedString, getTrimmedString, info, isData, isHeader, read, reset, rewrite, rewriteable, setChecksum, verifyDataIntegrity, verifyIntegrity, write

Methods inherited from class java.lang.Object

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

Method Details

getDefaultColumnName

public static String getDefaultColumnName(int col)

Returns the default name for a columns with the specified index, to use if no column name was explicitly defined

Parameters:

col - The zero-based Java index of the column

Returns:

The default column name to use if no other name was defined.

Since:

1.20

See Also:

• setColumnName(int, String, String)

addColumn

public int addColumn(Object newCol)
              throws FitsException

Add a column to the table without any associated header information.

Parameters:

newCol - the new column information. the newCol should be an Object[] where type of all of the constituents is identical. The length of data should match the other columns. Note: It is valid for data to be a 2 or higher dimensionality primitive array. In this case the column index is the first (in Java speak) index of the array. E.g., if called with int[30][20][10], the number of rows in the table should be 30 and this column will have elements which are 2-d integer arrays with TDIM = (10,20).

Returns:

the number of columns in the adapted table

Throws:

FitsException - if the operation failed

addRow

public int addRow(Object[] newRows)
           throws FitsException

Add a row to the end of the table. If this is the first row, then this will add appropriate columns for each of the entries. The rows to add must be supplied as column based array of arrays.

Parameters:

newRows - rows to add to the table

Returns:

the number of rows in the adapted table

Throws:

FitsException - if the operation failed

deleteColumnsIndexOne

public void deleteColumnsIndexOne(int column,
 int len)
                           throws FitsException

Deprecated.

It is not entirely foolproof for keeping the header in sync -- it is better to use TableData.deleteColumns(int, int) to edit tables before wrapping them in an HDU and editing the header as necessary to incorporate custom entries. May be removed from the API in the future.

Delete a set of columns from a table.

Parameters:

column - The one-indexed start column.

len - The number of columns to delete.

Throws:

FitsException - if the operation failed

deleteColumnsIndexOne

public void deleteColumnsIndexOne(int column,
 int len,
 String[] fields)
                           throws FitsException

Deprecated.

It is not entirely foolproof for keeping the header in sync -- it is better to use TableData.deleteColumns(int, int) to edit tables before wrapping them in an HDU and editing the header as necessary to incorporate custom entries. May be removed from the API in the future.

Delete a set of columns from a table.

Parameters:

column - The one-indexed start column.

len - The number of columns to delete.

fields - Stems for the header fields to be removed for the table.

Throws:

FitsException - if the operation failed

deleteColumnsIndexZero

public void deleteColumnsIndexZero(int column,
 int len)
                            throws FitsException

Deprecated.

It is not entirely foolproof for keeping the header in sync -- it is better to use TableData.deleteColumns(int, int) to edit tables before wrapping them in an HDU and editing the header as necessary to incorporate custom entries. May be removed from the API in the future.

Delete a set of columns from a table.

Parameters:

column - The one-indexed start column.

len - The number of columns to delete.

Throws:

FitsException - if the operation failed

deleteColumnsIndexZero

public void deleteColumnsIndexZero(int column,
 int len,
 IFitsHeader[] fields)
                            throws FitsException

Deprecated.

It is not entirely foolproof for keeping the header in sync -- it is better to use TableData.deleteColumns(int, int) to edit tables before wrapping them in an HDU and editing the header as necessary to incorporate custom entries. May be removed from the API in the future.

Delete a set of columns from a table.

Parameters:

column - The zero-indexed start column.

len - The number of columns to delete.

fields - Stems for the header fields to be removed for the table.

Throws:

FitsException - if the operation failed

deleteRows

public void deleteRows(int row)
                throws FitsException

Deprecated.

It is not entirely foolproof for keeping the header in sync -- it is better to use TableData.deleteRows(int, int) to edit tables before wrapping them in an HDU and editing the header as necessary to incorporate custom entries. May be removed from the API in the future.

Remove all rows from the table starting at some specific index from the table. Inspired by a routine by R. Mathar but re-implemented using the DataTable and changes to AsciiTable so that it can be done easily for both Binary and ASCII tables.

Parameters:

row - the (0-based) index of the first row to be deleted.

Throws:

FitsException - if an error occurs.

deleteRows

public void deleteRows(int firstRow,
 int nRow)
                throws FitsException

Deprecated.

It is not entirely foolproof for keeping the header in sync -- it is better to use TableData.deleteRows(int, int) to edit tables before wrapping them in an HDU and editing the header as necessary to incorporate custom entries. May be removed from the API in the future.

Remove a number of adjacent rows from the table. This routine was inspired by code by R.Mathar but re-implemented using changes in the ColumnTable class abd AsciiTable so that we can do it for all FITS tables.

Parameters:

firstRow - the (0-based) index of the first row to be deleted. This is zero-based indexing: 0<=firstrow< number of rows.

nRow - the total number of rows to be deleted.

Throws:

FitsException - If an error occurs in the deletion.

findColumn

public int findColumn(String colName)

Find the 0-based column index corresponding to a particular column name.

Parameters:

colName - the name of the column

Returns:

index of the column

getColumn

public Object getColumn(int col)
                 throws FitsException

Returns the data for a particular column in as an array of elements. See TableData.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:

• TableData.getColumn(int)
• setColumn(int, Object)
• getElement(int, int)
• getNCols()

getColumn

public Object getColumn(String colName)
                 throws FitsException

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

Parameters:

colName - The name or ID of the column as stored by the TTYPEn FITS header keyword.

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:

• TableData.getColumn(int)
• setColumn(int, Object)
• getElement(int, int)
• getNCols()

getColumnFormat

public String getColumnFormat(int index)
                       throws FitsException

Get the FITS type of a column in the table.

Parameters:

index - The 0-based index of the column.

Returns:

The FITS type.

Throws:

FitsException - if an invalid index was requested.

getColumnMeta

public String getColumnMeta(int index,
 String type)

Convenience method for getting column data. Note that this works only for metadata that returns a string value. This is equivalent to getStringValue(type+index);

Parameters:

index - index of the colum

type - the key type to get

Returns:

meta data string value

getColumnName

public String getColumnName(int index)

Gets the name of a column in the table, as it appears in this HDU's header. It may differ from a more currently assigned name of the binary table data column after the HDU creation or reading.

Parameters:

index - The 0-based column index.

Returns:

The column name.

See Also:

• BinaryTable.ColumnDesc.name()

getColumns

public Object[] getColumns()
                    throws FitsException

Returns the data for all columns in as an array. See TableData.addColumn(Object) for more information about the column format of each element in the returned array.

Returns:

An array containing the column data for all columns. Each entry in the returned array is itself 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:

• TableData.getColumn(int)
• setColumn(int, Object)
• getElement(int, int)
• getNCols()

getElement

public Object getElement(int row,
 int col)
                  throws FitsException

Returns a specific element from this table

Parameters:

row - the row index of the element

col - the column index of the element

Returns:

a specific element of the table using 0-based indices.

Throws:

FitsException - if the operation failed

See Also:

• getElement(int, int)

getNCols

public int getNCols()

Get the number of columns for this table

Returns:

The number of columns in the table.

getNRows

public int getNRows()

Get the number of rows for this table

Returns:

The number of rows in the table.

getRow

public Object[] getRow(int row)
                throws FitsException

Returns a specific row from this table

Parameters:

row - the index of the row to retreive

Returns:

a specific row of the table.

Throws:

FitsException - if the operation failed

See Also:

• setRow(int, Object[])

setColumn

public void setColumn(int col,
 Object newCol)
               throws FitsException

Update a column within a table. The new column should have the same format ast the column being replaced. See TableData.addColumn(Object) for more information about the column data format.

Parameters:

col - index of the column to replace

newCol - the replacement column

Throws:

FitsException - if the operation failed

See Also:

• getColumn(int)
• setColumn(String, Object)
• TableData.addColumn(Object)

setColumn

public void setColumn(String colName,
 Object newCol)
               throws FitsException

Update a column within a table. The new column should have the same format as the column being replaced. See TableData.addColumn(Object) for more information about the column data format.

Parameters:

colName - name of the column to replace

newCol - the replacement column

Throws:

FitsException - if the operation failed

See Also:

• getColumn(String)
• setColumn(int, Object)
• TableData.addColumn(Object)

setColumnMeta

public void setColumnMeta(int index,
 IFitsHeader key,
 String value,
 String comment,
 boolean after)
                   throws HeaderCardException

Specify column metadata for a given column in a way that allows all of the column metadata for a given column to be organized together.

Parameters:

index - The 0-based index of the column

key - The column key. I.e., the keyword will be key+(index+1)

value - The value to be placed in the header.

comment - The comment for the header

after - Should the header card be after the current column metadata block (true), or immediately before the TFORM card (false).

Throws:

HeaderCardException - if the header could not be updated

setColumnMeta

public void setColumnMeta(int index,
 IFitsHeader key,
 Number value,
 String comment,
 boolean after)
                   throws HeaderCardException

Specify column metadata for a given column in a way that allows all of the column metadata for a given column to be organized together.

Parameters:

index - The 0-based index of the column

key - The column key. I.e., the keyword will be key+(index+1)

value - The value to be placed in the header.

comment - The comment for the header

after - Should the header card be after the current column metadata block (true), or immediately before the TFORM card (false).

Throws:

HeaderCardException - if the header could not be updated

Since:

1.16

setColumnMeta

public void setColumnMeta(int index,
 String key,
 Boolean value,
 String comment,
 boolean after)
                   throws HeaderCardException

Specify column metadata for a given column in a way that allows all of the column metadata for a given column to be organized together.

Parameters:

index - The 0-based index of the column

key - The column key. I.e., the keyword will be key+(index+1)

value - The value to be placed in the header.

comment - The comment for the header

after - Should the header card be after the current column metadata block (true), or immediately before the TFORM card (false).

Throws:

HeaderCardException - if the header could not be updated

setColumnMeta

public void setColumnMeta(int index,
 String key,
 Number value,
 String comment,
 boolean after)
                   throws HeaderCardException

Specify column metadata for a given column in a way that allows all of the column metadata for a given column to be organized together.

Parameters:

index - The 0-based index of the column

key - The column key. I.e., the keyword will be key+(index+1)

value - The value to be placed in the header.

comment - The comment for the header

after - Should the header card be after the current column metadata block (true), or immediately before the TFORM card (false).

Throws:

HeaderCardException - if the header could not be updated

setColumnMeta

public void setColumnMeta(int index,
 String key,
 Number value,
 int precision,
 String comment,
 boolean after)
                   throws HeaderCardException

Specify column metadata for a given column in a way that allows all of the column metadata for a given column to be organized together.

Parameters:

index - The 0-based index of the column

key - The column key. I.e., the keyword will be key+(index+1)

value - The value to be placed in the header.

precision - The maximum number of decimal places to show after the leading figure. (Trailing zeroes will be ommitted.)

comment - The comment for the header

after - Should the header card be after the current column metadata block (true), or immediately before the TFORM card (false).

Throws:

HeaderCardException - if the header could not be updated

setColumnMeta

public void setColumnMeta(int index,
 String key,
 String value,
 String comment)
                   throws HeaderCardException

Specify column metadata for a given column in a way that allows all of the column metadata for a given column to be organized together.

Parameters:

index - The 0-based index of the column

key - The column key. I.e., the keyword will be key+(index+1)

value - The value to be placed in the header.

comment - The comment for the header

Throws:

HeaderCardException - if the header could not be updated

setColumnMeta

@Deprecated
public void setColumnMeta(int index,
 String key,
 String value,
 String comment,
 boolean after)
                   throws HeaderCardException

Deprecated.

use setColumnMeta(int, IFitsHeader, String, String, boolean)

Specify column metadata for a given column in a way that allows all of the column metadata for a given column to be organized together.

Parameters:

index - The 0-based index of the column

key - The column key. I.e., the keyword will be key+(index+1)

value - The value to be placed in the header.

comment - The comment for the header

after - Should the header card be after the current column metadata block (true), or immediately before the TFORM card (false). @throws FitsException if the operation failed

Throws:

HeaderCardException - if the header could not be updated

setColumnName

public void setColumnName(int index,
 String name,
 String comment)
                   throws IndexOutOfBoundsException,
HeaderCardException

Sets the name / ID of a specific column in this table. Naming columns is generally a good idea so that people can figure out what sort of data actually appears in specific table columns.

Parameters:

index - the column index

name - the name or ID we want to assing to the column

comment - Any additional comment we would like to store alongside in the FITS header. (The comment may be truncated or even ommitted, depending on space constraints in the FITS header.

Throws:

IndexOutOfBoundsException - if the table has no column matching the index

HeaderCardException - if there was a problem wil adding the associated descriptive FITS header keywords to this table's header.

See Also:

• getColumnName(int)
• getDefaultColumnName(int)

setCurrentColumn

public void setCurrentColumn(int col)

Deprecated.

(for internal use) Will be removed int the future (no longer used).

Set the cursor in the header to point after the metadata for the specified column

Parameters:

col - The 0-based index of the column

setCurrentColumn

public void setCurrentColumn(int col,
 boolean after)

Deprecated.

(for internal use) Will have private access in the future.

Set the cursor in the header to point either before the TFORMn value or after the column metadata

Parameters:

col - The 0-based index of the column

after - True if the cursor should be placed after the existing column metadata or false if the cursor is to be placed before the TFORM value. If no corresponding TFORM is found, the cursor will be placed at the end of current header.

setElement

public void setElement(int row,
 int col,
 Object element)
                throws FitsException

Update a single element within the table.

Parameters:

row - the row index

col - the column index

element - the replacement element

Throws:

FitsException - if the operation failed

See Also:

• getElement(int, int)

setRow

public void setRow(int row,
 Object[] newRow)
            throws FitsException

Update a row within a table.

Parameters:

row - row index

newRow - the replacement row

Throws:

FitsException - if the operation failed

See Also:

• getRow(int)