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.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	DataTable.TableConverter	Converts a DataTable to another type.

Method Summary

Modifier and Type	Method	Description
List<String>	asList()	Converts the table to a list of Strings.
<T> List<T>	asList(Class<T> itemType)	Converts the table to a list of itemType.
<T> List<T>	asList(Type itemType)	Converts the table to a list of itemType.
List<List<String>>	asLists()	Converts the table to a list of lists of Strings.
<T> List<List<T>>	asLists(Class<T> itemType)	Converts the table to a list of lists of itemType.
<T> List<List<T>>	asLists(Type itemType)	Converts the table to a list of lists of itemType.
Map<String,String>	asMap()	Converts the table to a single map of String to String.
<K,V> Map<K,V>	asMap(Class<K> keyType, Class<V> valueType)	Converts the table to a single map of keyType to valueType.
<K,V> Map<K,V>	asMap(Type keyType, Type valueType)	Converts the table to a single map of keyType to valueType.
List<Map<String,String>>	asMaps()	Converts the table to a list of maps of strings.
<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.
<K,V> List<Map<K,V>>	asMaps(Type keyType, Type valueType)	Converts the table to a list of maps of keyType to valueType.
String	cell(int row, int column)	Returns a single table cell.
List<List<String>>	cells()	Returns the cells of the table.
List<String>	column(int column)	Returns a single column.
DataTable	columns(int fromColumn)	Returns a table that is a view on a portion of this table.
DataTable	columns(int fromColumn, int toColumn)	Returns a table that is a view on a portion of this table.
<T> T	convert(Class<T> type, boolean transposed)	Converts a table to type.
<T> T	convert(Type type, boolean transposed)	Converts a table to type.
static DataTable	create(List<List<String>> raw)	Creates a new DataTable.
static DataTable	create(List<List<String>> raw, DataTable.TableConverter tableConverter)	Creates a new DataTable with a table converter.
void	diff(DataTable actual)	Performs a diff against an other instance.
static DataTable	emptyDataTable()	Creates an empty DataTable.
List<Map<String,String>>	entries()	Returns a view of the entries in a table.
boolean	equals(Object o)
DataTable.TableConverter	getTableConverter()	Returns the table converter of this data table.
int	hashCode()
int	height()	Returns the number of rows in the table.
boolean	isEmpty()	Returns true iff this table has no cells.
void	print(Appendable appendable)	Deprecated. superseded by DataTableFormatter.formatTo(DataTable, Appendable)
void	print(StringBuilder appendable)	Deprecated. superseded by DataTableFormatter.formatTo(DataTable, StringBuilder)
List<String>	row(int row)	Returns a single row.
DataTable	rows(int fromRow)	Returns a table that is a view on a portion of this table.
DataTable	rows(int fromRow, int toRow)	Returns a table that is a view on a portion of this table.
DataTable	subTable(int fromRow, int fromColumn)	Returns a table that is a view on a portion of this table.
DataTable	subTable(int fromRow, int fromColumn, int toRow, int toColumn)	Returns a table that is a view on a portion of this table.
String	toString()	Returns a string representation of the this table.
DataTable	transpose()	Returns a transposed view on this table.
void	unorderedDiff(DataTable actual)	Performs an unordered diff against an other instance.
List<String>	values()	Returns the values in the table as a single list.
int	width()	Returns the number of columns in the table.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

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:

DataTable.TableConverter.toList(DataTable, Type)

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:

DataTable.TableConverter.toList(DataTable, Type)

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:

DataTable.TableConverter.toList(DataTable, Type)

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:

DataTable.TableConverter.toLists(DataTable, Type)

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:

DataTable.TableConverter.toLists(DataTable, Type)

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:

DataTable.TableConverter.toLists(DataTable, Type)

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:

DataTable.TableConverter.toMap(DataTable, Type, Type)

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:

DataTable.TableConverter.toMap(DataTable, Type, Type)

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:

DataTable.TableConverter.toMap(DataTable, Type, Type)

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:

DataTable.TableConverter.toMaps(DataTable, Type, Type)

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:

DataTable.TableConverter.toMaps(DataTable, Type, Type)

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:

DataTable.TableConverter.toMaps(DataTable, Type, Type)

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