Package eu.bandm.tools.util.java

Class Iterators

java.lang.Object
eu.bandm.tools.util.java.Iterators
public final class Iterators extends Object
Library of constants and operations for working with iterators.
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    Iterators.FilterIterator<A>
    An iterator that passes on only selected elements.
    static interface 
    Iterators.LookaheadIterator<A>
    Iterators that can look one element ahead.
    static interface 
    Iterators.MultipleLookaheadIterator<E>
    Iterators which allow arbitrary deep look-ahead.
    static interface 
    Iterators.PushbackIterator<A>
    Iterators that can push an element back into the sequence.

  • Method Summary

    Modifier and Type
    Method
    Description
    static <E> Optional<E>
    anyOf(Iterator<E> it)
    Returns an arbitrary remaining element, if available.
    static <A> Iterator<A>
    cacheHasNext(Iterator<A> i)
    Returns an iterator consisting of the same elements as the given iterator, but caching redundant queries.
    static <A> Iterator<A>
    cast(Iterator<? extends A> iterator)
    Adjusts the element type of a given iterator.
    static <E> Iterator<E>
    concat(Iterator<? extends E> first, Iterator<? extends E> second)
    Returns an iterator consisting of the combined elements of two given iterators in order.
    static <E> Iterator<E>
    conditional(boolean cond, E elem)
    Returns an iterator that produces the given element or nothing, depending on a condition.
    static <E> Iterator<E>
    conditional(boolean cond, Supplier<? extends E> elem)
    Returns an iterator that produces one element computed on the fly or nothing, depending on a condition.
    static <E> Iterator<E>
    conditional(boolean cond, Iterator<E> things)
    Returns an iterator that produces the given elements or nothing, depending on a condition.
    static <E> Iterator<E>
    cons(E first, Iterator<E> rest)
    Returns an iterator consisting of the given first element preceding the remaining elements of a given iterator.
    static <V, L> Iterator<L>
    depthFirst(V root, Function<? super V,? extends Iterator<? extends L>> labels, Function<? super V,? extends Iterator<? extends V>> branches)
    Returns an iterator that produces the labels of a search tree by depth-first traversal.
    static <A> Iterator<A>
    drop(int n, Iterator<A> things)
    Returns a view on an iterator that has the same remaining elements, except the first ones.
    static <E> Iterator<E>
    empty()
    Returns an iterator consisting of no elements.
    static <E> Iterator<E>
    filter(Predicate<? super E> pred, Iterator<E> i)
    Returns an iterator consisting of the remaining elements of a given iterator that match the given predicate.
    static <A, B> Iterator<A>
    filterWithConstraint(BiPredicate<? super A,? super B> rel, Iterator<A> things, Iterator<B> constraints)
    Returns an iterator consisting of the elements of another iterator that match a constraint from a parallel iterator.
    static <E> Optional<E>
    firstOf(Iterator<E> it)
    Returns the first remaining element, if available.
    static <E, F> Iterator<F>
    flatMap(Function<? super E,? extends Iterator<? extends F>> fun, Iterator<E> things)
    Returns a concatenation of subsequences computed with a function.
    static <E> Iterator<E>
    flatten(Iterator<? extends Iterator<? extends E>> iterators)
    Returns an iterator consisting of the combined elements of all iterators returned by a given iterator in order.
    static <E> Iterator<E>
    forever(Supplier<? extends E> things)
    Returns an iterator that produces unboundedly many elements computed on demand.
    static <S> Iterator<S>
    iterate(S seed, Predicate<? super S> hasNext, UnaryOperator<S> next)
    Returns an iterator that produces elements by iterative application of the given step function to an initial element, conditioned on satisfying the given predicate.
    static <E, S> Iterator<E>
    iterate(S seed, Predicate<? super S> hasNext, UnaryOperator<S> next, Function<? super S,? extends E> view)
    Returns an iterator that produces elements by iterative application of the given step function to an initial state, conditioned on satisfying the given predicate, computing elements from states with the given view function.
    static <A> Iterators.LookaheadIterator<A>
    lookahead(Iterator<? extends A> things)
    Returns an view with lookahead capability for a given iterator.
    static <A, B> Iterator<B>
    map(Function<? super A,? extends B> fun, Iterator<A> it)
    Returns a view on an iterator that has all elements transformed by a given function.
    static <A> Iterator<A>
    merge(Comparator<? super A> order, boolean removeDuplicates, Iterator<? extends A> left, Iterator<? extends A> right)
    Returns the merged combination of two ordered sequences.
    static <E> Iterators.MultipleLookaheadIterator<E>
    multipleLookahead(E... elems)
    Returns an iterator with deep lookahead over the given elements.
    static <E> Iterators.MultipleLookaheadIterator<E>
    multipleLookahead(Iterable<? extends E> elems)
    Returns an iterator with deep lookahead over the given elements.
    static <E> Iterators.MultipleLookaheadIterator<E>
    multipleLookahead(Iterator<? extends E> it)
    Returns an iterator with deep lookahead over the given elements.
    static <E> Iterator<E>
    of(E... things)
    Returns an iterator consisting of exactly the given elements.
    static <A> Iterators.PushbackIterator<A>
    pushback(Iterator<? extends A> things)
    Returns an view with pushback capability for a given iterator.
    static <E> Iterator<E>
    range(int start, int end, IntFunction<? extends E> gen)
    Returns an iterator that produces elements computed from the given integer interval in ascending order.
    static <E> Iterator<E>
    repeat(E value, int times)
    Returns an iterator consisting of one value repeated several times.
    static <E> Iterator<E>
    singleton(E value)
    Returns an iterator consisting of exactly one given element.
    static <E> Iterator<E>
    singleton(Supplier<? extends E> elem)
    Returns an iterator consisting of exactly one given element computed on demand.
    static <A> Iterator<A>
    take(int n, Iterator<A> things)
    Returns a view on an iterator that has the same elements, up to a given length.
    static <A> Iterator<A>
    unmodifiableIterator(Iterator<A> i)
    Returns an unmodifiable view on an iterator.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • cast

      public static <A> Iterator<A> cast(Iterator<? extends A> iterator)
      Adjusts the element type of a given iterator.
      Type Parameters:
      A - the desired element type
      Parameters:
      iterator - an iterator
      Returns:
      the same iterator

    • empty

      public static <E> Iterator<E> empty()
      Returns an iterator consisting of no elements.
      Type Parameters:
      E - the type of elements returned by the returned iterator
      Returns:
      an iterator that has no elements

    • singleton

      public static <E> Iterator<E> singleton(E value)
      Returns an iterator consisting of exactly one given element. The element is not removable.
      Type Parameters:
      E - the type of elements returned by the returned iterator
      Parameters:
      value - the single element of the returned iterator
      Returns:
      an iterator that has exactly the given element

    • repeat

      public static <E> Iterator<E> repeat(E value, int times)
      Returns an iterator consisting of one value repeated several times.
      Type Parameters:
      E - the element type
      Parameters:
      value - the value
      times - the number of repetitions
      Returns:
      an iterator consisting of times repetitions of value
      Throws:
      IllegalArgumentException - if times is negative

    • of

      @SafeVarargs public static <E> Iterator<E> of(E... things)
      Returns an iterator consisting of exactly the given elements. Elements are not removable.
      Type Parameters:
      E - the type of elements returned by the returned iterator
      Parameters:
      things - the elements of the returned iterator
      Returns:
      an iterator that has exactly the given elements

    • cons

      public static <E> Iterator<E> cons(E first, Iterator<E> rest)
      Returns an iterator consisting of the given first element preceding the remaining elements of a given iterator. The first element is not removable. Further removal requests are passed through to the underlying iterator.
      Type Parameters:
      E - the type of elements returned by the returned iterator
      Parameters:
      first - the first element
      rest - the iterator of the succeeding elements
      Returns:
      an iterator that returns the first element followed by the remaining elements of rest
      Throws:
      NullPointerException - if rest == null

    • concat

      public static <E> Iterator<E> concat(Iterator<? extends E> first, Iterator<? extends E> second)
      Returns an iterator consisting of the combined elements of two given iterators in order. Removal requests are passed through to the underlying iterators.
      Type Parameters:
      E - the type of elements returned by the returned iterator
      Parameters:
      first - the first iterator to consult for elements
      second - the second iterator to consult for elements
      Returns:
      an iterator that returns all remaining elements of first, followed by all remaining elements of second
      Throws:
      NullPointerException - if first == null or second == null

    • flatten

      public static <E> Iterator<E> flatten(Iterator<? extends Iterator<? extends E>> iterators)
      Returns an iterator consisting of the combined elements of all iterators returned by a given iterator in order. Removal requests are passed through to the underlying iterators.
      Type Parameters:
      E - the type of elements returned by the returned iterator
      Parameters:
      iterators - the iterators to be combined
      Returns:
      the combined interator
      Throws:
      NullPointerException - if iterators == null or one in the list is ==null.

    • flatMap

      public static <E, F> Iterator<F> flatMap(Function<? super E,? extends Iterator<? extends F>> fun, Iterator<E> things)
      Returns a concatenation of subsequences computed with a function.
      Type Parameters:
      E - the source element type
      F - the target element type
      Parameters:
      fun - a function that computes a subsequence of target elements from a single source element
      things - the source elements
      Returns:
      the concatenation of the subsequences obtained by applying fun to all source elements in order

    • filter

      public static <E> Iterator<E> filter(Predicate<? super E> pred, Iterator<E> i)
      Returns an iterator consisting of the remaining elements of a given iterator that match the given predicate.

      Removal requests are passed through to the underlying iterator.

      Type Parameters:
      E - the element type
      Parameters:
      pred - a predicate specifying which elements to include
      i - an iterator
      Returns:
      an iterator consisting of those elements of i for which pred returns true
      Throws:
      NullPointerException - if pred or i is null

    • map

      public static <A, B> Iterator<B> map(Function<? super A,? extends B> fun, Iterator<A> it)
      Returns a view on an iterator that has all elements transformed by a given function.

      Changes to the backing iterator are reflected in the result.

      Removal requests are delegated to the backing iterator.

      Type Parameters:
      A - the source element type
      B - the target element type
      Parameters:
      fun - a transformer function
      it - some elements
      Returns:
      an iterator where each element is computed on the fly by applying fun to the corresponding element of it
      Throws:
      NullPointerException - if fun or it is null

    • unmodifiableIterator

      public static <A> Iterator<A> unmodifiableIterator(Iterator<A> i)
      Returns an unmodifiable view on an iterator.

      Changes to the underlying iterator are reflected in the result.

      Type Parameters:
      A - the element type
      Parameters:
      i - an iterator
      Returns:
      an iterator consisting of the same elements as i, but not supporting the remove operation

    • multipleLookahead

      public static <E> Iterators.MultipleLookaheadIterator<E> multipleLookahead(Iterator<? extends E> it)
      Returns an iterator with deep lookahead over the given elements.
      Type Parameters:
      E - the element type
      Parameters:
      it - the remaining elements
      Returns:
      an iterator with deep lookahead over the given elements

    • multipleLookahead

      public static <E> Iterators.MultipleLookaheadIterator<E> multipleLookahead(Iterable<? extends E> elems)
      Returns an iterator with deep lookahead over the given elements.
      Type Parameters:
      E - the element type
      Parameters:
      elems - the elements
      Returns:
      an iterator with deep lookahead over the given elements

    • multipleLookahead

      @SafeVarargs public static <E> Iterators.MultipleLookaheadIterator<E> multipleLookahead(E... elems)
      Returns an iterator with deep lookahead over the given elements.
      Type Parameters:
      E - the element type
      Parameters:
      elems - the elements
      Returns:
      an iterator with deep lookahead over the given elements

    • lookahead

      public static <A> Iterators.LookaheadIterator<A> lookahead(Iterator<? extends A> things)
      Returns an view with lookahead capability for a given iterator.

      Changes to the underlying iterator are reflected in the result.

      Removal requests are passed through to the underlying iterator.

      Type Parameters:
      A - the element type
      Parameters:
      things - the iterator
      Returns:
      an iterator consisting of the same elements as things, but with lookahead capability
      See Also:

    • pushback

      public static <A> Iterators.PushbackIterator<A> pushback(Iterator<? extends A> things)
      Returns an view with pushback capability for a given iterator.

      Changes to the underlying iterator are reflected in the result.

      Removal requests are passed through to the underlying iterator.

      Type Parameters:
      A - the element type
      Parameters:
      things - the iterator
      Returns:
      an iterator consisting of the same elements as things, but with pushback capability
      See Also:

    • merge

      public static <A> Iterator<A> merge(Comparator<? super A> order, boolean removeDuplicates, Iterator<? extends A> left, Iterator<? extends A> right)
      Returns the merged combination of two ordered sequences.
      Type Parameters:
      A - the element type
      Parameters:
      order - the ordering of both inputs and the result
      removeDuplicates - duplicates are removed if true, or retained if false
      left - the first ordered sequence of elements
      right - the second ordered sequence of elements
      Returns:
      an ordered sequence that contains the elements of both inputs, possibly without duplicates
      Throws:
      NullPointerException - if order, left or right is null

    • filterWithConstraint

      public static <A, B> Iterator<A> filterWithConstraint(BiPredicate<? super A,? super B> rel, Iterator<A> things, Iterator<B> constraints)
      Returns an iterator consisting of the elements of another iterator that match a constraint from a parallel iterator.

      The elements of the given iterators things and constraints are consumed in parallel, one element at a time. If one or both of them run out of elements, so does the resulting iterator.

      The pairs of successive elements are filtered through the given matching relation rel. If a pair is accepted, then the corresponding element (from things) appears in the resulting iterator; the matched constraint is omitted. If a pair is not accepted, then it is omitted altogether.

      The resulting iterator does not support the operation Iterator#remove().

      Type Parameters:
      A - the type of elements
      B - the type of constraints
      Parameters:
      rel - the matching relation between elements and constraints
      things - the iterator of elements
      constraints - the iterator of constraints
      Returns:
      an iterator that passes through elements that match their respective contstraint

    • cacheHasNext

      public static <A> Iterator<A> cacheHasNext(Iterator<A> i)
      Returns an iterator consisting of the same elements as the given iterator, but caching redundant queries.

      This is useful if a given iterator implementation performs an expensive computation on Iterator.hasNext().

      Type Parameters:
      A - the element type
      Parameters:
      i - an iterator
      Returns:
      an iterator consisting of the same elements, but which caches the result of hasNext between calls to next

    • drop

      public static <A> Iterator<A> drop(int n, Iterator<A> things)
      Returns a view on an iterator that has the same remaining elements, except the first ones.

      Changes to the underlying iterator are reflected in the result.

      Removal requests are passed through to the underlying iterator.

      If more elements were to be dropped than available, the result is simply empty.

      Type Parameters:
      A - the element type
      Parameters:
      n - the number of elements to discard from the start of the iteration
      things - some elements
      Returns:
      an iterator that has the same elements as things, except for n many that are discarded at the start of the iteration
      Throws:
      IllegalArgumentException - if n is negative
      NullPointerException - if things is null
      See Also:

    • take

      public static <A> Iterator<A> take(int n, Iterator<A> things)
      Returns a view on an iterator that has the same elements, up to a given length.

      Changes to the underlying iterable are reflected in the result.

      Removal requests are passed through to the underlying iterator.

      If more elements were to be retained than available, the result is simply equivalent to the input.

      Type Parameters:
      A - the element type
      Parameters:
      n - the number of elements to retain from the iteration
      things - some elements
      Returns:
      an iterator that has the same first elements as things, but ends after n elements
      Throws:
      IllegalArgumentException - if n is negative
      NullPointerException - if things is null
      See Also:

    • firstOf

      public static <E> Optional<E> firstOf(Iterator<E> it)
      Returns the first remaining element, if available.
      Type Parameters:
      E - the element type
      Parameters:
      it - an iterator
      Returns:
      an optional value that contains the first remaining (next) element if there is one, or the empty optional value if there are no more elements

    • anyOf

      public static <E> Optional<E> anyOf(Iterator<E> it)
      Returns an arbitrary remaining element, if available.
      Type Parameters:
      E - the element type
      Parameters:
      it - an iterator
      Returns:
      an optional value that contains an arbitrarily chosen element if there is one, or the empty optional value if there are no elements

    • iterate

      public static <E, S> Iterator<E> iterate(S seed, Predicate<? super S> hasNext, UnaryOperator<S> next, Function<? super S,? extends E> view)
      Returns an iterator that produces elements by iterative application of the given step function to an initial state, conditioned on satisfying the given predicate, computing elements from states with the given view function. Iteration terminates as soon as the hasNext predicate returns false.

      The iterator returned by this method should produce the same sequence of elements as the corresponding for-loop: 

           for (T state = seed; hasNext.test(state); state = next.apply(state)) {
         final E elem = view.apply(state);
         ...
     }
      Type Parameters:
      E - the type of elements
      S - the type of states
      Parameters:
      seed - the initial state
      hasNext - a predicate to determine before which state iteration should terminate
      next - a function to produce the next state
      view - a function to compute an element from a state
      Returns:
      an iterator that produces elements iteratively
      Throws:
      NullPointerException - if codeNext, next or view is null
      Since:
      1.2
      See Also:

    • iterate

      public static <S> Iterator<S> iterate(S seed, Predicate<? super S> hasNext, UnaryOperator<S> next)
      Returns an iterator that produces elements by iterative application of the given step function to an initial element, conditioned on satisfying the given predicate. Iteration terminates as soon as the hasNext predicate returns false.

      The iterator returned by this method should produce the same sequence of elements as the corresponding for-loop: 

           for (T elem = seed; hasNext.test(elem); elem = next.apply(elem)) {
         ...
     }
      Type Parameters:
      S - the type of elements
      Parameters:
      seed - the initial element
      hasNext - a predicate to determine before which element iteration should terminate
      next - a function to produce the next element
      Returns:
      an iterator that produces elements iteratively
      Throws:
      NullPointerException - if codeNext or next is null
      Since:
      1.2
      See Also:

    • depthFirst

      public static <V, L> Iterator<L> depthFirst(V root, Function<? super V,? extends Iterator<? extends L>> labels, Function<? super V,? extends Iterator<? extends V>> branches)
      Returns an iterator that produces the labels of a search tree by depth-first traversal.
      Type Parameters:
      V - the type of search tree nodes
      L - the type of labels
      Parameters:
      root - the root node of the search tree
      labels - a function to enumerate the labels of a node
      branches - a function to enumerate the children of a node
      Returns:
      an enumeration of all labels encountered in depth-first search order
      Throws:
      NullPointerException - if labels or branches is null
      Since:
      1.2

    • range

      public static <E> Iterator<E> range(int start, int end, IntFunction<? extends E> gen)
      Returns an iterator that produces elements computed from the given integer interval in ascending order.

      The iterator returned by this method should produce the same sequence of elements as the corresponding for-loop: 

           for (int i = start; i < end; i++)
         final E elem = gen.apply(i);
         ...
     }
      Type Parameters:
      E - the type of elements
      Parameters:
      start - the start of the interval (inclusive)
      end - the end of the interval (exclusive)
      gen - a function to produce the element for an integer index
      Returns:
      an iterator that produces elements computed from the interval [start, end)
      Throws:
      NullPointerException - if gen is null
      Since:
      1.2

    • singleton

      public static <E> Iterator<E> singleton(Supplier<? extends E> elem)
      Returns an iterator consisting of exactly one given element computed on demand. The element is not removable.
      Type Parameters:
      E - the type of elements returned by the returned iterator
      Parameters:
      elem - a supplier that computes the single element of the returned iterator on demand
      Returns:
      an iterator that has exactly the computed element
      Throws:
      NullPointerException - if elem is null
      Since:
      1.2

    • conditional

      public static <E> Iterator<E> conditional(boolean cond, E elem)
      Returns an iterator that produces the given element or nothing, depending on a condition.
      Type Parameters:
      E - the type of elements
      Parameters:
      cond - a condition
      elem - the element to produce conditionally
      Returns:
      an iterator that produces just elem if cond is true; the empty iterator otherwise.
      Since:
      1.2
      See Also:

    • conditional

      public static <E> Iterator<E> conditional(boolean cond, Supplier<? extends E> elem)
      Returns an iterator that produces one element computed on the fly or nothing, depending on a condition.

      The given supplier is only used if the condition is true.

      Type Parameters:
      E - the type of elements
      Parameters:
      cond - a condition
      elem - a supplier for the element to produce conditionally
      Returns:
      an iterator that produces just elem.get() if cond is true; the empty iterator otherwise.
      Throws:
      NullPointerException - if elem is null
      Since:
      1.2
      See Also:

    • conditional

      public static <E> Iterator<E> conditional(boolean cond, Iterator<E> things)
      Returns an iterator that produces the given elements or nothing, depending on a condition.

      The given iterator is only used if the condition is true.

      This method is equivalent to filter(Predicate<? super E>, Iterator<E>) with a constant predicate, but returns a more efficient iterator.

      Type Parameters:
      E - the type of elements
      Parameters:
      cond - a condition
      things - an iterator for the elements to produce conditionally
      Returns:
      an iterator that forwards the elements of things if cond is true; the empty iterator otherwise.
      Throws:
      NullPointerException - if things is null
      Since:
      1.2
      See Also:

    • forever

      public static <E> Iterator<E> forever(Supplier<? extends E> things)
      Returns an iterator that produces unboundedly many elements computed on demand.

      The hasNext method of the returned iterator always returns true. The next method of the returned iterator does not actively throw NoSuchElementException, but it may throw any exception caused by the underlying supplier.

      The resulting iterator is not suitable for exhaustive consumption of all elements; such a loop does not terminate. Clients must stop consuming more elements by themselves, or iteration must be limited by other means.

      Type Parameters:
      E - the type of elements returned by the returned iterator
      Parameters:
      things - a supplier that computes each element of the returned iterator on demand
      Returns:
      an iterator that produces the computed elements
      Throws:
      NullPointerException - if things is null
      Since:
      1.2
      See Also: