tech.bitey.dataframe

Interface Column<E>

Type Parameters:

E - the type of elements in this list

All Superinterfaces:

Collection<E>, Iterable<E>, List<E>, NavigableSet<E>, Set<E>, SortedSet<E>

All Known Subinterfaces:

BooleanColumn, DateColumn, DateTimeColumn, DoubleColumn, FloatColumn, IntColumn, LongColumn, NumericColumn<E>, StringColumn

All Known Implementing Classes:

NonNullSingleBufferColumn

public interface Column<E>
extends List<E>, NavigableSet<E>

An immutable collection backed by a primitive array. Elements of type E are packed/unpacked to and from the backing array. Columns implement both List and NavigableSet. List is the primary interface, and all List methods are always available. There are (up to) three concrete implementations of a Column for each element type, with different tradeoffs between performance and functionality. The methods isNullable() and isSortedSet() can be used to determine the characteristics of a particular column:

Column Implementation Overview

Database Terminology	Implementation	isNullable	isSortedSet	Spliterator characteristics	Get by Index / RandomAccess	Find by Value/ Binary Search
Heap, NULL	NullableColumn	TRUE	FALSE	ORDERED, IMMUTABLE	O(n) / FALSE	O(n) / FALSE
Heap, NOT NULL	NonNullColumn sortedSet=FALSE	FALSE	FALSE	ORDERED, IMMUTABLE, NONNULL	O(1) / TRUE	O(n) / FALSE
Unique Index	NonNullColumn sortedSet=TRUE	FALSE	TRUE	ORDERED, IMMUTABLE, NONNULL, SORTED, DISTINCT	O(1) / TRUE	O(log(n)) / TRUE

Note: NavigableSet operations are only available for unique indices (i.e., when isSortedSet() -> true)! They will throw UnsupportedOperationException otherwise.

All concrete implementations of Column must be done via AbstractColumn. It is not enough to simply implement this interface.

Author:

Lior Privman

Method Summary

Modifier and Type	Method and Description
Column<E>	append(Column<E> tail) Appends two columns with the same element type.
default Column<E>	append(Column<E> tail, boolean coerce) Appends two columns with the same element type.
ColumnType	getType()
Column<E>	head(E toElement) Same behavior as head(Object, boolean), with inclusive set to false.
Column<E>	head(E toElement, boolean inclusive) Returns a view of the portion of this column whose elements are less than (or equal to, if inclusive is true) toElement.
boolean	isNull(int index) Test if a value is null at a given index.
boolean	isNullable() Indicates the nullability of this column.
boolean	isSortedSet() The array organization of this column: either a free-form heap, or a unique index.
default Spliterator<E>	spliterator() Creates a Spliterator over the elements in this list.
Column<E>	subColumn(E fromElement, boolean fromInclusive, E toElement, boolean toInclusive) Returns a view of the portion of this column whose elements range from fromElement to toElement.
Column<E>	subColumn(E fromElement, E toElement) Same behavior as Column#subColumn(Object, boolean, Object, Boolean), with fromInclusive set to true and toInclusive set to false.
Column<E>	subColumn(int fromIndex, int toIndex) Returns a view of the portion of this column between the specified fromIndex, inclusive, and toIndex, exclusive.
Column<E>	tail(E fromElement) Same behavior as tail(Object, boolean), with inclusive set to true.
Column<E>	tail(E fromElement, boolean inclusive) Returns a view of the portion of this column whose elements are greater than (or equal to, if inclusive is true) fromElement.
Column<E>	toHeap() Converts a unique index into a heap.

Methods inherited from interface java.util.List

add, add, addAll, addAll, clear, contains, containsAll, equals, get, hashCode, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, remove, remove, removeAll, replaceAll, retainAll, set, size, sort, subList, toArray, toArray

Methods inherited from interface java.util.NavigableSet

ceiling, descendingIterator, descendingSet, floor, headSet, headSet, higher, iterator, lower, pollFirst, pollLast, subSet, subSet, tailSet, tailSet

Methods inherited from interface java.util.SortedSet

comparator, first, last

Methods inherited from interface java.util.Collection

parallelStream, removeIf, stream

Methods inherited from interface java.lang.Iterable

forEach

Method Detail

isNullable

boolean isNullable()

Indicates the nullability of this column.

Returns:

true iff this column supports null values.

isSortedSet

boolean isSortedSet()

The array organization of this column: either a free-form heap, or a unique index.

Returns:

true iff this column is a unique index. Meaning the elements are sorted and distinct.

toHeap

Column<E> toHeap()

Converts a unique index into a heap.

Returns:

a column equal to this one, but which reports isSortedSet() as false

getType

ColumnType getType()

Returns:

this column's type.

isNull

boolean isNull(int index)

Test if a value is null at a given index.

Parameters:

index - the index to test

Returns:

true iff the value at the given index is null

subColumn

Column<E> subColumn(int fromIndex,
                    int toIndex)

Returns a view of the portion of this column between the specified fromIndex, inclusive, and toIndex, exclusive. (If fromIndex and toIndex are equal, the returned list is empty.) The returned column is backed by this column.

Parameters:

fromIndex - low endpoint (inclusive) of the subList

toIndex - high endpoint (exclusive) of the subList

Returns:

a view of the specified range within this column

Throws:

IndexOutOfBoundsException - for an illegal endpoint index value (fromIndex < 0 || toIndex > size || fromIndex > toIndex)

subColumn

Column<E> subColumn(E fromElement,
                    boolean fromInclusive,
                    E toElement,
                    boolean toInclusive)

Returns a view of the portion of this column whose elements range from fromElement to toElement. If fromElement and toElement are equal, the returned column is empty unless fromInclusive and toInclusive are both true. The returned column is backed by this column.

This method is only available when isSortedSet() returns true.

Parameters:

fromElement - low endpoint of the returned column

fromInclusive - true if the low endpoint is to be included in the returned view

toElement - high endpoint of the returned column

toInclusive - true if the high endpoint is to be included in the returned view

Returns:

a view of the portion of this column whose elements range from fromElement to toElement

Throws:

UnsupportedOperationException - if isSortedSet() return false

ClassCastException - if fromElement and toElement do not match type E

NullPointerException - if fromElement or toElement is null

IllegalArgumentException - if fromElement is greater than toElement

subColumn

Column<E> subColumn(E fromElement,
                    E toElement)

Same behavior as Column#subColumn(Object, boolean, Object, Boolean), with fromInclusive set to true and toInclusive set to false.

This method is only available when isSortedSet() returns true.

Parameters:

fromElement - low endpoint of the returned column, inclusive

toElement - high endpoint of the returned column, exclusive

Returns:

view of the portion of this column whose elements range from fromElement, inclusive, to toElement, exclusive

head

Column<E> head(E toElement,
               boolean inclusive)

Returns a view of the portion of this column whose elements are less than (or equal to, if inclusive is true) toElement. The returned column is backed by this column.

This method is only available when isSortedSet() returns true.

Parameters:

toElement - high endpoint of the returned column

inclusive - true if the high endpoint is to be included in the returned view

Returns:

a view of the portion of this column whose elements are less than (or equal to, if inclusive is true) toElement

Throws:

UnsupportedOperationException - if isSortedSet() return false

ClassCastException - if toElement is not compatible with this column's element type.

NullPointerException - if toElement is null

head

Column<E> head(E toElement)

Same behavior as head(Object, boolean), with inclusive set to false.

This method is only available when isSortedSet() returns true.

Parameters:

toElement - high endpoint of the returned column

Returns:

a view of the portion of this column whose elements are less than toElement

tail

Column<E> tail(E fromElement,
               boolean inclusive)

Returns a view of the portion of this column whose elements are greater than (or equal to, if inclusive is true) fromElement. The returned column is backed by this column.

This method is only available when isSortedSet() returns true.

Parameters:

fromElement - low endpoint of the returned column

inclusive - true if the low endpoint is to be included in the returned view

Returns:

a view of the portion of this column whose elements are greater than or equal to fromElement

Throws:

UnsupportedOperationException - if isSortedSet() return false

ClassCastException - if fromElement is not compatible with this column's element type.

NullPointerException - if fromElement is null

tail

Column<E> tail(E fromElement)

Same behavior as tail(Object, boolean), with inclusive set to true.

This method is only available when isSortedSet() returns true.

Parameters:

fromElement - low endpoint of the returned column

Returns:

a view of the portion of this column whose elements are greater than or equal to fromElement

spliterator

default Spliterator<E> spliterator()

Creates a Spliterator over the elements in this list.

The Spliterator reports SIZED, ORDERED, and IMMUTABLE.

Specified by:

spliterator in interface Collection<E>

Specified by:

spliterator in interface Iterable<E>

Specified by:

spliterator in interface List<E>

Specified by:

spliterator in interface Set<E>

Specified by:

spliterator in interface SortedSet<E>

Returns:

a Spliterator over the elements in this column

append

Column<E> append(Column<E> tail)

Appends two columns with the same element type.

Both columns must either be unique indices or not. If they're both unique indices then the first value of the provided column must be greater than the last value of this column.

Parameters:

tail - - the column to be appended to the end of this column

Returns:

the provided column appended to the end of this column

append

default Column<E> append(Column<E> tail,
                         boolean coerce)

Appends two columns with the same element type.

If coerce is true and exactly one of the columns is a unique index, the unique index will be converted to a heap before appending. Otherwise this method behaves like append(Column)

Parameters:

tail - - the column to be appended to the end of this column

coerce - - specifies if the sole unique index should be converted to a heap

Returns:

the provided column appended to the end of this column