org.fulib.tables

Class Table<T>

java.lang.Object

org.fulib.tables.Table<T>

Type Parameters:

T - the type of values contained in the column this table points to

All Implemented Interfaces:

java.lang.Iterable<T>

Direct Known Subclasses:

BooleanTable, doubleTable, floatTable, intTable, longTable, ObjectTable, StringTable

public class Table<T>
extends java.lang.Object
implements java.lang.Iterable<T>

Provides a mechanism for managing object structures in a row and column format. This is not to be viewed as a way to store arbitrary objects in a matrix of sorts; the operations of this class are specific to object structures. It is intentionally not possible to access specific cells with given row and column.

Each table instance maintains a column name, called the column pointer, and an underlying data structure. The underlying data is shared between table instances derived from one another. As such, operations on one table usually cause changes in derived or original tables. This can be prevented with the copy() operation, which does a full copy of all data such that the copy is no longer connected to the original.

Various subclasses exist for type-specific operations, e.g. primitive numbers (intTable, longTable, floatTable, doubleTable), other standard data types (StringTable, BooleanTable), and model objects (ObjectTable).

Since:

1.2

Constructor Summary

Constructors

Constructor and Description
Table() Creates a new empty table with zero rows and zero columns.
Table(java.lang.String columnName) Creates a new empty table with zero rows and one column with the given name.
Table(java.lang.String columnName, T... start) Creates a new table with the given objects in the first column.
Table(T... start) Creates a new table with the given objects in the first column, which uses the default name "A".

Method Summary

Modifier and Type	Method and Description
<TAB extends Table<T>> TAB	as(java.lang.Class<? extends TAB> type) Coerces this table to the given type by creating a new instance of that type that points to the same underlying data structure and column.
Table<T>	copy() Creates a copy of this table.
<U> Table<U>	derive(java.lang.String targetColumn, java.util.function.Function<? super java.util.Map<java.lang.String,java.lang.Object>,? extends U> function) Creates a new column with the given name by applying the given function to each row.
<U> Table<U>	deriveAll(java.lang.String targetColumn, java.util.function.Function<? super java.util.Map<java.lang.String,java.lang.Object>,? extends java.util.Collection<? extends U>> function) Creates a new column with the given name by applying the given function to each row, and flattening the result.
Table<T>	dropColumns(java.lang.String... columnNames) Removes all given columns from the underlying data structure and ensures no duplicate rows exist afterwards.
<U> Table<U>	expand(java.lang.String targetColumn, java.util.function.Function<? super T,? extends U> function) Creates a new column with the given name by applying the given function to each object in the column pointed to by this table.
<V,U> Table<U>	expand(java.lang.String sourceColumn, java.lang.String targetColumn, java.util.function.Function<? super V,? extends U> function) Creates a new column with the given name by applying the given function to each object in the given column.
<U> Table<U>	expandAll(java.lang.String targetColumn, java.util.function.Function<? super T,? extends java.util.Collection<? extends U>> function) Creates a new column with the given name by applying the given function to each object in the column pointed to by this table, and flattening the result.
<V,U> Table<U>	expandAll(java.lang.String sourceColumn, java.lang.String targetColumn, java.util.function.Function<? super V,? extends java.util.Collection<? extends U>> function) Creates a new column with the given name by applying the given function to each object in the given column, and flattening the result.
Table<T>	filter(java.util.function.Predicate<? super T> predicate) Removes all rows from this table for which the predicate returned false when passed the cell value of the column this table points to.
<V> Table<T>	filter(java.lang.String sourceColumn, java.util.function.Predicate<? super V> predicate) Removes all rows from this table for which the predicate returned false when passed the cell value in the given column.
Table<T>	filterRows(java.util.function.Predicate<? super java.util.Map<java.lang.String,java.lang.Object>> predicate) Removes all rows from this table for which the predicate returned false.
java.util.LinkedHashMap<java.lang.String,java.lang.Integer>	getColumnMap() Deprecated. since 1.2; for internal use only
java.lang.String	getColumnName()
java.util.ArrayList<java.util.ArrayList<java.lang.Object>>	getTable() Deprecated. since 1.2; for internal use only
java.util.Iterator<T>	iterator()
<V> java.util.Iterator<V>	iterator(java.lang.String sourceColumn)
int	rowCount()
Table<T>	selectColumns(java.lang.String... columnNames) Removes all columns from the underlying data structure except the given ones, and ensures no duplicate rows exist afterwards.
java.util.stream.Stream<T>	stream()
<V> java.util.stream.Stream<V>	stream(java.lang.String sourceColumn)
java.util.List<T>	toList()
<V> java.util.List<V>	toList(java.lang.String sourceColumn)
java.util.Set<T>	toSet()
<V> java.util.Set<V>	toSet(java.lang.String sourceColumn)
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

Table

public Table()

Creates a new empty table with zero rows and zero columns.

Table

public Table(java.lang.String columnName)

Creates a new empty table with zero rows and one column with the given name.

Parameters:

columnName - the column name

Table

@SafeVarargs
public Table(T... start)

Creates a new table with the given objects in the first column, which uses the default name "A".

Parameters:

start - the objects in the first column

Table

@SafeVarargs
public Table(java.lang.String columnName,
                          T... start)

Creates a new table with the given objects in the first column.

Parameters:

columnName - the name of the first column

start - the objects in the first column

Method Detail

copy

public Table<T> copy()

Creates a copy of this table. Modifications of any kind, to the original or copied table, are not reflected in the other instance.

Returns:

a copy of this table

getColumnName

public java.lang.String getColumnName()

Returns:

the name of the column this table points to

as

public <TAB extends Table<T>> TAB as(java.lang.Class<? extends TAB> type)

Coerces this table to the given type by creating a new instance of that type that points to the same underlying data structure and column.

The type must be either one of the Table subclasses in the org.fulib.tables package, or provide a public constructor with one parameter of type Table.

Type Parameters:

TAB - the result type

Parameters:

type - the Class corresponding to <TAB>.

Returns:

a table of the given type pointing to the same underlying data and column as this one

Since:

1.2

expand

public <U> Table<U> expand(java.lang.String targetColumn,
                           java.util.function.Function<? super T,? extends U> function)

Creates a new column with the given name by applying the given function to each object in the column pointed to by this table.

Example:

 Table<Integer> a = new Table<>("A", 1, 2, 3);
 Table<Integer> b = a.expand("B", i -> i * 2);
 

b

A	B
1	2
2	4
3	6

Type Parameters:

U - the cell type of the new column

Parameters:

targetColumn - the name of the new column

function - the function that computes a value for the new column

Returns:

a table pointing to the new column

Since:

1.2

expand

public <V,U> Table<U> expand(java.lang.String sourceColumn,
                             java.lang.String targetColumn,
                             java.util.function.Function<? super V,? extends U> function)

Creates a new column with the given name by applying the given function to each object in the given column.

Example:

 Table<Integer> a = new Table<>("A", 1, 2, 3);
 a.expand("B", i -> i * 2);
 Table<Integer> c = a.expand("B", "C", (Integer i) -> i + 1);
 

c

A	B	C
1	2	3
2	4	5
3	6	7

Type Parameters:

V - the cell type of the column to operate on

U - the cell type of the new column

Parameters:

sourceColumn - the name of the column to operate on

targetColumn - the name of the new column

function - the function that computes a value for the new column

Returns:

a table pointing to the new column

Since:

1.4

expandAll

public <U> Table<U> expandAll(java.lang.String targetColumn,
                              java.util.function.Function<? super T,? extends java.util.Collection<? extends U>> function)

Creates a new column with the given name by applying the given function to each object in the column pointed to by this table, and flattening the result.

Example:

 Table<Integer> a = new Table<>("A", 1, 2);
 Table<Integer> b = a.expandAll("B", i -> Arrays.asList(i + 10, i + 20));
 

b

A	B
1	11
1	21
2	12
2	22

Type Parameters:

U - the cell type of the new column

Parameters:

targetColumn - the name of the new column

function - the function that computes a collection of values for the new column

Returns:

a table pointing to the new column

Since:

1.2

expandAll

public <V,U> Table<U> expandAll(java.lang.String sourceColumn,
                                java.lang.String targetColumn,
                                java.util.function.Function<? super V,? extends java.util.Collection<? extends U>> function)

Creates a new column with the given name by applying the given function to each object in the given column, and flattening the result.

Example:

 Table<Integer> a = new Table<>("A", 1, 2);
 a.expand("B", i -> i * 2);
 Table<Integer> c = a.expandAll("B", "C", (Integer i) -> Arrays.asList(i + 10, i + 20));
 

c

A	B	C
1	2	12
1	2	22
2	4	14
2	4	24

Type Parameters:

V - the cell type of the column to operate on

U - the cell type of the new column

Parameters:

sourceColumn - the name of the column to operate on

targetColumn - the name of the new column

function - the function that computes a collection of values for the new column

Returns:

a table pointing to the new column

Since:

1.4

derive

public <U> Table<U> derive(java.lang.String targetColumn,
                           java.util.function.Function<? super java.util.Map<java.lang.String,java.lang.Object>,? extends U> function)

Creates a new column with the given name by applying the given function to each row.

Example:

 Table<Integer> a = new Table<>("A", 1, 2);
 Table<Integer> b = a.expand("B", i -> i * 10);
 Table<Integer> c = b.derive("C", row -> (int) row.get("A") + (int) row.get("B"));
 

c

A	B	C
1	10	11
2	20	22

Type Parameters:

U - the cell type of the new column

Parameters:

targetColumn - the name of the new column

function - the function that computes a value for the new column

Returns:

a table pointing to the new column

Since:

1.2

deriveAll

public <U> Table<U> deriveAll(java.lang.String targetColumn,
                              java.util.function.Function<? super java.util.Map<java.lang.String,java.lang.Object>,? extends java.util.Collection<? extends U>> function)

Creates a new column with the given name by applying the given function to each row, and flattening the result.

Example:

 Table<Integer> a = new Table<>("A", 1, 2);
 Table<Integer> b = a.expand("B", i -> i * 10);
 Table<Integer> c = b.deriveAll("C", row -> {
    int a1 = (int) row.get("A");
    int b1 = (int) row.get("B");
    return Arrays.asList(a1 + b1, a1 * b1);
 });
 

c

A	B	C
1	10	11
1	10	10
2	20	22
2	20	40

Type Parameters:

U - the cell type of the new column

Parameters:

targetColumn - the name of the new column

function - the function that computes a collection of values for the new column

Returns:

a table pointing to the new column

Since:

1.2

dropColumns

public Table<T> dropColumns(java.lang.String... columnNames)

Removes all given columns from the underlying data structure and ensures no duplicate rows exist afterwards. Given column names that don't exist are ignored.

After this operation, table instances with the same underlying data that pointed to one of these columns will throw an exception when operated on in any way that accesses their corresponding column.

Example:

 Table<String> names = new StringTable("Alice", "Bob", "Charlie", "alice");
 Table<String> uppercase = names.expand("uppercase", String::toUpperCase);
 Table<String> lowercase = names.expand("lowercase", String::toLowerCase);
 

before

A	uppercase	lowercase
Alice	ALICE	alice
Bob	BOB	bob
Charlie	CHARLIE	charlie
alice	ALICE	alice

 names.dropColumns(names.getColumnName());
 

after

uppercase	lowercase
ALICE	alice
BOB	bob
CHARLIE	charlie

 names.toList(); // throws IllegalStateException
 

Parameters:

columnNames - the names of columns to drop

Returns:

this instance, to allow method chaining

selectColumns

public Table<T> selectColumns(java.lang.String... columnNames)

Removes all columns from the underlying data structure except the given ones, and ensures no duplicate rows exist afterwards. If one of the given column names is not part of this table, an IllegalArgumentException is thrown and no changes are made. Note the original order of columns is unaffected by the order of the given names.

After this operation, table instances with the same underlying data that pointed to a columns not part of the given ones will throw an exception when operated on in any way that accesses their corresponding column.

Example:

 Table<String> names = new StringTable("Alice", "Bob", "Charlie", "alice");
 Table<String> uppercase = names.expand("uppercase", String::toUpperCase);
 Table<String> lowercase = names.expand("lowercase", String::toLowerCase);
 

before

A	uppercase	lowercase
Alice	ALICE	alice
Bob	BOB	bob
Charlie	CHARLIE	charlie
alice	ALICE	alice

 names.selectColumns("uppercase", "lowercase");
 

after

uppercase	lowercase
ALICE	alice
BOB	bob
CHARLIE	charlie

 names.toList(); // throws IllegalStateException
 

Parameters:

columnNames - the names of columns to retain

Returns:

this instance, to allow method chaining

Throws:

java.lang.IllegalArgumentException - when columnNames contains a column name that is not part of this table

filter

public Table<T> filter(java.util.function.Predicate<? super T> predicate)

Removes all rows from this table for which the predicate returned false when passed the cell value of the column this table points to.

Example:

 final Table<Integer> numbers = new Table<>("A", 1, 2, 3, 4, 5, 6, 7, 8, 9, 10);
 numbers.filter(i -> i % 2 == 0);
 

result

A
2
4
6
8
10

Parameters:

predicate - the predicate that determines which rows should be kept

Returns:

this table, to allow method chaining

filter

public <V> Table<T> filter(java.lang.String sourceColumn,
                           java.util.function.Predicate<? super V> predicate)

Removes all rows from this table for which the predicate returned false when passed the cell value in the given column.

Example:

 Table<Integer> a = new Table<>("A", 1, 2, 3, 4, 5, 6, 7, 8, 9, 10);
 a.expand("B", i -> i + 1);
 a.filter("B", (Integer i) -> i % 2 == 0);
 

result

A	B
1	2
3	4
5	6
7	8
9	10

Type Parameters:

V - the cell type of the column to operate on

Parameters:

sourceColumn - the name of the column to operate on

predicate - the predicate that determines which rows should be kept

Returns:

this table, to allow method chaining

Since:

1.4

filterRows

public Table<T> filterRows(java.util.function.Predicate<? super java.util.Map<java.lang.String,java.lang.Object>> predicate)

Removes all rows from this table for which the predicate returned false. The rows are passed as maps from column name to cell value.

Example:

 Table<Integer> a = new Table<>("A", 1, 2);
 Table<Integer> b = a.expandAll("B", i -> Arrays.asList(1, 2));
 

before

A	B
1	1
1	2
2	1
2	2

 a.filterRows(row -> (int) row.get("A") != (int) row.get("B"));
 

after

A	B
1	2
2	1

Parameters:

predicate - the predicate that determines which rows should be kept

Returns:

this table, to allow method chaining

Since:

1.2

rowCount

public int rowCount()

Returns:

the number of rows of this table

Since:

1.2

iterator

public java.util.Iterator<T> iterator()

Specified by:

iterator in interface java.lang.Iterable<T>

Returns:

an iterator over the cell values of the column this table instance points to

Since:

1.2

iterator

public <V> java.util.Iterator<V> iterator(java.lang.String sourceColumn)

Parameters:

sourceColumn - the name of the column to operate on

Returns:

an iterator over the cell values of the given column

Since:

1.4

toList

public java.util.List<T> toList()

Returns:

a list of cell values of the column this table instance points to

toList

public <V> java.util.List<V> toList(java.lang.String sourceColumn)

Type Parameters:

V - the cell type of the column to operate on

Parameters:

sourceColumn - the name of the column to operate on

Returns:

a list of cell values of the given column

Since:

1.4

toSet

public java.util.Set<T> toSet()

Returns:

a set of cell values of the column this table instance points to

toSet

public <V> java.util.Set<V> toSet(java.lang.String sourceColumn)

Type Parameters:

V - the cell type of the column to operate on

Parameters:

sourceColumn - the name of the column to operate on

Returns:

a set of cell values of the given column

Since:

1.4

stream

public java.util.stream.Stream<T> stream()

Returns:

a stream of cell values of the column this table instance points to

Since:

1.2

stream

public <V> java.util.stream.Stream<V> stream(java.lang.String sourceColumn)

Type Parameters:

V - the cell type of the column to operate on

Parameters:

sourceColumn - the name of the column to operate on

Returns:

a stream of cell values of the given column

Since:

1.4

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

getTable

@Deprecated
public java.util.ArrayList<java.util.ArrayList<java.lang.Object>> getTable()

Deprecated. since 1.2; for internal use only

Returns:

a 2D copy of the internal table

getColumnMap

@Deprecated
public java.util.LinkedHashMap<java.lang.String,java.lang.Integer> getColumnMap()

Deprecated. since 1.2; for internal use only

Returns:

a copy of the internal column map