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 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:
    • 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:
    • 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:
  • 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
    • 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