Package com.complexible.common.collect

# Class SkippingIterators

java.lang.Object
com.complexible.common.collect.SkippingIterators

public final class SkippingIterators extends Object
Few utility methods to construct skipping iterators.

Version:
  7.9
Author:
  Pavel Klinov

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <T> Comparator<T>`
  `allEqual()`
  `static <T> SkippingIterator<T>`
  `appendCloseable(SkippingIterator<T> iterator, AutoCloseable toClose)`
  `static <T> SkippingIterator<T>`
  `concat(ResettableIterator<SkippingIterator<T>> theIterators, Comparator<T> theComparator, long theEstimatedSize)`
  Returns a skipping iterator which skips through all iterators sequentially.
  `static <T> SkippingIterator<T>`
  `concat(SkippingIterator<T>... theIterators)`
  Returns a skipping iterator which skips through all iterators sequentially
  `static <T extends Copyable<T>>
  SkippingIterator<T>`
  `copy(SkippingIterator<T> iterator)`
  `static <T> PeekingSkippingIterator<T>`
  `distinct(SkippingIterator<T> theIterator)`
  Returns the elements of `theIterator` but filters any duplicates.
  `static <T> PeekingSkippingIterator<T>`
  `emptyIterator()`
  `static <T> PeekingSkippingIterator<T>`
  `filter(SkippingIterator<T> theIterator, Predicate<? super T> theFilter)`
  Returns the elements of `theIterator` that satisfy a predicate.
  `static <T> SkippingIterator<T>`
  `forArray(T[] theArray, int theStart, int theEnd, Comparator<T> theComparator)`
  `static <T> PeekingSkippingIterator<T>`
  `forArray(T[] theArray, Comparator<T> theComparator)`
  `static <T> SkippingIterator<T>`
  `forIterator(ResettableIterator<T> theSource, Comparator<T> theComparator)`
  `static <T> PeekingSkippingIterator<T>`
  `iterateBeginning(SkippingIterator<T> theIterator, T theMin)`
  Returns the elements of `theIterator` that are greater than or equal to the given `theMin` value.
  `static <T> PeekingSkippingIterator<T>`
  `iterateRange(SkippingIterator<T> theIterator, T theMin, T theMax)`
  Returns the elements of `theIterator` that are greater than or equal to the given `theMin` value and less than or equal to the given `theMax` value.
  `static <T> PeekingSkippingIterator<T>`
  `iterateUntil(SkippingIterator<T> theIterator, T theMax)`
  Returns the elements of `theIterator` that are less than or equal to the given `theMax` value.
  `static <T> SkippingIterator<T>`
  `minus(SkippingIterator<T> theIterator, SkippingIterator<T> theFilteredElements)`
  Returns the elements of `theIterator` that are not in `theFilteredElements` .
  `static <T> PeekingSkippingIterator<T>`
  `peekingIterator(SkippingIterator<T> theIterator)`
  `static <T> SkippingIterator<T>`
  `prepend(T theFirst, SkippingIterator<T> theIterator)`
  Functionally equivalent to concatenation of a singleton iterator with the given iterator but might be tad faster.
  `static <T> SkippingIterator<T>`
  `singletonIterator(T theElement, Comparator<T> theComparator)`
  `static <T> ResettablePredicate<T>`
  `sortedContains(SkippingIterator<T> theIterator)`
  Returns a predicate that returns `true` when the argument exists in the given iterator with the caveat that the predicate should be called in sorted order.
  `static <T> ResettablePredicate<T>`
  `sortedContains(SkippingIterator<T> theIterator, BiPredicate<T,T> theEquality)`
  A generalization of `sortedContains` for a more relaxed containment testing.
  `static <T> ResettablePredicate<T>`
  `sortedNotContains(SkippingIterator<T> theIterator)`
  Returns a predicate that returns `true` when the argument exists in the given iterator with the caveat that the predicate should be called in sorted order.
  `static <I, O> SkippingIterator<O>`
  `transform(SkippingIterator<I> theIterator, Function<I,O> theFunction, Function<O,I> theInverseFunction, Comparator<O> theComparator)`
  Returns an iterator that applies `theFunction` to each element of `theIterator`.
  `static <T> SkippingIterator<T>`
  `union(Comparator<T> theComparator, SkippingIterator<T>... theIterators)`
  A generalization of binary union to the n-ary case.
  `static <T> SkippingIterator<T>`
  `union(Comparator<T> theComparator, SkippingIterator<T> theIterator1, SkippingIterator<T> theIterator2)`
  Returns a skipping iterator that is the union of two given iterators where both the base iterators comply with the given comparator.
  `static <T> SkippingIterator<T>`
  `union(Comparator<T> theComparator, SkippingIterator<T> theIterator1, SkippingIterator<T> theIterator2, BiFunction<T,T,T> theMergeFunc)`
  Returns a skipping iterator that is the union of two given iterators where both the base iterators comply with the given comparator and performs the given merge operation when an element exists in both base iterators.
  `static <T> SkippingIterator<T>`
  `unionAll(Comparator<T> theComparator, SkippingIterator<T>... theIterators)`
  `static <T> SkippingIterator<T>`
  `wrap(ResettableIterator<T> theIterator, Comparator<T> theComparator)`
  Wraps the given regular iterator as a `SkippingIterator` that implements skipping by iterating over the base iterator one by one until the skip limit is reached.

  ### Methods inherited from class java.lang.Object

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

- ## Method Details

  - ### forIterator

    public static <T> SkippingIterator<T> forIterator(ResettableIterator<T> theSource, Comparator<T> theComparator)

  - ### forArray

    public static <T> PeekingSkippingIterator<T> forArray(T[] theArray, Comparator<T> theComparator)

  - ### forArray

    public static <T> SkippingIterator<T> forArray(T[] theArray, int theStart, int theEnd, Comparator<T> theComparator)

  - ### sortedContains

    @MustBeClosed public static <T> ResettablePredicate<T> sortedContains(SkippingIterator<T> theIterator)
    Returns a predicate that returns `true` when the argument exists in the given iterator with the caveat that the predicate should be called in sorted order. If the predicate is called first with one element and then with another element that is smaller then the second call is guaranteed to return `false` regardless of the contents of the iterator. The `Resettable.reset()` function can be called to reset the internal state of the predicate.

  - ### sortedContains

    @MustBeClosed public static <T> ResettablePredicate<T> sortedContains(SkippingIterator<T> theIterator, BiPredicate<T,T> theEquality)
    A generalization of `sortedContains` for a more relaxed containment testing. This allows for checking if an element exists in the iterator s.t. that it is equal to the given one w.r.t. a particular equality predicate. The caller must ensure that elements passed to the returned predicate can be used for skipping on the underlying iterator. Also the equality predicate must be consistent with the comparator of the iterator.

  - ### sortedNotContains

    @MustBeClosed public static <T> ResettablePredicate<T> sortedNotContains(SkippingIterator<T> theIterator)
    Returns a predicate that returns `true` when the argument exists in the given iterator with the caveat that the predicate should be called in sorted order. If the predicate is called first with one element and then with another element that is smaller then the second call is guaranteed to return `false` regardless of the contents of the iterator. The `Resettable.reset()` function can be called to reset the internal state of the predicate.

    NOTE: The predicate returned by this function behaves exactly as `Predicates.not(sortedContains(theIterator))` but slightly more efficient.

  - ### iterateRange

    @MustBeClosed public static <T> PeekingSkippingIterator<T> iterateRange(SkippingIterator<T> theIterator, T theMin, T theMax)
    Returns the elements of `theIterator` that are greater than or equal to the given `theMin` value and less than or equal to the given `theMax` value. Iterating over the returned iterator will cause `theIterator` to advance as well. After the returned iterator is consumed, calling `theIterator.next()` will return a value that is greater than or equal `theMax` if there are any more elements left.

  - ### iterateBeginning

    @MustBeClosed public static <T> PeekingSkippingIterator<T> iterateBeginning(SkippingIterator<T> theIterator, T theMin)
    Returns the elements of `theIterator` that are greater than or equal to the given `theMin` value. Iterating over the returned iterator will cause `theIterator` to advance as well.

  - ### iterateUntil

    @MustBeClosed public static <T> PeekingSkippingIterator<T> iterateUntil(SkippingIterator<T> theIterator, T theMax)
    Returns the elements of `theIterator` that are less than or equal to the given `theMax` value. Iterating over the returned iterator will cause `theIterator` to advance as well. After the returned iterator is consumed, calling `theIterator.next()` will return a value that is greater than or equal `theMax` if there are any more elements left.

  - ### filter

    @MustBeClosed public static <T> PeekingSkippingIterator<T> filter(SkippingIterator<T> theIterator, Predicate<? super T> theFilter)
    Returns the elements of `theIterator` that satisfy a predicate. If the predicate is stateful it should implement th `ResettablePredicate` interface.

  - ### distinct

    @MustBeClosed public static <T> PeekingSkippingIterator<T> distinct(SkippingIterator<T> theIterator)
    Returns the elements of `theIterator` but filters any duplicates. Duplicates is determined va `.equals()` check. WARNING: This iterator remembers the last return value and compares it with the next value. The underlying iterator should not return the same mutable object each time multiple times otherwise everything will be thought to be a duplicate.

  - ### minus

    @MustBeClosed public static <T> SkippingIterator<T> minus(SkippingIterator<T> theIterator, SkippingIterator<T> theFilteredElements)
    Returns the elements of `theIterator` that are not in `theFilteredElements` .

  - ### transform

    @MustBeClosed public static <I, O> SkippingIterator<O> transform(SkippingIterator<I> theIterator, Function<I,O> theFunction, Function<O,I> theInverseFunction, Comparator<O> theComparator)
    Returns an iterator that applies `theFunction` to each element of `theIterator`. The function should preserve the order of elements such that for any two values `x` and `y` we have `theIterator.comparator().compare(x, y) == theComparator.compare(theFunction.apply(x), theFunction.apply(y)`

  - ### wrap

    @MustBeClosed public static <T> SkippingIterator<T> wrap(ResettableIterator<T> theIterator, Comparator<T> theComparator)
    Wraps the given regular iterator as a `SkippingIterator` that implements skipping by iterating over the base iterator one by one until the skip limit is reached.

  - ### concat

    @MustBeClosed @SafeVarargs public static <T> SkippingIterator<T> concat(SkippingIterator<T>... theIterators)
    Returns a skipping iterator which skips through all iterators sequentially

  - ### prepend

    @MustBeClosed public static <T> SkippingIterator<T> prepend(T theFirst, SkippingIterator<T> theIterator)
    Functionally equivalent to concatenation of a singleton iterator with the given iterator but might be tad faster.

  - ### concat

    @MustBeClosed public static <T> SkippingIterator<T> concat(ResettableIterator<SkippingIterator<T>> theIterators, Comparator<T> theComparator, long theEstimatedSize)
    Returns a skipping iterator which skips through all iterators sequentially. Note that, resetting `theIterators` should reset all the iterators that has already been returned by this iterator.

  - ### union

    @MustBeClosed public static <T> SkippingIterator<T> union(Comparator<T> theComparator, SkippingIterator<T> theIterator1, SkippingIterator<T> theIterator2)
    Returns a skipping iterator that is the union of two given iterators where both the base iterators comply with the given comparator. The base iterators may span overlapping ranges and contain common elements. The resulting iterator will return all elements in sorted order and skip base iterators as needed. The duplicate elements from both iterators will be returned only once.

  - ### allEqual

    public static <T> Comparator<T> allEqual()

  - ### union

    public static <T> SkippingIterator<T> union(Comparator<T> theComparator, SkippingIterator<T>... theIterators)
    A generalization of binary union to the n-ary case.

  - ### unionAll

    public static <T> SkippingIterator<T> unionAll(Comparator<T> theComparator, SkippingIterator<T>... theIterators)

  - ### union

    public static <T> SkippingIterator<T> union(Comparator<T> theComparator, SkippingIterator<T> theIterator1, SkippingIterator<T> theIterator2, BiFunction<T,T,T> theMergeFunc)
    Returns a skipping iterator that is the union of two given iterators where both the base iterators comply with the given comparator and performs the given merge operation when an element exists in both base iterators. When a duplicate is found in both operators only the result of the merge function will be included in the resulting iterator.

  - ### emptyIterator

    public static <T> PeekingSkippingIterator<T> emptyIterator()

  - ### singletonIterator

    public static <T> SkippingIterator<T> singletonIterator(T theElement, Comparator<T> theComparator)

  - ### peekingIterator

    @MustBeClosed public static <T> PeekingSkippingIterator<T> peekingIterator(SkippingIterator<T> theIterator)

  - ### appendCloseable

    public static <T> SkippingIterator<T> appendCloseable(SkippingIterator<T> iterator, AutoCloseable toClose)

  - ### copy

    public static <T extends Copyable<T>> SkippingIterator<T> copy(SkippingIterator<T> iterator)