uk.ac.starlink.table
Class Tables

java.lang.Object
  extended byuk.ac.starlink.table.Tables

public class Tables
extends 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.
static ValueInfo UTYPE_INFO
          ValueInfo for utype attribute.
 
Constructor Summary
Tables()
           
 
Method Summary
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 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 String getUtype(ValueInfo info)
          Returns the Utype associated with a given metadata item.
static Object getValue(Collection dvals, ValueInfo info)
          Returns the value from a list of DescribedValue objects which corresponds to a given info key.
static boolean isBlank(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, String utype)
          Tries to set the Utype for a given metadata item.
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.
 
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.


UTYPE_INFO

public static final ValueInfo UTYPE_INFO
ValueInfo for utype attribute.


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 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:
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:
IndexOutOfBoundsException - if startab has no column at icol

streamStarTable

public static void streamStarTable(StarTable source,
                                   TableSink sink)
                            throws 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:
IOException

checkTable

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

isBlank

public static boolean isBlank(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

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 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:
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:
IllegalArgumentException - if the conversion cannot be done

getElementLabels

public static 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 String getUtype(ValueInfo info)
Returns the Utype associated with a given metadata item.

Currently, if info is a ColumnInfo then its aux data list will be searched for an item matching UTYPE_INFO (string-valued with name "utype"), while null will be returned for any other ValueInfo instances. In future however the ValueInfo interface may have a utype attribute associated with it, at which point this method will defer to that.

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,
                            String utype)
Tries to set the Utype for a given metadata item. Currently, if info is a ColumnInfo then its aux data list will be augmented with a new item with info UTYPE_INFO (name "utype"), and there will be no effect for any other ValueInfo instances. In future however the ValueInfo interface may have a utype attribute associated with it, at which point this method will defer to that.

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

getValue

public static Object getValue(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.