Class AsciiTable
- All Implemented Interfaces:
FitsElement
,TableData
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:
-
Field Summary
Fields inherited from class nom.tam.fits.Data
dataSize, fileOffset, input
-
Constructor Summary
ConstructorsConstructorDescriptionCreate an empty ASCII tableAsciiTable
(Header hdr) Deprecated.(for internal use) Visibility may be reduced to the package level in the future.AsciiTable
(Header hdr, boolean preferInt) Deprecated.UsesetI10PreferInt(boolean)
instead prior to reading ASCII tables. -
Method Summary
Modifier and TypeMethodDescriptionint
Add a column to the table, without updating the header of an encompassing HDU.int
Adds an ASCII table column with the specified ASCII text width for storing its elements.int
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.protected void
fillHeader
(Header h) Describe the structure of this data object in the supplied header.static AsciiTable
fromColumnMajor
(Object[] columns) Creates an ASCII table from existing data in column-major format order.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 asint.class
orString.class
.protected Object[]
Returns the data content that is currently in memory.Object[]
getData()
Returns the underlying Java representation of the data contained in this HDU's data segment.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
Get the number of bytes in a rowprotected long
Returns the calculated byte size of the data, regardless of whether the data is currently in memory or not.static boolean
Checks if I10 columns should be treated as containing 32-bitint
values, rather than 64-bitlong
values, when possible.boolean
isNull
(int row, int col) Checks if an element isnull
.protected void
Load data from the current position of the input into memory.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
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
Sets new data for a table row.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, ensureData, getFileOffset, getKernel, getRandomAccessInput, getSize, isDeferred, isEmpty, reset, rewrite, rewriteable, setFileOffset
Methods inherited from class java.lang.Object
clone, equals, finalize, 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
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 formatI10
, thesetI10PreferInt(boolean)
mayb be used to control whether to treat them asint
or aslong
values (the latter is the default).- Parameters:
hdr
- The header describing the table- Throws:
FitsException
- if the operation failed
-
AsciiTable
Deprecated.UsesetI10PreferInt(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 ittrue
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 tablepreferInt
- iftrue
, format "I10" columns will be assumedint.class
, provided TLMINn/TLMAXn or TDMINn/TDMAXn limits (if defined) allow it. iffalse
, I10 columns that have no clear indication of data range will be assumedlong.class
.- Throws:
FitsException
- if the operation failed
-
-
Method Details
-
fromColumnMajor
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 ofint[]
,long[]
,float[]
,double[]
, or elseString[]
, 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
Return the data type in the specified column, such asint.class
orString.class
.- Parameters:
col
- The 0-based column index- Returns:
- the class of data in the specified column.
- Since:
- 1.16
-
addColumn
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 useTableHDU.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 anObject[]
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 failedIllegalArgumentException
- See Also:
-
addColumn
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 elseString[]
. 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 textwidth
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
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
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 removelen
- the number of subsequent columns to remove- Throws:
FitsException
- if the table could not be modified- See Also:
-
deleteRows
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 removelen
- the number of subsequent rows to remove- Throws:
FitsException
- if the table could not be modified- See Also:
-
loadData
Description copied from class:Data
Load data from the current position of the input into memory. This may be triggered immediately when calling
Data.read(ArrayDataInput)
if called on a non random accessible input, or else later when data is accessed viaData.ensureData()
, for example as a result of aData.getData()
call. This method will not be called unless there is actual data of non-zero size to be read.Implementations should create appropriate data structures and populate them from the specified input.
- Specified by:
loadData
in classData
- Parameters:
in
- The input from which to load data- Throws:
IOException
- if the data could not be loaded from the input.FitsException
- if the data is garbled.- See Also:
-
read
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 aFitsFile
, 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 interfaceFitsElement
- Overrides:
read
in classData
- 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:
-
fillHeader
Description copied from class:Data
Describe the structure of this data object in the supplied header.- Specified by:
fillHeader
in classData
- Parameters:
h
- header to fill with the data from the current data object
-
getColumn
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:
-
getCurrentData
Description copied from class:Data
Returns the data content that is currently in memory. In case of a data object in deferred read state (that is its prescription has been parsed from the header, but no data content was loaded yet from a random accessible input), this call may returnnull
or an object representing empty data.- Specified by:
getCurrentData
in classData
- Returns:
- The current data content in memory.
- See Also:
-
getData
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 classData
- 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
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 adouble[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[]
orshort[]
, depending on theFitsFactory.setUseUnicodeChars(boolean)
setting, not unicode Javachar[]
. Therefore, this call will returnbyte[]
orshort[]
, 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 fromA
toB
orI
. - Complex values in FITS are stored as
float[2]
ordouble[2]
, not as aComplexValue
type. Therefore, this call will returnfloat[]
ordouble[]
, 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 fromC
toF
, or fromM
toD
,.
- Parameters:
row
- the 0-based row index of the elementcol
- 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:
- Character arrays in FITS are stored as
-
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
Description copied from interface:TableData
Returns an array of elements in a particualr table row. SeeTableData.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
. SeeTableData.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.
-
getTrueSize
protected long getTrueSize()Description copied from class:Data
Returns the calculated byte size of the data, regardless of whether the data is currently in memory or not.- Specified by:
getTrueSize
in classData
- Returns:
- the calculated byte size for the data.
-
isNull
public boolean isNull(int row, int col) Checks if an element isnull
.- Parameters:
row
- The 0-based rowcol
- The 0-based column- Returns:
- if the given element has been nulled.
-
setColumn
Description copied from interface:TableData
Sets new data for a table column. SeeTableData.addColumn(Object)
for more information on the column data format.- Parameters:
col
- the 0-based column indexnewData
- an object containing the new column data (for all rows) of the specified column. SeeTableData.getColumn(int)
for more information on the column data format.- Throws:
FitsException
- if the table could not be modified- See Also:
-
setElement
Description copied from interface:TableData
Sets new data element in this table. SeeTableData.getElement(int, int)
for more information about the format of elements.- Parameters:
row
- the 0-based row index of the elementcol
- the 0-based column index of the elementnewData
- 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
Description copied from interface:TableData
Sets new data for a table row. SeeTableData.getElement(int, int)
for more information about the format of elements.- Parameters:
row
- the 0-based row indexnewData
- an object containing the row data (for all column) of the specified row. SeeTableData.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
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 callsTableData.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 toTableData.deleteColumns(int, int)
.hdr
- The table header- Throws:
FitsException
- if the header could not be updated
-
write
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 interfaceFitsElement
- Specified by:
write
in classData
- Parameters:
str
- The data sink.- Throws:
FitsException
- if the write was unsuccessful.
-
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. -
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 ittrue
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 assumetrue
, and thus to treat I10 columns asint
values.- Parameters:
value
- iftrue
, format "I10" columns will be assumedint.class
, provided TLMINn/TLMAXn or TDMINn/TDMAXn limits (if defined) allow it. iffalse
, I10 columns that have no clear indication of data range will be assumedlong.class
.- Since:
- 1.19
- See Also:
-
isI10PreferInt
public static boolean isI10PreferInt()Checks if I10 columns should be treated as containing 32-bitint
values, rather than 64-bitlong
values, when possible.- Returns:
true
if I10 columns should be treated as containing 32-bitint
values, otherwisefalse
.- Since:
- 1.19
- See Also:
-