Column (tech.bitey:dataframe 0.3.2 API)

Type Parameters:: E - the type of elements in this list

All Superinterfaces:: Collection<E>, Iterable<E>, List<E>

All Known Subinterfaces:: BooleanColumn, ByteColumn, DateColumn, DateTimeColumn, DecimalColumn, DoubleColumn, FloatColumn, IntColumn, LongColumn, NumericColumn<E>, ShortColumn, StringColumn

All Known Implementing Classes:: EnumColumn

public interface Column<E>
extends List<E>

An immutable List 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:

**Column Implementation Overview**
Database Terminology	isNonnull	isSorted	isDistinct	`Spliterator` characteristics	Find by Value / Binary Search
Heap, NULL	FALSE	FALSE	FALSE	`ORDERED`, `IMMUTABLE`	O(n) No
Heap, NOT NULL	TRUE	FALSE	FALSE	`ORDERED`, `IMMUTABLE`, `NONNULL`	O(n) No
Index	TRUE	TRUE	FALSE	`ORDERED`, `IMMUTABLE`, `NONNULL`, `SORTED`	O(log(n)) Yes
Unique Index	TRUE	TRUE	TRUE	`ORDERED`, `IMMUTABLE`, `NONNULL`, `SORTED`, `DISTINCT`	O(log(n)) Yes

Additional Notes

The characteristics cannot be mixed and matched arbitrarily. Rather: DISTINCT implies SORTED implies NONNULL.
All columns report SIZED and SUBSIZED in addition to the characteristics listed above.

Author:: biteytech@protonmail.com

Field Summary

Fields
Modifier and Type Field and Description

static int BASE_CHARACTERISTICS

Fields
Modifier and Type	Field and Description
`static int`	`BASE_CHARACTERISTICS`

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
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.
`E`	`ceiling(E value)` Returns the least element in this column greater than or equal to the given element, or `null` if there is no such element.
`int`	`characteristics()` Returns the `Spliterator.characteristics()` for this column.
`Comparator<? super E>`	`comparator()` Returns the comparator used to order the elements in this column.
`Column<E>`	`copy()` Returns a column equal to this one, but with elements stored in a newly allocated buffer.
`E`	`first()` Returns the first (lowest) element in this column.
`E`	`floor(E value)` Returns the greatest element in this column less than or equal to the given element, or `null` if there is no such element.
`ColumnType<E>`	`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`.
`E`	`higher(E value)` Returns the least element in this column strictly greater than the given element, or `null` if there is no such element.
`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.
`E`	`last()` Returns the last (highest) element in this column.
`E`	`lower(E value)` Returns the greatest element in this column strictly less than the given element, or `null` if there is no such element.
`default Spliterator<E>`	`spliterator()` Creates a `Spliterator` over the elements in this list.
`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>`	`subColumnByValue(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>`	`subColumnByValue(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>`	`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.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<E> 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)
  - 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>
    
    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.
  - comparator
```
Comparator<? super E> comparator()
```
    Returns the comparator used to order the elements in this column.
    
    Returns:
    
    the comparator used to order the elements in this column.
  - first
```
E first()
```
    Returns the first (lowest) element in this column.
    
    Returns:
    
    the first (lowest) element in this column
    
    Throws:
    
    NoSuchElementException - if this column is empty
  - last
```
E last()
```
    Returns the last (highest) element in this column.
    
    Returns:
    
    the last (highest) element in this column
    
    Throws:
    
    NoSuchElementException - if this column is empty
  - lower
```
E lower(E value)
```
    Returns the greatest element in this column strictly less than the given element, or null if there is no such element.
    
    Parameters:
    
    value - the value to match
    
    Returns:
    
    the greatest element less than e, or null if there is no such element
    
    Throws:
    
    UnsupportedOperationException - if column is not a unique index, i.e. the DISTINCT flag is not set
  - higher
```
E higher(E value)
```
    Returns the least element in this column strictly greater than the given element, or null if there is no such element.
    
    Parameters:
    
    value - the value to match
    
    Returns:
    
    the least element greater than e, or null if there is no such element
    
    Throws:
    
    UnsupportedOperationException - if column is not a unique index, i.e. the DISTINCT flag is not set
  - floor
```
E floor(E value)
```
    Returns the greatest element in this column less than or equal to the given element, or null if there is no such element.
    
    Parameters:
    
    value - the value to match
    
    Returns:
    
    the greatest element less than or equal to e, or null if there is no such element
    
    Throws:
    
    UnsupportedOperationException - if column is not a unique index, i.e. the DISTINCT flag is not set
  - ceiling
```
E ceiling(E value)
```
    Returns the least element in this column greater than or equal to the given element, or null if there is no such element.
    
    Parameters:
    
    value - the value to match
    
    Returns:
    
    the least element greater than or equal to e, or null if there is no such element
    
    Throws:
    
    UnsupportedOperationException - if column is not a unique index, i.e. the DISTINCT flag is not set
  - subColumnByValue
```
Column<E> subColumnByValue(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 result
    
    toElement - high endpoint of the returned column
    
    toInclusive - true if the high endpoint is to be included in the result
    
    Returns:
    
    a view of the portion of this column whose elements range from fromElement to toElement
    
    Throws:
    
    UnsupportedOperationException - if isDistinct() return false
    
    IllegalArgumentException - if fromElement is greater than toElement
  - subColumnByValue
```
Column<E> subColumnByValue(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
  - 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
  - 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

Interface Column<E>

Field Summary

Method Summary

Methods inherited from interface java.util.List

Methods inherited from interface java.util.Collection

Methods inherited from interface java.lang.Iterable

Field Detail

BASE_CHARACTERISTICS

Method Detail

characteristics

isNonnull

isSorted

isDistinct

toHeap

toSorted

toDistinct

getType

isNull

subColumn

spliterator

append

append

copy

comparator

first

last

lower

higher

floor

ceiling

subColumnByValue

subColumnByValue

head

head

tail

tail