uk.ac.starlink.table
Class Tables

java.lang.Object
  extended by uk.ac.starlink.table.Tables

public class Tables
extends java.lang.Object

Utility class for miscellaneous table-related functionality.


Field Summary
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.
 
Constructor Summary
Tables()
           
 
Method Summary
static TableSequence arrayTableSequence(StarTable[] tables)
          Convenience method to construct a TableSequence for a supplied array of tables.
static int checkedLongToInt(long lval)
          Convenience method to get an int value from a long.
static void checkTable(StarTable table)
          Diagnostic method which tests the invariants of a StarTable.
static StarTable deleteColumn(StarTable startab, int icol)
          Returns a table equivalent to the original but with a given column deleted.
static ColumnInfo[] getColumnInfos(StarTable startab)
          Convenience method to return an array of all the column headers in a given table.
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 java.lang.String getUtype(ValueInfo info)
          Deprecated. use ValueInfo.getUtype() instead
static java.lang.Object getValue(java.util.Collection dvals, ValueInfo info)
          Returns the value from a list of DescribedValue objects which corresponds to a given info key.
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 setUtype(ValueInfo info, java.lang.String utype)
          Deprecated. use DefaultValueInfo.setUtype(java.lang.String) instead
static TableSequence singleTableSequence(StarTable table)
          Convenience method to consruct 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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NULL_VALUE_INFO

public static final 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). 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.


RA_INFO

public static final DefaultValueInfo RA_INFO
ValueInfo representing Right Ascension. The units are radians and it is non-nullable.


DEC_INFO

public static final DefaultValueInfo DEC_INFO
ValueInfo representing Declination. The units are radians and it is non-nullable.

Constructor Detail

Tables

public Tables()
Method Detail

randomTable

public static StarTable randomTable(StarTable startab)
                             throws java.io.IOException
Returns a table based on a given table and guaranteed to have random access. If the original table stab 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 with isRandom()==true
Throws:
java.io.IOException

getColumnInfos

public static ColumnInfo[] getColumnInfos(StarTable startab)
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

public static StarTable deleteColumn(StarTable startab,
                                     int icol)
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 column
icol - the index of the column to be deleted
Throws:
java.lang.IndexOutOfBoundsException - if startab has no column at icol

streamStarTable

public static void streamStarTable(StarTable source,
                                   TableSink sink)
                            throws java.io.IOException
Copies the data and metadata from a StarTable into a table sink. This method is supplied for convenience; its implementation is very straightforward.

Parameters:
source - table to be copied
sink - table destination
Throws:
java.io.IOException

checkTable

public static void checkTable(StarTable table)
                       throws java.io.IOException
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:
java.lang.AssertionError - if an invariant is violated
java.io.IOException - if there is an I/O error

isBlank

public static boolean isBlank(java.lang.Object value)
Indicates whether a given value is conventionally regarded as a blank value. For most objects this is equivalent to testing whether it is equall to null, 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

singleTableSequence

public static TableSequence singleTableSequence(StarTable table)
Convenience method to consruct a TableSequence for a single table.

Parameters:
table - table
Returns:
table sequence with just one element

arrayTableSequence

public static TableSequence arrayTableSequence(StarTable[] tables)
Convenience method to construct a TableSequence for a supplied array of tables.

Parameters:
tables - table array
Returns:
table sequence containing input tables

tableArray

public static StarTable[] tableArray(TableSequence tseq)
                              throws java.io.IOException
Convenience method to construct an array of StarTables from a TableSequence.

Parameters:
tseq - table sequence
Returns:
array containing tables from sequence
Throws:
java.io.IOException

sortTable

public static StarTable sortTable(StarTable table,
                                  int[] colIndices,
                                  boolean up,
                                  boolean nullsLast)
                           throws java.io.IOException
Returns a sorted version of a table. The sorting is done on the values of one or more columns, as specified by the colIndices 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 access
colIndices - indices of the columns which are to act as sort keys; first element is primary key etc
up - true for sorting into ascending order, false for descending order
nullsLast - 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:
java.io.IOException - if table.isRandom is not true

checkedLongToInt

public static int checkedLongToInt(long lval)
Convenience method to get an int value from a long. If the supplied long integer lval is out of the range which can be represented in an int, then unlike a typecast, this method will throw an IllegalArgumentException.

Parameters:
lval - the long value to convert
Returns:
an int value which has the same value as lval
Throws:
java.lang.IllegalArgumentException - if the conversion cannot be done

getElementLabels

public 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(). If the given shape cannot be decomposed into a fixed size array, returns null.

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

public static java.lang.String getUtype(ValueInfo info)
Deprecated. use ValueInfo.getUtype() instead

Returns the Utype associated with a given metadata item.

Parameters:
info - metadata item
Returns:
utype string, or null if none is available
See Also:
setUtype(uk.ac.starlink.table.ValueInfo, java.lang.String)

setUtype

public static void setUtype(ValueInfo info,
                            java.lang.String utype)
Deprecated. use DefaultValueInfo.setUtype(java.lang.String) instead

Tries to set the Utype for a given metadata item.

Parameters:
info - metadata item
utype - new utype value
See Also:
getUtype(uk.ac.starlink.table.ValueInfo)

getValue

public static java.lang.Object getValue(java.util.Collection dvals,
                                        ValueInfo info)
Returns the value from a list of 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.

Parameters:
dvals - list of DescribedValue objects
info - key giving the value you want
Returns:
matching value

Copyright © 2004 CLRC: Central Laboratory of the Research Councils. All rights reserved.