Package smile.data

Interface Tuple

All Superinterfaces:
Serializable
All Known Implementing Classes:
AbstractTuple
public interface Tuple extends Serializable
A tuple is an immutable finite ordered list (sequence) of elements. Allows both generic access by ordinal, which will incur boxing overhead for primitives, as well as native primitive access.

It is invalid to use the native primitive interface to retrieve a value that is null, instead a user must check `isNullAt` before attempting to retrieve a value that might be null.

  • Method Summary

    Modifier and Type
    Method
    Description
    default boolean
    anyNull()
    Returns true if there are any NULL values in this tuple.
    default Object
    apply(int i)
    Returns the value at position i.
    default Object
    apply(String field)
    Returns the value by field name.
    Object
    get(int i)
    Returns the value at position i.
    default Object
    get(String field)
    Returns the value by field name.
    default <T> T[]
    getArray(int i)
    Returns the value at position i of array type.
    default <T> T[]
    getArray(String field)
    Returns the field value of array type.
    default <T> T
    getAs(int i)
    Returns the value at position i.
    default <T> T
    getAs(String field)
    Returns the value of a given fieldName.
    default boolean
    getBoolean(int i)
    Returns the value at position i as a primitive boolean.
    default boolean
    getBoolean(String field)
    Returns the field value as a primitive boolean.
    default byte
    getByte(int i)
    Returns the value at position i as a primitive byte.
    default byte
    getByte(String field)
    Returns the field value as a primitive byte.
    default char
    getChar(int i)
    Returns the value at position i as a primitive byte.
    default char
    getChar(String field)
    Returns the field value as a primitive byte.
    default LocalDate
    getDate(int i)
    Returns the value at position i of date type as java.time.LocalDate.
    default LocalDate
    getDate(String field)
    Returns the field value of date type as java.time.LocalDate.
    default LocalDateTime
    getDateTime(int i)
    Returns the value at position i of date type as java.time.LocalDateTime.
    default LocalDateTime
    getDateTime(String field)
    Returns the field value of date type as java.time.LocalDateTime.
    default BigDecimal
    getDecimal(int i)
    Returns the value at position i of decimal type as java.math.BigDecimal.
    default BigDecimal
    getDecimal(String field)
    Returns the field value of decimal type as java.math.BigDecimal.
    default double
    getDouble(int i)
    Returns the value at position i as a primitive double.
    default double
    getDouble(String field)
    Returns the field value as a primitive double.
    default float
    getFloat(int i)
    Returns the value at position i as a primitive float.
    default float
    getFloat(String field)
    Returns the field value as a primitive float.
    default int
    getInt(int i)
    Returns the value at position i as a primitive int.
    default int
    getInt(String field)
    Returns the field value as a primitive int.
    default long
    getLong(int i)
    Returns the value at position i as a primitive long.
    default long
    getLong(String field)
    Returns the field value as a primitive long.
    default String
    getScale(int i)
    Returns the value at position i of NominalScale or OrdinalScale.
    default String
    getScale(String field)
    Returns the field value of NominalScale or OrdinalScale.
    default short
    getShort(int i)
    Returns the value at position i as a primitive short.
    default short
    getShort(String field)
    Returns the field value as a primitive short.
    default String
    getString(int i)
    Returns the value at position i as a String object.
    default String
    getString(String field)
    Returns the field value as a String object.
    default Tuple
    getStruct(int i)
    Returns the value at position i of struct type.
    default Tuple
    getStruct(String field)
    Returns the field value of struct type.
    default LocalTime
    getTime(int i)
    Returns the value at position i of date type as java.time.LocalTime.
    default LocalTime
    getTime(String field)
    Returns the field value of date type as java.time.LocalTime.
    default boolean
    hasNull()
    Returns true if the tuple has null/missing values.
    default int
    indexOf(String field)
    Returns the index of a given field name.
    default boolean
    isNullAt(int i)
    Checks whether the value at position i is null.
    default boolean
    isNullAt(String field)
    Checks whether the field value is null.
    default int
    length()
    Returns the number of elements in the Tuple.
    default Measure[]
    measures()
    Returns the field's level of measurements.
    default String[]
    names()
    Returns the field names.
    static Tuple
    of(double[] row, StructType schema)
    Returns a double array based tuple.
    static Tuple
    of(int[] row, StructType schema)
    Returns an integer array based tuple.
    static Tuple
    of(Object[] row, StructType schema)
    Returns an object array based tuple.
    static Tuple
    of(ResultSet rs, StructType schema)
    Returns the current row of a JDBC ResultSet as a tuple.
    StructType
    schema()
    Returns the schema of tuple.
    default double[]
    toArray(boolean bias, CategoricalEncoder encoder, String... fields)
    Return an array obtained by converting the fields to numeric mode.
    default double[]
    toArray(String... fields)
    Return an array obtained by converting the fields to numeric mode.
    default String
    toString(int i)
    Returns the string representation of the value at position i.
    default String
    toString(String field)
    Returns the string representation of the field value.
    default DataType[]
    types()
    Returns the field data types.

  • Method Details

    • schema

      StructType schema()
      Returns the schema of tuple.
      Returns:
      the schema of tuple.

    • length

      default int length()
      Returns the number of elements in the Tuple.
      Returns:
      the number of elements in the Tuple.

    • names

      default String[] names()
      Returns the field names.
      Returns:
      the field names.

    • types

      default DataType[] types()
      Returns the field data types.
      Returns:
      the field data types.

    • measures

      default Measure[] measures()
      Returns the field's level of measurements.
      Returns:
      the field's level of measurements.

    • toArray

      default double[] toArray(String... fields)
      Return an array obtained by converting the fields to numeric mode. Missing values/nulls will be encoded as Double.NaN.
      Parameters:
      fields - the fields to export. If empty, all fields will be used.
      Returns:
      the tuple as an array of doubles.

    • toArray

      default double[] toArray(boolean bias, CategoricalEncoder encoder, String... fields)
      Return an array obtained by converting the fields to numeric mode. Missing values/nulls will be encoded as Double.NaN.
      Parameters:
      bias - if true, add the first element of 1.
      encoder - the categorical variable encoder.
      fields - the fields to export. If empty, all fields will be used.
      Returns:
      the tuple as an array of doubles.

    • apply

      default Object apply(int i)
      Returns the value at position i. The value may be null.
      Parameters:
      i - the index of field.
      Returns:
      the field value.

    • apply

      default Object apply(String field)
      Returns the value by field name. The value may be null.
      Parameters:
      field - the name of field.
      Returns:
      the field value.

    • get

      Object get(int i)
      Returns the value at position i. The value may be null.
      Parameters:
      i - the index of field.
      Returns:
      the field value.

    • get

      default Object get(String field)
      Returns the value by field name. The value may be null.
      Parameters:
      field - the name of field.
      Returns:
      the field value.

    • isNullAt

      default boolean isNullAt(int i)
      Checks whether the value at position i is null.
      Parameters:
      i - the index of field.
      Returns:
      true if the field value is null.

    • isNullAt

      default boolean isNullAt(String field)
      Checks whether the field value is null.
      Parameters:
      field - the name of field.
      Returns:
      true if the field value is null.

    • hasNull

      default boolean hasNull()
      Returns true if the tuple has null/missing values.
      Returns:
      true if the tuple has null/missing values.

    • getBoolean

      default boolean getBoolean(int i)
      Returns the value at position i as a primitive boolean.
      Parameters:
      i - the index of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.
      NullPointerException - when value is null.

    • getBoolean

      default boolean getBoolean(String field)
      Returns the field value as a primitive boolean.
      Parameters:
      field - the name of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.
      NullPointerException - when value is null.

    • getChar

      default char getChar(int i)
      Returns the value at position i as a primitive byte.
      Parameters:
      i - the index of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.
      NullPointerException - when value is null.

    • getChar

      default char getChar(String field)
      Returns the field value as a primitive byte.
      Parameters:
      field - the name of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.
      NullPointerException - when value is null.

    • getByte

      default byte getByte(int i)
      Returns the value at position i as a primitive byte.
      Parameters:
      i - the index of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.
      NullPointerException - when value is null.

    • getByte

      default byte getByte(String field)
      Returns the field value as a primitive byte.
      Parameters:
      field - the name of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.
      NullPointerException - when value is null.

    • getShort

      default short getShort(int i)
      Returns the value at position i as a primitive short.
      Parameters:
      i - the index of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.
      NullPointerException - when value is null.

    • getShort

      default short getShort(String field)
      Returns the field value as a primitive short.
      Parameters:
      field - the name of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.
      NullPointerException - when value is null.

    • getInt

      default int getInt(int i)
      Returns the value at position i as a primitive int.
      Parameters:
      i - the index of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.
      NullPointerException - when value is null.

    • getInt

      default int getInt(String field)
      Returns the field value as a primitive int.
      Parameters:
      field - the name of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.
      NullPointerException - when value is null.

    • getLong

      default long getLong(int i)
      Returns the value at position i as a primitive long.
      Parameters:
      i - the index of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.
      NullPointerException - when value is null.

    • getLong

      default long getLong(String field)
      Returns the field value as a primitive long.
      Parameters:
      field - the name of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.
      NullPointerException - when value is null.

    • getFloat

      default float getFloat(int i)
      Returns the value at position i as a primitive float. Throws an exception if the type mismatches or if the value is null.
      Parameters:
      i - the index of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.
      NullPointerException - when value is null.

    • getFloat

      default float getFloat(String field)
      Returns the field value as a primitive float. Throws an exception if the type mismatches or if the value is null.
      Parameters:
      field - the name of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.
      NullPointerException - when value is null.

    • getDouble

      default double getDouble(int i)
      Returns the value at position i as a primitive double.
      Parameters:
      i - the index of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.
      NullPointerException - when value is null.

    • getDouble

      default double getDouble(String field)
      Returns the field value as a primitive double.
      Parameters:
      field - the name of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.
      NullPointerException - when value is null.

    • getString

      default String getString(int i)
      Returns the value at position i as a String object.
      Parameters:
      i - the index of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.

    • getString

      default String getString(String field)
      Returns the field value as a String object.
      Parameters:
      field - the name of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.

    • toString

      default String toString(int i)
      Returns the string representation of the value at position i.
      Parameters:
      i - the index of field.
      Returns:
      the string representation of field value.

    • toString

      default String toString(String field)
      Returns the string representation of the field value.
      Parameters:
      field - the name of field.
      Returns:
      the string representation of field value.

    • getDecimal

      default BigDecimal getDecimal(int i)
      Returns the value at position i of decimal type as java.math.BigDecimal.
      Parameters:
      i - the index of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.

    • getDecimal

      default BigDecimal getDecimal(String field)
      Returns the field value of decimal type as java.math.BigDecimal.
      Parameters:
      field - the name of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.

    • getDate

      default LocalDate getDate(int i)
      Returns the value at position i of date type as java.time.LocalDate.
      Parameters:
      i - the index of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.

    • getDate

      default LocalDate getDate(String field)
      Returns the field value of date type as java.time.LocalDate.
      Parameters:
      field - the name of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.

    • getTime

      default LocalTime getTime(int i)
      Returns the value at position i of date type as java.time.LocalTime.
      Parameters:
      i - the index of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.

    • getTime

      default LocalTime getTime(String field)
      Returns the field value of date type as java.time.LocalTime.
      Parameters:
      field - the name of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.

    • getDateTime

      default LocalDateTime getDateTime(int i)
      Returns the value at position i of date type as java.time.LocalDateTime.
      Parameters:
      i - the index of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.

    • getDateTime

      default LocalDateTime getDateTime(String field)
      Returns the field value of date type as java.time.LocalDateTime.
      Parameters:
      field - the name of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.

    • getScale

      default String getScale(int i)
      Returns the value at position i of NominalScale or OrdinalScale.
      Parameters:
      i - the index of field.
      Returns:
      the field scale.

    • getScale

      default String getScale(String field)
      Returns the field value of NominalScale or OrdinalScale.
      Parameters:
      field - the name of field.
      Returns:
      the field scale.
      Throws:
      ClassCastException - when the data is not nominal or ordinal.

    • getArray

      default <T> T[] getArray(int i)
      Returns the value at position i of array type.
      Type Parameters:
      T - the data type of array elements.
      Parameters:
      i - the index of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.

    • getArray

      default <T> T[] getArray(String field)
      Returns the field value of array type.
      Type Parameters:
      T - the data type of array elements.
      Parameters:
      field - the name of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.

    • getStruct

      default Tuple getStruct(int i)
      Returns the value at position i of struct type.
      Parameters:
      i - the index of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.

    • getStruct

      default Tuple getStruct(String field)
      Returns the field value of struct type.
      Parameters:
      field - the name of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.

    • getAs

      default <T> T getAs(int i)
      Returns the value at position i. For primitive types if value is null it returns 'zero value' specific for primitive ie. 0 for Int - use isNullAt to ensure that value is not null
      Type Parameters:
      T - the data type of field.
      Parameters:
      i - the index of field.
      Returns:
      the field value.
      Throws:
      ClassCastException - when data type does not match.

    • getAs

      default <T> T getAs(String field)
      Returns the value of a given fieldName. For primitive types if value is null it returns 'zero value' specific for primitive i.e. 0 for Int - use isNullAt to ensure that value is not null
      Type Parameters:
      T - the data type of field.
      Parameters:
      field - the name of field.
      Returns:
      the field value.
      Throws:
      UnsupportedOperationException - when schema is not defined.
      IllegalArgumentException - when fieldName do not exist.
      ClassCastException - when data type does not match.

    • indexOf

      default int indexOf(String field)
      Returns the index of a given field name.
      Parameters:
      field - the name of field.
      Returns:
      the field index.
      Throws:
      IllegalArgumentException - when a field `name` does not exist.

    • anyNull

      default boolean anyNull()
      Returns true if there are any NULL values in this tuple.
      Returns:
      true if there are any NULL values in this tuple.

    • of

      static Tuple of(Object[] row, StructType schema)
      Returns an object array based tuple.
      Parameters:
      row - the object array.
      schema - the schema of tuple.
      Returns:
      the tuple.

    • of

      static Tuple of(double[] row, StructType schema)
      Returns a double array based tuple.
      Parameters:
      row - the double array.
      schema - the schema of tuple.
      Returns:
      the tuple.

    • of

      static Tuple of(int[] row, StructType schema)
      Returns an integer array based tuple.
      Parameters:
      row - the int array.
      schema - the schema of tuple.
      Returns:
      the tuple.

    • of

      static Tuple of(ResultSet rs, StructType schema) throws SQLException
      Returns the current row of a JDBC ResultSet as a tuple.
      Parameters:
      rs - the JDBC ResultSet.
      schema - the schema of tuple.
      Returns:
      the tuple.
      Throws:
      SQLException - when JDBC operation fails.