Package com.complexible.common.collect

Class SkippingIterators

  • public final class SkippingIterators
extends java.lang.Object
    Few utility methods to construct skipping iterators.
    Version:
    7.9
    Author:
    Pavel Klinov

    • Method Detail

      • forArray

        public static <T> PeekingSkippingIterator<T> forArray​(T[] theArray,
                                                      java.util.Comparator<T> theComparator)

      • forArray

        public static <T> SkippingIterator<T> forArray​(T[] theArray,
                                               int theStart,
                                               int theEnd,
                                               java.util.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,
                                                        java.util.function.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,
                                                    java.util.function.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.

      • transform

        @MustBeClosed
public static <I,​O> SkippingIterator<O> transform​(SkippingIterator<I> theIterator,
                                                        java.util.function.Function<I,​O> theFunction,
                                                        java.util.function.Function<O,​I> theInverseFunction,
                                                        java.util.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,
                                           java.util.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,
                                             java.util.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​(java.util.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> java.util.Comparator<T> allEqual()

      • union

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

      • union

        public static <T> SkippingIterator<T> union​(java.util.Comparator<T> theComparator,
                                            SkippingIterator<T> theIterator1,
                                            SkippingIterator<T> theIterator2,
                                            java.util.function.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.

      • singletonIterator

        public static <T> SkippingIterator<T> singletonIterator​(T theElement,
                                                        java.util.Comparator<T> theComparator)