public class Tables
extends java.lang.Object
Modifier and Type | Field and Description |
---|---|
static DefaultValueInfo |
DEC_INFO
ValueInfo representing Declination.
|
static ValueInfo |
NULL_VALUE_INFO
ValueInfo which may be used as part of a column's metadata to indicate
a special value (preferably a
Number
that should be interpreted as a null (blank). |
static DefaultValueInfo |
RA_INFO
ValueInfo representing Right Ascension.
|
static ValueInfo |
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.
|
Constructor and Description |
---|
Tables() |
Modifier and Type | Method and Description |
---|---|
static 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 an int value from a long.
|
static long |
checksumData(RowSequence rseq,
java.util.zip.Checksum checksum)
Feeds the data from a row sequence to a supplied checksum accumulator.
|
static int |
checksumData(StarTable table)
Returns a checksum of all the cell data in a given table.
|
static void |
checkTable(StarTable table)
Diagnostic method which tests the invariants of a StarTable.
|
static java.lang.String |
collapseWhitespace(java.lang.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,
java.lang.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(java.util.Collection<DescribedValue> dvals,
java.lang.String name)
Utility method to locate an element in a list of DescribedValue
given the name of its ValueInfo member.
|
static java.lang.String[] |
getElementLabels(int[] shape)
Returns an array of strings suitable as labels or label suffixes
for elements of an array as returned by
ValueInfo.getShape() . |
static <T> T |
getTypedValue(DescribedValue dval,
java.lang.Class<T> clazz)
Utility method to get a typed value from a, possibly null,
described value.
|
static java.lang.String |
getUtype(ValueInfo info)
Deprecated.
use
ValueInfo.getUtype() instead |
static java.lang.Object |
getValue(java.util.Collection<DescribedValue> dvals,
ValueInfo info)
Returns the value from a list of
DescribedValue objects
which corresponds to a given info key. |
static java.lang.String |
getXtype(ValueInfo info)
Deprecated.
use
ValueInfo.getXtype() instead |
static boolean |
isBlank(java.lang.Object value)
Indicates whether a given value is conventionally regarded as a
blank value.
|
static StarTable |
randomTable(StarTable startab)
Returns a table based on a given table and guaranteed to have
random access.
|
static void |
setDescribedValue(java.util.Collection<DescribedValue> dvals,
DescribedValue dval)
Utility method to update a list of DescribedValues with a new entry.
|
static void |
setUtype(ValueInfo info,
java.lang.String utype)
Deprecated.
use
DefaultValueInfo.setUtype(java.lang.String) instead |
static void |
setXtype(ValueInfo info,
java.lang.String xtype)
Deprecated.
use
DefaultValueInfo.setXtype(java.lang.String) instead |
static TableSequence |
singleTableSequence(StarTable table)
Convenience method to construct a TableSequence for a single table.
|
static StarTable |
sortTable(StarTable table,
int[] colIndices,
boolean up,
boolean nullsLast)
Returns a sorted version of a table.
|
static void |
streamStarTable(StarTable source,
TableSink sink)
Copies the data and metadata from a StarTable into a
table sink.
|
static StarTable[] |
tableArray(TableSequence tseq)
Convenience method to construct an array of StarTables from a
TableSequence.
|
static java.lang.String |
tableToString(StarTable table,
java.lang.String ofmt)
Returns the contents of a table as a string.
|
public static final ValueInfo NULL_VALUE_INFO
Number
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 a null is returned from the table interrogation methods
if that is what is meant.public static final ValueInfo UBYTE_FLAG_INFO
Boolean.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.public static final DefaultValueInfo RA_INFO
public static final DefaultValueInfo DEC_INFO
public static StarTable randomTable(StarTable startab) throws java.io.IOException
This convenience method is equivalent to calling StoragePolicy.getDefaultPolicy().randomTable(startab).
startab
- original tablejava.io.IOException
public static ColumnInfo[] getColumnInfos(StarTable startab)
startab
- the table being enquired aboutpublic static StarTable deleteColumn(StarTable startab, int icol)
startab
- the table from which to delete a columnicol
- the index of the column to be deletedjava.lang.IndexOutOfBoundsException
- if startab has no column
at icolpublic static void streamStarTable(StarTable source, TableSink sink) throws java.io.IOException
source
- table to be copiedsink
- table destinationjava.io.IOException
public static RowSplittable getDefaultRowSplittable(StarTable table) throws java.io.IOException
RowAccess
objects, and for a non-random table
it will not be capable of splits.table
- tablejava.io.IOException
public static void checkTable(StarTable table) throws java.io.IOException
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.
table
- table to testjava.lang.AssertionError
- if an invariant is violatedjava.io.IOException
- if there is an I/O errorpublic static int checksumData(StarTable table) throws java.io.IOException
table
- table to checksumjava.io.IOException
public static long checksumData(RowSequence rseq, java.util.zip.Checksum checksum) throws java.io.IOException
rseq
- row sequence containing datachecksum
- checksum accumulatorjava.io.IOException
public static boolean isBlank(java.lang.Object value)
value
- value to testpublic static java.lang.String collapseWhitespace(java.lang.String txt)
whitespace='collapse'
:
leading and trailing whitespace is removed,
and any other run of whitespace is replaced by a single space character.txt
- input string (may be null)public static TableSequence singleTableSequence(StarTable table)
table
- tablepublic static TableSequence arrayTableSequence(StarTable[] tables)
tables
- table arraypublic static StarTable[] tableArray(TableSequence tseq) throws java.io.IOException
tseq
- table sequencejava.io.IOException
public static StarTable sortTable(StarTable table, int[] colIndices, boolean up, boolean nullsLast) throws java.io.IOException
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 firstjava.io.IOException
- if table.isRandom is not truepublic static java.lang.String tableToString(StarTable table, java.lang.String ofmt)
table
- input tableofmt
- output format specifier, or null for plain text outputpublic static int checkedLongToInt(long lval)
lval
- the long value to convertjava.lang.IllegalArgumentException
- if the conversion cannot be donepublic static int assertLongToInt(long lval)
lval
- long value, asserted to be in the range
Integer.MIN_VALUE..Integer.MAX_VALUElval
public static java.lang.String[] getElementLabels(int[] shape)
ValueInfo.getShape()
.
If the given shape cannot be decomposed into a fixed
size array, returns null.shape
- vector giving dimensions of an array value@Deprecated public static java.lang.String getUtype(ValueInfo info)
ValueInfo.getUtype()
insteadinfo
- metadata itemsetUtype(uk.ac.starlink.table.ValueInfo, java.lang.String)
@Deprecated public static void setUtype(ValueInfo info, java.lang.String utype)
DefaultValueInfo.setUtype(java.lang.String)
insteadinfo
- metadata itemutype
- new utype valuegetUtype(uk.ac.starlink.table.ValueInfo)
@Deprecated public static java.lang.String getXtype(ValueInfo info)
ValueInfo.getXtype()
insteadxtype
attribute of
the VOTable format. Other table formats may or may not be able
to represent it.info
- metadata item@Deprecated public static void setXtype(ValueInfo info, java.lang.String xtype)
DefaultValueInfo.setXtype(java.lang.String)
insteadinfo
- metadata itemxtype
- new xtype valuegetXtype(uk.ac.starlink.table.ValueInfo)
public static void setDescribedValue(java.util.Collection<DescribedValue> dvals, DescribedValue dval)
dvals
- list to modifydval
- new entry to addpublic static DescribedValue getDescribedValueByName(java.util.Collection<DescribedValue> dvals, java.lang.String name)
dvals
- list to queryname
- required value of namedvals
for which
getInfo().getName()
matches name
public static <T> T getAuxDatumValue(ValueInfo info, ValueInfo auxKey, java.lang.Class<T> auxClazz)
info
- metadata itemauxKey
- info identifying aux metadata entry in info
auxClazz
- required result typepublic static <T> T getTypedValue(DescribedValue dval, java.lang.Class<T> clazz)
dval
- described value, or nullclazz
- required return typedval
, or null if dval is null,
or if dval's value has the wrong typepublic static java.lang.Object getValue(java.util.Collection<DescribedValue> dvals, ValueInfo info)
DescribedValue
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.dvals
- list of DescribedValue objectsinfo
- key giving the value you wantpublic static void fixColumns(ColumnInfo[][] infoLists, JoinFixAction[] fixActs)
infoLists
- array of N arrays of column metadata objectsfixActs
- array of N policies for renaming columns