# 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`

public abstract class StarTableJELRowReader extends JELRowReader
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` and `valueObject` 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 of `getTranslatedColumns`. 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

Fields
Modifier and Type
Field
Description
`static final String`
`PARAM_PREFIX`
The string which should be prefixed to a table parameter (constant) name to result in substituting its value.
`static final String`
`UCD_PREFIX`
A string to prefix to a UCD string to indicate the column/parameter with that UCD.
`static final String`
`UTYPE_PREFIX`
A string to prefix to a Utype string to indicate the column/parameter with that Utype.

### Fields inherited from class JELRowReader

`COLUMN_ID_CHAR, NULL_QUERY_PREFIX, OBJECT_PREFIX`

## Constructor Summary

Constructors
Constructor
Description
`StarTableJELRowReader(uk.ac.starlink.table.StarTable table)`
Constructs a new row reader for a given StarTable.

## Method Summary

Modifier and Type
Method
Description
`protected 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 the `PARAM_PREFIX` prefix) or by UCD (using the `UCD_PREFIX` prefix) or by Utype (using the `UTYPE_PREFIX` prefix).
`abstract long`
`getCurrentRow()`
Returns the index of the row on which evaluations are currently taking place.
`uk.ac.starlink.table.DescribedValue`
`getDescribedValueByName(String name)`
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 row
`uk.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`
`requiresRowIndex()`
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`
`valueInt(String colName)`
Returns the value of a named column in this reader's table at the current row as an int.
`long`
`valueLong(String colName)`
Returns the value of a named column in this reader's table at the current row as a long int.
`Object`
`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.
`String`
`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 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`

### Methods inherited from class Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### PARAM_PREFIX

public static final String PARAM_PREFIX
The string which should be prefixed to a table parameter (constant) name to result in substituting its value.

See Also:
  - Constant Field Values

### UCD_PREFIX

public static final String 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:
  - Constant Field Values

### UTYPE_PREFIX

public static final String 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:
  - Constant Field Values

## 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

protected abstract Object getCell(int icol) throws IOException
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 the `getCurrentRow()` 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

public double valueDouble(String colName)
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

public int valueInt(String colName)
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

public long valueLong(String colName)
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

public String valueString(String colName)
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

public Object 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.

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 class `JELRowReader`
Parameters:
  `icol` - column index
Returns:
  true if value at icol is null

### getColumnClass

protected Class<?> getColumnClass(int icol)
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 class `JELRowReader`
Parameters:
  `icol` - non-negative column index
Returns:
  value class, or null for non-existent column

### getColumnIndexByName

protected int getColumnIndexByName(String name)
Description copied from class: `JELRowReader`
Returns the column index of a column in the row given its name. If `name` does not refer to any known column, return -1.

Specified by:
  `getColumnIndexByName` in class `JELRowReader`
Parameters:
  `name` - column name
Returns:
  column index, or -1

### getDescribedValueByName

public uk.ac.starlink.table.DescribedValue getDescribedValueByName(String name)
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

protected Constant<?> getConstantByName(String name)
Understands table parameters identified case-insensitively by name (using the `PARAM_PREFIX` prefix) or by UCD (using the `UCD_PREFIX` prefix) or by Utype (using the `UTYPE_PREFIX` prefix).

Specified by:
  `getConstantByName` in class `JELRowReader`
Parameters:
  `name` - constant name
Returns:
  constant, or null

### getSpecialByName

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 row

Overrides:
  `getSpecialByName` in class `JELRowReader`
Parameters:
  `name` - special name
Returns:
  special, or null

### createDescribedValueConstant

protected Constant<?> createDescribedValueConstant(uk.ac.starlink.table.DescribedValue dval)
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 call `JELRowReader.foundNull()` (and return any value) if the result is null.

Specified by:
  `getBooleanColumnValue` in class `JELRowReader`
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 call `JELRowReader.foundNull()` (and return any value) if the result is null.

Specified by:
  `getByteColumnValue` in class `JELRowReader`
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 call `JELRowReader.foundNull()` (and return any value) if the result is null.

Specified by:
  `getCharColumnValue` in class `JELRowReader`
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 call `JELRowReader.foundNull()` (and return any value) if the result is null.

Specified by:
  `getShortColumnValue` in class `JELRowReader`
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 call `JELRowReader.foundNull()` (and return any value) if the result is null.

Specified by:
  `getIntColumnValue` in class `JELRowReader`
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 call `JELRowReader.foundNull()` (and return any value) if the result is null.

Specified by:
  `getLongColumnValue` in class `JELRowReader`
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 call `JELRowReader.foundNull()` (and return any value) if the result is null.

Specified by:
  `getFloatColumnValue` in class `JELRowReader`
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 call `JELRowReader.foundNull()` (and return any value) if the result is null.

Specified by:
  `getDoubleColumnValue` in class `JELRowReader`
Parameters:
  `icol` - column index
Returns:
  value

### getObjectColumnValue

protected Object getObjectColumnValue(int icol)
Description copied from class: `JELRowReader`
Returns an Object value for a cell of the current row.

Specified by:
  `getObjectColumnValue` in class `JELRowReader`
Parameters:
  `icol` - column index
Returns:
  value

### getUcdRegex

public 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. 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 input `ucd` 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

public 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. Punctuation is mapped to underscores, and the pattern is case-insensitive.

Parameters:
  `utype` - utype specification
Returns:
  regular expression pattern which matches actual Utypes