Package uk.ac.starlink.ttools.jel
Class StarTableJELRowReader
java.lang.Object
gnu.jel.DVMap
uk.ac.starlink.ttools.jel.JELRowReader
uk.ac.starlink.ttools.jel.StarTableJELRowReader
- Direct Known Subclasses:
DummyJELRowReader
,RandomJELRowReader
,SequentialJELRowReader
JELRowReader subclass for access to StarTables.
In addition to the syntax provided by the superclass, the following symbols are understood:
- "$0" or "$index" or (deprecated) "index" (case insensitive):
- the 1-based index of the current row.
- "$ncol"
- Number of columns in the table.
- "$nrow"
- Number of rows in the table. If this is not known, a null value is returned.
- Parameter names:
- The string "param$" followed by the name of a table parameter (case-insensitive) is a constant for the table (as a primitive, if applicable). This can only work if the parameter name is a legal java identifier.
- UCD specifiers:
- The string "ucd$" followed by the text of a UCD giving the required value. Any punctuation (such as ".", ";", "-") in the UCD should be replaced with a "_" (since these symbols cannot appear in identifiers). If the identifier has a trailing "_", then any UCD which starts as specified is considered to match. The first matching column, or if there is none the first matching parameter value is returned. UCD matching is case-insensitive.
- Utype specifiers:
- The string "utype$" followed by the text of a Utype identifying the required value. Any punctuation (such as ".", ":", "-") in the Utype should be replaced with a "_" (since these symbols cannot appear in identifiers). The first matching column, or if there is none the first matching parameter value is returned. UType matching is case-insensitive.
- "$random" (case insensitive) or (deprecated) "RANDOM":
- The special token "$random" evaluates to a double-precision random
number
0<=x<1
which is constant for a given row within this reader. The quality of the random numbers may not be particularly good. - "value*()" functions:
- The methods
valueDouble
,valueInt
,valueLong
,valueString
andvalueObject
are provided. Each takes as an argument an exact column name, and provides the typed value of the column at the current row. These methods are not the generally recommended way to access column values; they are slower and less tidy than simply using column names or $IDs in expressions, and do not admit of static analysis, so their use can not be reflected in the results ofgetTranslatedColumns
. However, it does allow access by column name to columns with names that are not legal java identifiers.
- Since:
- 7 Dec 2007
- Author:
- Mark Taylor
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final String
The string which should be prefixed to a table parameter (constant) name to result in substituting its value.static final String
A string to prefix to a UCD string to indicate the column/parameter with that UCD.static final String
A string to prefix to a Utype string to indicate the column/parameter with that Utype.Fields inherited from class uk.ac.starlink.ttools.jel.JELRowReader
COLUMN_ID_CHAR, NULL_QUERY_PREFIX, OBJECT_PREFIX
-
Constructor Summary
ConstructorsConstructorDescriptionStarTableJELRowReader
(uk.ac.starlink.table.StarTable table) Constructs a new row reader for a given StarTable. -
Method Summary
Modifier and TypeMethodDescriptionprotected Constant
<?> createDescribedValueConstant
(uk.ac.starlink.table.DescribedValue dval) Returns a Constant object based on a DescribedValue.protected boolean
getBooleanColumnValue
(int icol) Returns a boolean value for a cell of the current row.protected byte
getByteColumnValue
(int icol) Returns a byte value for a cell of the current row.protected abstract Object
getCell
(int icol) Returns the value for a given column in this reader's table at the current row.protected char
getCharColumnValue
(int icol) Returns a char value for a cell of the current row.protected Class
<?> getColumnClass
(int icol) Returns the class of values returned by a given column.protected int
getColumnIndexByName
(String name) Returns the column index of a column in the row given its name.protected Constant
<?> getConstantByName
(String name) Understands table parameters identified case-insensitively by name (using thePARAM_PREFIX
prefix) or by UCD (using theUCD_PREFIX
prefix) or by Utype (using theUTYPE_PREFIX
prefix).abstract long
Returns the index of the row on which evaluations are currently taking place.uk.ac.starlink.table.DescribedValue
Returns a table parameter that can be identified by the given designation.protected double
getDoubleColumnValue
(int icol) Returns a double value for a cell of the current row.protected float
getFloatColumnValue
(int icol) Returns a float value for a cell of the current row.protected int
getIntColumnValue
(int icol) Returns a int value for a cell of the current row.protected long
getLongColumnValue
(int icol) Returns a long value for a cell of the current row.protected Object
getObjectColumnValue
(int icol) Returns an Object value for a cell of the current row.protected short
getShortColumnValue
(int icol) Returns a short value for a cell of the current row.protected Constant
<?> getSpecialByName
(String name) Adds to the superclass implementation the following: "$0", "index" or "$index" gives the (1-based) row number "$ncol" gives the number of columns in the table "$nrow" gives the number of rows in the table (null if unknown) "$random" or "RANDOM" returns a double random number, always the same for a given rowuk.ac.starlink.table.StarTable
getTable()
Returns the table associated with this reader.static Pattern
getUcdRegex
(String ucd) Takes a (non-prefixed) UCD specification and returns a Pattern actual UCDs should match if they represent the same thing.static Pattern
getUtypeRegex
(String utype) Takes a (non-prefixed) Utype specification and returns a Pattern actual Utypes should match if they represent the same thing.protected boolean
isBlank
(int icol) Indicates whether the value in a given column is null.boolean
Indicates whether this RowReader has been asked to reference any constants for which the row index is required.double
valueDouble
(String colName) Returns the value of a named column in this reader's table at the current row as a double.int
Returns the value of a named column in this reader's table at the current row as an int.long
Returns the value of a named column in this reader's table at the current row as a long int.valueObject
(String colName) Returns the value of a named column in this reader's table at the current row as an Object; This is not generally the recommended way to access column values, but it will work for column names without any syntactical restrictions.valueString
(String colName) Returns the value of a named column in this reader's table at the current row as a String.Methods inherited from class uk.ac.starlink.ttools.jel.JELRowReader
evaluate, evaluateBoolean, evaluateDouble, foundNull, getBooleanArrayProperty, getBooleanProperty, getBooleanProperty, getBooleanValue, getByteArrayProperty, getByteProperty, getByteValue, getCharArrayProperty, getCharProperty, getCharValue, getColumnIndex, getDateArrayProperty, getDoubleArrayProperty, getDoubleProperty, getDoubleValue, getFloatArrayProperty, getFloatProperty, getFloatValue, getIntArrayProperty, getIntProperty, getIntValue, getLongArrayProperty, getLongProperty, getLongValue, getNumberProperty, getObjectArrayProperty, getObjectProperty, getShortArrayProperty, getShortProperty, getShortValue, getStringArrayProperty, getStringProperty, getTranslatedColumns, getTranslatedConstants, getTypeName, setFailOnNull, stripPrefix, translate
-
Field Details
-
PARAM_PREFIX
The string which should be prefixed to a table parameter (constant) name to result in substituting its value.- See Also:
-
UCD_PREFIX
A string to prefix to a UCD string to indicate the column/parameter with that UCD. The first matching column, else the first matching parameter, is used. Punctuation in the UCD name is all mapped to "_". A trailing "_" corresponds to a wildcard.- See Also:
-
UTYPE_PREFIX
A string to prefix to a Utype string to indicate the column/parameter with that Utype. The first matching column, else the first matching parameter, is used. Punctuation in the Utype name is all mapped to "_".- See Also:
-
-
Constructor Details
-
StarTableJELRowReader
public StarTableJELRowReader(uk.ac.starlink.table.StarTable table) Constructs a new row reader for a given StarTable. Note that this reader cannot become aware of changes to the columns of the table; in the event of such changes this object should be dicarded and and a new one used for any new expressions.- Parameters:
table
- the StarTable this reader will read from
-
-
Method Details
-
getTable
public uk.ac.starlink.table.StarTable getTable()Returns the table associated with this reader.- Returns:
- table
-
getCell
Returns the value for a given column in this reader's table at the current row.- Parameters:
icol
- column index- Returns:
- contents of column icol at the current row
- Throws:
IOException
-
getCurrentRow
public abstract long getCurrentRow()Returns the index of the row on which evaluations are currently taking place.- Returns:
- row index (first row is 0)
-
requiresRowIndex
public boolean requiresRowIndex()Indicates whether this RowReader has been asked to reference any constants for which the row index is required. In practice this means it will return true if any of the JEL expressions which this RowReader has been asked to compile may need to call thegetCurrentRow()
method. Since not all row reader implementations are able to return a value for that method, this is useful information.- Returns:
- true if the current row index may be required during evaluation
-
valueDouble
Returns the value of a named column in this reader's table at the current row as a double. This is not generally the recommended way to access column values, but it will work for column names without any syntactical restrictions.- Parameters:
colName
- column name, matched exactly- Returns:
- value of named column as a double, or NaN on failure (no such column or value not numeric)
-
valueInt
Returns the value of a named column in this reader's table at the current row as an int. This is not generally the recommended way to access column values, but it will work for column names without any syntactical restrictions.- Parameters:
colName
- column name, matched exactly- Returns:
- value of column as an int; foundNull is called on failure (no such column or value not numeric or not finite)
-
valueLong
Returns the value of a named column in this reader's table at the current row as a long int. This is not generally the recommended way to access column values, but it will work for column names without any syntactical restrictions.- Parameters:
colName
- column name, matched exactly- Returns:
- value of column as a long; foundNull is called on failure (no such column or value not numeric or not finite)
-
valueString
Returns the value of a named column in this reader's table at the current row as a String. This is not generally the recommended way to access column values, but it will work for column names without any syntactical restrictions.- Parameters:
colName
- column name, matched exactly- Returns:
- value of column as a String, or null if no such column
-
valueObject
Returns the value of a named column in this reader's table at the current row as an Object; This is not generally the recommended way to access column values, but it will work for column names without any syntactical restrictions.- Parameters:
colName
- column name, matched exactly- Returns:
- value of column as an Object, or null if no such column
-
isBlank
protected boolean isBlank(int icol) Description copied from class:JELRowReader
Indicates whether the value in a given column is null.- Specified by:
isBlank
in classJELRowReader
- Parameters:
icol
- column index- Returns:
- true if value at icol is null
-
getColumnClass
Description copied from class:JELRowReader
Returns the class of values returned by a given column. If no column with the given index exists, null should be returned.- Specified by:
getColumnClass
in classJELRowReader
- Parameters:
icol
- non-negative column index- Returns:
- value class, or null for non-existent column
-
getColumnIndexByName
Description copied from class:JELRowReader
Returns the column index of a column in the row given its name. Ifname
does not refer to any known column, return -1.- Specified by:
getColumnIndexByName
in classJELRowReader
- Parameters:
name
- column name- Returns:
- column index, or -1
-
getDescribedValueByName
Returns a table parameter that can be identified by the given designation. This will typically have a prefix such as "param$", "ucd$" etc. Called during expression evaluation, may be overridden.- Parameters:
name
- designation in JEL expression- Returns:
- fixed value for
name
, or null
-
getConstantByName
Understands table parameters identified case-insensitively by name (using thePARAM_PREFIX
prefix) or by UCD (using theUCD_PREFIX
prefix) or by Utype (using theUTYPE_PREFIX
prefix).- Specified by:
getConstantByName
in classJELRowReader
- Parameters:
name
- constant name- Returns:
- constant, or null
-
getSpecialByName
Adds to the superclass implementation the following:- "$0", "index" or "$index" gives the (1-based) row number
- "$ncol" gives the number of columns in the table
- "$nrow" gives the number of rows in the table (null if unknown)
- "$random" or "RANDOM" returns a double random number, always the same for a given row
- Overrides:
getSpecialByName
in classJELRowReader
- Parameters:
name
- special name- Returns:
- special, or null
-
createDescribedValueConstant
Returns a Constant object based on a DescribedValue. The supplied implementation evaluates the constant's class and value once when this method is called.- Parameters:
dval
- described value object- Returns:
- constant which evaluates to dval's value
-
getBooleanColumnValue
protected boolean getBooleanColumnValue(int icol) Description copied from class:JELRowReader
Returns a boolean value for a cell of the current row. Will only be called if the relevant column is declared boolean. Must callJELRowReader.foundNull()
(and return any value) if the result is null.- Specified by:
getBooleanColumnValue
in classJELRowReader
- Parameters:
icol
- column index- Returns:
- value
-
getByteColumnValue
protected byte getByteColumnValue(int icol) Description copied from class:JELRowReader
Returns a byte value for a cell of the current row. Will only be called if the relevant column is declared byte. Must callJELRowReader.foundNull()
(and return any value) if the result is null.- Specified by:
getByteColumnValue
in classJELRowReader
- Parameters:
icol
- column index- Returns:
- value
-
getCharColumnValue
protected char getCharColumnValue(int icol) Description copied from class:JELRowReader
Returns a char value for a cell of the current row. Will only be called if the relevant column is declared char. Must callJELRowReader.foundNull()
(and return any value) if the result is null.- Specified by:
getCharColumnValue
in classJELRowReader
- Parameters:
icol
- column index- Returns:
- value
-
getShortColumnValue
protected short getShortColumnValue(int icol) Description copied from class:JELRowReader
Returns a short value for a cell of the current row. Will only be called if the relevant column is declared short. Must callJELRowReader.foundNull()
(and return any value) if the result is null.- Specified by:
getShortColumnValue
in classJELRowReader
- Parameters:
icol
- column index- Returns:
- value
-
getIntColumnValue
protected int getIntColumnValue(int icol) Description copied from class:JELRowReader
Returns a int value for a cell of the current row. Will only be called if the relevant column is declared int. Must callJELRowReader.foundNull()
(and return any value) if the result is null.- Specified by:
getIntColumnValue
in classJELRowReader
- Parameters:
icol
- column index- Returns:
- value
-
getLongColumnValue
protected long getLongColumnValue(int icol) Description copied from class:JELRowReader
Returns a long value for a cell of the current row. Will only be called if the relevant column is declared long. Must callJELRowReader.foundNull()
(and return any value) if the result is null.- Specified by:
getLongColumnValue
in classJELRowReader
- Parameters:
icol
- column index- Returns:
- value
-
getFloatColumnValue
protected float getFloatColumnValue(int icol) Description copied from class:JELRowReader
Returns a float value for a cell of the current row. Will only be called if the relevant column is declared float. Must callJELRowReader.foundNull()
(and return any value) if the result is null.- Specified by:
getFloatColumnValue
in classJELRowReader
- Parameters:
icol
- column index- Returns:
- value
-
getDoubleColumnValue
protected double getDoubleColumnValue(int icol) Description copied from class:JELRowReader
Returns a double value for a cell of the current row. Will only be called if the relevant column is declared double. Must callJELRowReader.foundNull()
(and return any value) if the result is null.- Specified by:
getDoubleColumnValue
in classJELRowReader
- Parameters:
icol
- column index- Returns:
- value
-
getObjectColumnValue
Description copied from class:JELRowReader
Returns an Object value for a cell of the current row.- Specified by:
getObjectColumnValue
in classJELRowReader
- Parameters:
icol
- column index- Returns:
- value
-
getUcdRegex
Takes a (non-prefixed) UCD specification and returns a Pattern actual UCDs should match if they represent the same thing. Punctuation is mapped to underscores, and the pattern is case-insensitive, which means that the same syntax can work for UCD1s and UCD1+s. If a trailing underscore (or other punctuation mark) is present in the inputucd
it is considered as a trailing match-all wildcard.- Parameters:
ucd
- UCD1 or UCD1+ specification/pattern- Returns:
- regular expression pattern which matches actual UCD1s or UCD1+s
-
getUtypeRegex
Takes a (non-prefixed) Utype specification and returns a Pattern actual Utypes should match if they represent the same thing. Punctuation is mapped to underscores, and the pattern is case-insensitive.- Parameters:
utype
- utype specification- Returns:
- regular expression pattern which matches actual Utypes
-