Package uk.ac.starlink.table
Class Tables
java.lang.Object
uk.ac.starlink.table.Tables
Utility class for miscellaneous table-related functionality.
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final DefaultValueInfo
ValueInfo representing Declination.static final ValueInfo
ValueInfo which may be used as part of a column's metadata to indicate a special value (preferably aNumber
that should be interpreted as a null (blank).static final String
A user-directed XML string documenting the behaviour of theparseCount(java.lang.String)
method.static final ValueInfo
ValueInfo that indicates result of a query.static final DefaultValueInfo
ValueInfo representing Right Ascension.static final ValueInfo
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. -
Method Summary
Modifier and TypeMethodDescriptionstatic 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 anint
value from along
.static int
checksumData
(StarTable table) Returns a checksum of all the cell data in a given table.static long
checksumData
(StarTable table, Checksum checksum) Feeds the data from a row sequence to a supplied checksum accumulator.static void
checkTable
(StarTable table) Diagnostic method which tests the invariants of a StarTable.static String
collapseWhitespace
(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, 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
(Collection<DescribedValue> dvals, String name) Utility method to locate an element in a list of DescribedValue given the name of its ValueInfo member.static String[]
getElementLabels
(int[] shape) Returns an array of strings suitable as labels or label suffixes for elements of an array as returned byValueInfo.getShape()
.static <T> T
getTypedValue
(DescribedValue dval, Class<T> clazz) Utility method to get a typed value from a, possibly null, described value.static String
Deprecated.static Object
getValue
(Collection<DescribedValue> dvals, ValueInfo info) Returns the value from a list ofDescribedValue
objects which corresponds to a given info key.static String
Deprecated.useValueInfo.getXtype()
insteadstatic boolean
Indicates whether a given value is conventionally regarded as a blank value.static long
parseCount
(String countTxt) Interprets a string as a non-negative long integer.static StarTable
randomTable
(StarTable startab) Returns a table based on a given table and guaranteed to have random access.static void
setDescribedValue
(Collection<DescribedValue> dvals, DescribedValue dval) Utility method to update a list of DescribedValues with a new entry.static void
Deprecated.useDefaultValueInfo.setUtype(java.lang.String)
insteadstatic void
Deprecated.useDefaultValueInfo.setXtype(java.lang.String)
insteadstatic TableSequence
singleTableSequence
(StarTable table) Convenience method to construct a TableSequence for a single table.static StarTable
Returns a sorted version of a table.static void
streamStarTable
(StarTable source, TableSink sink) Copies the data and metadata from aStarTable
into a table sink.static StarTable[]
tableArray
(TableSequence tseq) Convenience method to construct an array of StarTables from a TableSequence.static String
tableToString
(StarTable table, String ofmt) Returns the contents of a table as a string.
-
Field Details
-
NULL_VALUE_INFO
ValueInfo which may be used as part of a column's metadata to indicate a special value (preferably aNumber
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 anull
is returned from the table interrogation methods if that is what is meant. -
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 toBoolean.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. -
QUERY_STATUS_INFO
ValueInfo that indicates result of a query. Its name is QUERY_STATUS, and it is used by DALI, but non-DALI/VO sources can use the same mechanism to flag non-standard status. Values are normally "OK", "OVERFLOW" or "ERROR". -
PARSE_COUNT_MAY_BE_GIVEN
A user-directed XML string documenting the behaviour of theparseCount(java.lang.String)
method. This string starts " may be given as " and ends with a full stop.- See Also:
-
RA_INFO
ValueInfo representing Right Ascension. The units are radians and it is non-nullable. -
DEC_INFO
ValueInfo representing Declination. The units are radians and it is non-nullable.
-
-
Method Details
-
randomTable
Returns a table based on a given table and guaranteed to have random access. If the original tablestab
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 withisRandom()==true
- Throws:
IOException
-
getColumnInfos
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
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 columnicol
- the index of the column to be deleted- Throws:
IndexOutOfBoundsException
- ifstartab
has no column aticol
-
streamStarTable
Copies the data and metadata from aStarTable
into a table sink. This method is supplied for convenience; its implementation is very straightforward.- Parameters:
source
- table to be copiedsink
- table destination- Throws:
IOException
-
getDefaultRowSplittable
Returns a RowSplittable object with generic characteristics for a given table. For a random-access table the splitting will be based onRowAccess
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:
IOException
-
checkTable
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:
AssertionError
- if an invariant is violatedIOException
- if there is an I/O error
-
checksumData
Returns a checksum of all the cell data in a given table. Currently, the Adler32 checksum is used.- Parameters:
table
- table to checksum- Returns:
- checksum value
- Throws:
IOException
-
checksumData
Feeds the data from a row sequence to a supplied checksum accumulator.- Parameters:
table
- table containing datachecksum
- checksum accumulator- Returns:
- number of rows checksummed (note this is not the checksum value)
- Throws:
IOException
-
isBlank
Indicates whether a given value is conventionally regarded as a blank value. For most objects this is equivalent to testing whether it is equall tonull
, 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
Collapses whitespace in a string. This normalises the text in the sense of the XML Schema facetwhitespace='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
Convenience method to construct a TableSequence for a single table.- Parameters:
table
- table- Returns:
- table sequence with just one element
-
arrayTableSequence
Convenience method to construct a TableSequence for a supplied array of tables.- Parameters:
tables
- table array- Returns:
- table sequence containing input tables
-
tableArray
Convenience method to construct an array of StarTables from a TableSequence.- Parameters:
tseq
- table sequence- Returns:
- array containing tables from sequence
- Throws:
IOException
-
sortTable
public static StarTable sortTable(StarTable table, int[] colIndices, boolean up, boolean nullsLast) throws IOException Returns a sorted version of a table. The sorting is done on the values of one or more columns, as specified by thecolIndices
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 accesscolIndices
- indices of the columns which are to act as sort keys; first element is primary key etcup
- true for sorting into ascending order, false for descending ordernullsLast
- 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:
IOException
- iftable.isRandom
is not true
-
tableToString
Returns the contents of a table as a string. Only intended for small tables, for instance during debugging.- Parameters:
table
- input tableofmt
- output format specifier, or null for plain text output- Returns:
- stringified table
-
checkedLongToInt
public static int checkedLongToInt(long lval) Convenience method to get anint
value from along
. If the supplied long integerlval
is out of the range which can be represented in anint
, then unlike a typecast, this method will throw anIllegalArgumentException
.- Parameters:
lval
- thelong
value to convert- Returns:
- an
int
value which has the same value aslval
- Throws:
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
Returns an array of strings suitable as labels or label suffixes for elements of an array as returned byValueInfo.getShape()
. If the givenshape
cannot be decomposed into a fixed size array, returnsnull
.- 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.useValueInfo.getUtype()
insteadReturns the Utype associated with a given metadata item.- Parameters:
info
- metadata item- Returns:
- utype string, or null if none is available
- See Also:
-
setUtype
Deprecated.useDefaultValueInfo.setUtype(java.lang.String)
insteadTries to set the Utype for a given metadata item.- Parameters:
info
- metadata itemutype
- new utype value- See Also:
-
getXtype
Deprecated.useValueInfo.getXtype()
insteadReturns the extended type value associated with a given metadata item. The XType corresponds to thextype
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.useDefaultValueInfo.setXtype(java.lang.String)
insteadTries to set the Xtype for a given metadata item.- Parameters:
info
- metadata itemxtype
- new xtype value- See Also:
-
setDescribedValue
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 modifydval
- new entry to add
-
getDescribedValueByName
Utility method to locate an element in a list of DescribedValue given the name of its ValueInfo member.- Parameters:
dvals
- list to queryname
- required value of name- Returns:
- element of
dvals
for whichgetInfo().getName()
matchesname
-
getAuxDatumValue
Utility method to return an auxiliary metadata item from a ValueInfo.- Parameters:
info
- metadata itemauxKey
- info identifying aux metadata entry ininfo
auxClazz
- required result type- Returns:
- typed aux metadata item requested, or null if it doesn't exist or has the wrong type
-
getTypedValue
Utility method to get a typed value from a, possibly null, described value.- Parameters:
dval
- described value, or nullclazz
- required return type- Returns:
- typed value of
dval
, or null if dval is null, or if dval's value has the wrong type
-
getValue
Returns the value from a list ofDescribedValue
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 objectsinfo
- key giving the value you want- Returns:
- matching value
-
fixColumns
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 objectsfixActs
- array of N policies for renaming columns
-
parseCount
Interprets a string as a non-negative long integer. This mostly just parses the supplied string as an integer, but it will also accept embedded underscores (like 1_000_000), suitable exponential notation (like 1e6), and hexadecimal (like 0x400).- Parameters:
countTxt
- textual representation of integer- Returns:
- non-negative integer value
- Throws:
NumberFormatException
- if it can't be interpreted as a non-negative integer- See Also:
-
ValueInfo.getUtype()
instead