Package io.cucumber.datatable

Class DataTable

java.lang.Object
io.cucumber.datatable.DataTable
@API(status=STABLE) public final class DataTable extends Object
A m-by-n table of string values. For example: 
 |     | firstName   | lastName | birthDate  |
 | 4a1 | Annie M. G. | Schmidt  | 1911-03-20 |
 | c92 | Roald       | Dahl     | 1916-09-13 |

A table is either empty or contains one or more values. As such if a table has zero height it must have zero width and vice versa.

The first row of the the table may be referred to as the table header. The remaining cells as the table body.

A table can be converted into an object of an arbitrary type by a DataTable.TableConverter. A table created without a table converter will throw a DataTable.NoConverterDefined exception when doing so.

Several methods are provided to convert tables to common data structures such as lists, maps, ect. These methods have the form asX and will use the provided data table converter. A DataTable is immutable and thread safe.

  • Method Details

    • create

      public static DataTable create(List<List<String>> raw)
      Creates a new DataTable.

      Parameters:
      raw - the underlying table
      Returns:
      a new data table containing the raw values
      Throws:
      NullPointerException - if raw is null
      IllegalArgumentException - when the table is not rectangular or contains null values.

    • create

      public static DataTable create(List<List<String>> raw, DataTable.TableConverter tableConverter)
      Creates a new DataTable with a table converter.
      Parameters:
      raw - the underlying table
      tableConverter - to transform the table
      Returns:
      a new data table containing the raw values
      Throws:
      NullPointerException - if either raw or tableConverter is null
      IllegalArgumentException - when the table is not rectangular or contains null values

    • emptyDataTable

      public static DataTable emptyDataTable()
      Creates an empty DataTable.
      Returns:
      an empty DataTable

    • getTableConverter

      public DataTable.TableConverter getTableConverter()
      Returns the table converter of this data table.
      Returns:
      the tables table converter

    • diff

      public void diff(DataTable actual) throws TableDiffException
      Performs a diff against an other instance.
      Parameters:
      actual - the other table to diff with
      Throws:
      TableDiffException - if the tables are different

    • unorderedDiff

      public void unorderedDiff(DataTable actual) throws TableDiffException
      Performs an unordered diff against an other instance.
      Parameters:
      actual - the other table to diff with
      Throws:
      TableDiffException - if the tables are different

    • values

      public List<String> values()
      Returns the values in the table as a single list. Contains the cells ordered from left to right, top to bottom, starting at the top left.
      Returns:
      the values of the table

    • asList

      public List<String> asList()
      Converts the table to a list of Strings.
      Returns:
      a list of strings
      See Also:

    • asList

      public <T> List<T> asList(Class<T> itemType)
      Converts the table to a list of itemType.
      Type Parameters:
      T - the type of the list items
      Parameters:
      itemType - the type of the list items
      Returns:
      a list of objects
      See Also:

    • asList

      public <T> List<T> asList(Type itemType)
      Converts the table to a list of itemType.
      Type Parameters:
      T - the type of the list items
      Parameters:
      itemType - the type of the list items
      Returns:
      a list of objects
      See Also:

    • asLists

      public List<List<String>> asLists()
      Converts the table to a list of lists of Strings.
      Returns:
      a list of list of strings
      See Also:

    • asLists

      public <T> List<List<T>> asLists(Class<T> itemType)
      Converts the table to a list of lists of itemType.
      Type Parameters:
      T - the type of the list items
      Parameters:
      itemType - the type of the list items
      Returns:
      a list of list of objects
      See Also:

    • asLists

      public <T> List<List<T>> asLists(Type itemType)
      Converts the table to a list of lists of itemType.
      Type Parameters:
      T - the type of the list items
      Parameters:
      itemType - the type of the list items
      Returns:
      a list of list of objects
      See Also:

    • asMap

      public Map<String,String> asMap()
      Converts the table to a single map of String to String.

      For each row the first cell is used to create the key value. The remaining cells are used to create the value. If the table only has a single column that value is null.

      Returns:
      a map
      See Also:

    • asMap

      public <K, V> Map<K,V> asMap(Class<K> keyType, Class<V> valueType)
      Converts the table to a single map of keyType to valueType.

      For each row the first cell is used to create the key value. The remaining cells are used to create the value. If the table only has a single column that value is null.

      Type Parameters:
      K - key type
      V - value type
      Parameters:
      keyType - key type
      valueType - value type
      Returns:
      a map
      See Also:

    • asMap

      public <K, V> Map<K,V> asMap(Type keyType, Type valueType)
      Converts the table to a single map of keyType to valueType.

      For each row the first cell is used to create the key value. The remaining cells are used to create the value. If the table only has a single column that value is null.

      Type Parameters:
      K - key type
      V - value type
      Parameters:
      keyType - key type
      valueType - value type
      Returns:
      a map
      See Also:

    • entries

      public List<Map<String,String>> entries()
      Returns a view of the entries in a table. An entry is a map of the header values to the corresponding values in a row in the body of the table.
      Returns:
      a view of the entries in a table.

    • asMaps

      public List<Map<String,String>> asMaps()
      Converts the table to a list of maps of strings. For each row in the body of the table a map is created containing a mapping of column headers to the column cell of that row.
      Returns:
      a list of maps
      See Also:

    • asMaps

      public <K, V> List<Map<K,V>> asMaps(Type keyType, Type valueType)
      Converts the table to a list of maps of keyType to valueType. For each row in the body of the table a map is created containing a mapping of column headers to the column cell of that row.
      Type Parameters:
      K - key type
      V - value type
      Parameters:
      keyType - key type
      valueType - value type
      Returns:
      a list of maps
      See Also:

    • asMaps

      public <K, V> List<Map<K,V>> asMaps(Class<K> keyType, Class<V> valueType)
      Converts the table to a list of maps of keyType to valueType. For each row in the body of the table a map is created containing a mapping of column headers to the column cell of that row.
      Type Parameters:
      K - key type
      V - value type
      Parameters:
      keyType - key type
      valueType - value type
      Returns:
      a list of maps
      See Also:

    • cells

      public List<List<String>> cells()
      Returns the cells of the table.
      Returns:
      the cells of the table

    • cell

      public String cell(int row, int column)
      Returns a single table cell.
      Parameters:
      row - row index of the cell
      column - column index of the cell
      Returns:
      a single table cell
      Throws:
      IndexOutOfBoundsException - when either row or column is outside the table.

    • column

      public List<String> column(int column)
      Returns a single column.
      Parameters:
      column - column index the column
      Returns:
      a single column
      Throws:
      IndexOutOfBoundsException - when column is outside the table.

    • columns

      public DataTable columns(int fromColumn)
      Returns a table that is a view on a portion of this table. The sub table begins at fromColumn inclusive and extends to the end of that table.
      Parameters:
      fromColumn - the beginning column index, inclusive
      Returns:
      the specified sub table
      Throws:
      IndexOutOfBoundsException - when any endpoint is outside the table.
      IllegalArgumentException - when a from endpoint comes after an to endpoint

    • columns

      public DataTable columns(int fromColumn, int toColumn)
      Returns a table that is a view on a portion of this table. The sub table begins at fromColumn inclusive and extends to toColumn exclusive.
      Parameters:
      fromColumn - the beginning column index, inclusive
      toColumn - the end column index, exclusive
      Returns:
      the specified sub table
      Throws:
      IndexOutOfBoundsException - when any endpoint is outside the table.
      IllegalArgumentException - when a from endpoint comes after an to endpoint

    • convert

      public <T> T convert(Class<T> type, boolean transposed)
      Converts a table to type.
      Type Parameters:
      T - the desired type
      Parameters:
      type - the desired type
      transposed - transpose the table before transformation
      Returns:
      an instance of type

    • convert

      public <T> T convert(Type type, boolean transposed)
      Converts a table to type.
      Type Parameters:
      T - the desired type
      Parameters:
      type - the desired type
      transposed - transpose the table before transformation
      Returns:
      an instance of type

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • isEmpty

      public boolean isEmpty()
      Returns true iff this table has no cells.
      Returns:
      true iff this table has no cells

    • row

      public List<String> row(int row)
      Returns a single row.
      Parameters:
      row - row index the column
      Returns:
      a single row
      Throws:
      IndexOutOfBoundsException - when row is outside the table.

    • rows

      public DataTable rows(int fromRow)
      Returns a table that is a view on a portion of this table. The sub table begins at fromRow inclusive and extends to the end of that table.
      Parameters:
      fromRow - the beginning row index, inclusive
      Returns:
      the specified sub table
      Throws:
      IndexOutOfBoundsException - when any endpoint is outside the table.
      IllegalArgumentException - when a from endpoint comes after an to endpoint

    • rows

      public DataTable rows(int fromRow, int toRow)
      Returns a table that is a view on a portion of this table. The sub table begins at fromRow inclusive and extends to toRow exclusive.
      Parameters:
      fromRow - the beginning row index, inclusive
      toRow - the end row index, exclusive
      Returns:
      the specified sub table
      Throws:
      IndexOutOfBoundsException - when any endpoint is outside the table.
      IllegalArgumentException - when a from endpoint comes after an to endpoint

    • subTable

      public DataTable subTable(int fromRow, int fromColumn)
      Returns a table that is a view on a portion of this table. The sub table begins at fromRow inclusive and fromColumn inclusive and extends to the last column and row.
      Parameters:
      fromRow - the beginning row index, inclusive
      fromColumn - the beginning column index, inclusive
      Returns:
      the specified sub table
      Throws:
      IndexOutOfBoundsException - when any endpoint is outside the table.

    • subTable

      public DataTable subTable(int fromRow, int fromColumn, int toRow, int toColumn)
      Returns a table that is a view on a portion of this table. The sub table begins at fromRow inclusive and fromColumn inclusive and extends to toRow exclusive and toColumn exclusive.
      Parameters:
      fromRow - the beginning row index, inclusive
      fromColumn - the beginning column index, inclusive
      toRow - the end row index, exclusive
      toColumn - the end column index, exclusive
      Returns:
      the specified sub table
      Throws:
      IndexOutOfBoundsException - when any endpoint is outside the table.
      IllegalArgumentException - when a from endpoint comes after an to endpoint

    • height

      public int height()
      Returns the number of rows in the table.
      Returns:
      the number of rows in the table

    • width

      public int width()
      Returns the number of columns in the table.
      Returns:
      the number of columns in the table

    • toString

      public String toString()
      Returns a string representation of the this table.
      Overrides:
      toString in class Object

    • print

      @Deprecated public void print(Appendable appendable) throws IOException
      Deprecated.
      superseded by DataTableFormatter.formatTo(DataTable, Appendable)
      Prints a string representation of this table to the appendable.
      Parameters:
      appendable - to append the string representation of this table to.
      Throws:
      IOException - If an I/O error occurs

    • print

      @Deprecated public void print(StringBuilder appendable)
      Deprecated.
      superseded by DataTableFormatter.formatTo(DataTable, StringBuilder)
      Prints a string representation of this table to the appendable.
      Parameters:
      appendable - to append the string representation of this table to.

    • transpose

      public DataTable transpose()
      Returns a transposed view on this table. Example: 
          | a | 7 | 4 |
    | b | 9 | 2 |

      becomes: 

       | a | b |
 | 7 | 9 |
 | 4 | 2 |
      Returns:
      a transposed view of the table