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 nio buffers. Elements of type E are packed/unpacked to and from the buffers. There are four variants for each element type, with different tradeoffs between performance and functionality. The methods isNonnull(), isSorted(), and isDistinct() can be used to query the characteristics() of a column:

Column Implementation Overview

Database Terminology	isNonnull	isSorted	isDistinct	Spliterator characteristics	Get by Index / RandomAccess	Find by Value/ Binary Search
Heap, NULL	FALSE	FALSE	FALSE	ORDERED, IMMUTABLE	O(n) / FALSE	O(n) / FALSE
Heap, NOT NULL	TRUE	FALSE	FALSE	ORDERED, IMMUTABLE, NONNULL	O(1) / TRUE	O(n) / FALSE
Index	TRUE	TRUE	FALSE	ORDERED, IMMUTABLE, NONNULL, SORTED	O(1) / TRUE	O(log(n)) / TRUE
Unique Index	TRUE	TRUE	TRUE	ORDERED, IMMUTABLE, NONNULL, SORTED, DISTINCT	O(1) / TRUE	O(log(n)) / TRUE

Additional Notes

• The characteristics cannot be mixed and matched arbitrarily. Rather: DISTINCT implies SORTED implies NONNULL.
• All columns report SIZED, SUBSIZED, and IMMUTABLE in addition to the ones listed above.
• Columns implement both List and NavigableSet. List is the primary interface, and all List methods are always available. NavigableSet operations are only available for unique indices (i.e., when isDistinct() -> true). They will throw UnsupportedOperationException otherwise.

Author:

Lior Privman

Field Summary

Fields

Modifier and Type	Field and Description
static int	BASE_CHARACTERISTICS

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.
int	characteristics() Returns the Spliterator.characteristics() for this column.
Column<E>	copy() Returns a column equal to this one, but with elements stored in a newly allocated buffer.
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.
default boolean	isDistinct() Returns true if the Spliterator.DISTINCT flag is set.
default boolean	isNonnull() Returns true if the Spliterator.NONNULL flag is set.
boolean	isNull(int index) Test if a value is null at a given index.
default boolean	isSorted() Returns true if the Spliterator.SORTED flag is set.
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>	toDistinct() Converts a column to a unique index.
Column<E>	toHeap() Converts an index into a heap.
Column<E>	toSorted() Converts a heap to an index.

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

Field Detail

BASE_CHARACTERISTICS

static final int BASE_CHARACTERISTICS

See Also:

Constant Field Values

Method Detail

characteristics

int characteristics()

Returns the Spliterator.characteristics() for this column.

Returns:

the characteristics for this column

isNonnull

default boolean isNonnull()

Returns true if the Spliterator.NONNULL flag is set.

Returns:

true if the NONNULL flag is set.

isSorted

default boolean isSorted()

Returns true if the Spliterator.SORTED flag is set.

Returns:

true if the SORTED flag is set.

isDistinct

default boolean isDistinct()

Returns true if the Spliterator.DISTINCT flag is set.

Returns:

true if the DISTINCT flag is set.

toHeap

Column<E> toHeap()

Converts an index into a heap.

Returns:

a column equal to this one, but which reports isSorted() as false. The resulting column shares the same underlying buffer as this one.

toSorted

Column<E> toSorted()

Converts a heap to an index. The resulting column will have the same elements, but sorted in ascending order. The behavior of this method depends on the characteristics() of this column:

• heap - checks if the column is already sorted. If so, returns a new column which shares the same underlying buffer, but with SORTED flag set. If not already sorted then copy() will be invoked, and the resulting column will be sorted.
• sorted - returns this column
• distinct - returns a new column which shares the same underlying buffer, but with DISTINCT flag unset.

Returns:

a column with elements sorted in ascending order

Throws:

UnsupportedOperationException - if the NONNULL flag is not set

toDistinct

Column<E> toDistinct()

Converts a column to a unique index. The behavior of this method depends on the characteristics() of this column:

• heap - checks if the column is already sorted and distinct. If so, returns a new column which shares the same underlying buffer, but with SORTED and DISTINCT flags set. If not already sorted and distinct then copy() will be invoked, and the resulting column will be sorted and deduplicated.
• sorted - checks if the column contains duplicates. If not, returns a new column which shares the same underlying buffer, but with DISTINCT flag set. If duplicates are present then copy() will be invoked, and the resulting column will be deduplicated.
• distinct - returns this column

Returns:

a column with distinct elements sorted in ascending order

Throws:

UnsupportedOperationException - if the NONNULL flag is not set

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 isDistinct() 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 isDistinct() 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 isDistinct() 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 isDistinct() 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 isDistinct() 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 isDistinct() 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 isDistinct() 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 isDistinct() 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 isDistinct() 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, SUBSIZED, 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 have the same characteristics. 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 one of the columns is sorted, the sorted column 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 a sole sorted column should be converted to a heap

Returns:

the provided column appended to the end of this column

copy

Column<E> copy()

Returns a column equal to this one, but with elements stored in a newly allocated buffer.

Returns:

a column equal to this one, but with elements stored in a newly allocated buffer.