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 combinators for classes implementing Iterator.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Iterators.FilterIterator<A>
static interface	Iterators.LookaheadIterator<A>
(package private) static class	Iterators.LookaheadIteratorImpl<A>
static class	Iterators.MultipleLookaheadIterator<T>	An iterator which allows arbitrary deep look-ahead for an underlying iterator.
static class	Iterators.Pairwise<T>	Deprecated, for removal: This API element is subject to removal in a future version. use forEachPair(java.util.Iterator<T>, java.util.function.BiConsumer<T, T>) instead.
static interface	Iterators.PushbackIterator<A>
(package private) static class	Iterators.PushbackIteratorImpl<A>
static class	Iterators.Triplewise<T>	Deprecated, for removal: This API element is subject to removal in a future version. use forEachTriple(java.util.Iterator<T>, eu.bandm.tools.util.function.TriConsumer<T, T, T>) instead.

Method Summary

Modifier and Type	Method	Description
static <E> Optional<E>	anyOf(Iterator<E> it)	Deliver an arbitrarily selected value delivered by the given iterator, or an empty Optional if no such exists.
static <E, F> Iterator<F>	bind(Function<? super E,? extends Iterator<? extends F>> fun, Iterator<E> things)	Deprecated, for removal: This API element is subject to removal in a future version. use #flatMap(Function,Iterator) instead.
static <A> Iterator<A>	cacheHasNext(Iterator<A> i)
static <A> Iterator<A>	cast(Iterator<? extends A> iterator)	Forgets a wildcard in the element type of a given iterator.
static <A, B> Iterator<B>	comprehend(Iterator<A> gen, Function<? super A,? extends Iterator<B>> fun)	Deprecated. use streams instead
static <A, B> Iterator<B>	comprehend(Iterator<A> gen, Predicate<? super A> filter, Function<? super A,? extends B> map)	Deprecated. use streams instead
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>	cons(E first, Iterator<E> rest)	Returns an iterator consisting of the given first element preceding the remaining elements of a given iterator.
static <A> Iterator<A>	drop(int n, Iterator<A> things)
static <A> void	elementwise(Consumer<? super A> sink, Iterator<A> it)	Deprecated, for removal: This API element is subject to removal in a future version. use Iterator.forEachRemaining(java.util.function.Consumer<? super E>) instead.
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)	Deliver the first value delivered by the given iterator, or an empty Optional if no such exists.
static <E, F> Iterator<F>	flatMap(Function<? super E,? extends Iterator<? extends F>> fun, Iterator<E> things)
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 <T> void	forEachPair(Iterator<T> it, @Opt Consumer<T> first, BiConsumer<T,T> pairwise, @Opt Consumer<T> last)	Apply one given code to the first item delivered by the iterator, then the code to all pairs of adjacent items, and finally the code to the very last item.
static <T> void	forEachPair(Iterator<T> it, BiConsumer<T,T> pairwise)	Apply the given code to all pairs of adjacent items delivered by the iterator, in their sequential order.
static <T> void	forEachTriple(Iterator<T> it, TriConsumer<@Opt T,@Opt T,@Opt T> consumer)	Apply the given code to all adjacent triples of items es delivered by the iterator.
static <A> Iterators.LookaheadIterator<A>	lookahead(Iterator<? extends A> things)
static <A, B> Iterator<B>	map(Function<? super A,? extends B> fun, Iterator<A> it)	Returns an iterator consisting of the results of applying the given function to the remaining elements of a given iterator.
static <A> Iterator<A>	merge(Comparator<? super A> order, boolean removeDuplicates, Iterator<? extends A> left, Iterator<? extends A> right)
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)
static <E> Iterator<E>	singleton(E value)	Returns an iterator consisting of exactly one given element.
static <A> Iterator<A>	take(int n, Iterator<A> things)
static <A> Iterator<A>	unmodifiableIterator(Iterator<A> i)

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)

Forgets a wildcard in the element type of a given iterator.

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

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.

bind

@Deprecated(forRemoval=true)
public static <E,
F> Iterator<F> bind(Function<? super E,? extends Iterator<? extends F>> fun,
 Iterator<E> things)

Deprecated, for removal: This API element is subject to removal in a future version.

use #flatMap(Function,Iterator) instead.

flatMap

@Undocumented
public static <E,
F> Iterator<F> flatMap(Function<? super E,? extends Iterator<? extends F>> fun,
 Iterator<E> things)

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.

map

public static <A,
B> Iterator<B> map(Function<? super A,? extends B> fun,
 Iterator<A> it)

Returns an iterator consisting of the results of applying the given function to the remaining elements of a given iterator. Removal requests are passed through to the underlying iterator.

comprehend

@Deprecated(since="0.0")
public static <A,
B> Iterator<B> comprehend(Iterator<A> gen,
 Predicate<? super A> filter,
 Function<? super A,? extends B> map)

Deprecated.

use streams instead

First apply filter, than map, and collect results.

comprehend

@Deprecated(since="0.0")
public static <A,
B> Iterator<B> comprehend(Iterator<A> gen,
 Function<? super A,? extends Iterator<B>> fun)

Deprecated.

use streams instead

Apply function and collect results.

unmodifiableIterator

@Undocumented
public static <A> Iterator<A> unmodifiableIterator(Iterator<A> i)

lookahead

@Undocumented
public static <A> Iterators.LookaheadIterator<A> lookahead(Iterator<? extends A> things)

pushback

@Undocumented
public static <A> Iterators.PushbackIterator<A> pushback(Iterator<? extends A> things)

merge

@Undocumented
public static <A> Iterator<A> merge(Comparator<? super A> order,
 boolean removeDuplicates,
 Iterator<? extends A> left,
 Iterator<? extends A> right)

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().

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

@Undocumented
public static <A> Iterator<A> cacheHasNext(Iterator<A> i)

drop

@Undocumented
public static <A> Iterator<A> drop(int n,
 Iterator<A> things)

take

@Undocumented
public static <A> Iterator<A> take(int n,
 Iterator<A> things)

elementwise

@Undocumented
@Deprecated(forRemoval=true)
public static <A> void elementwise(Consumer<? super A> sink,
 Iterator<A> it)

Deprecated, for removal: This API element is subject to removal in a future version.

use Iterator.forEachRemaining(java.util.function.Consumer<? super E>) instead.

forEachPair

public static <T> void forEachPair(Iterator<T> it,
 BiConsumer<T,T> pairwise)

Apply the given code to all pairs of adjacent items delivered by the iterator, in their sequential order.

forEachPair

public static <T> void forEachPair(Iterator<T> it,
 @Opt
 @Opt Consumer<T> first,
 BiConsumer<T,T> pairwise,
 @Opt
 @Opt Consumer<T> last)

Apply one given code to the first item delivered by the iterator, then the code to all pairs of adjacent items, and finally the code to the very last item.

Parameters:

first - code for the very first item. May be null for no activitiy.

pairwise - code for all adjaacent pairs, must not be null.

last - code for the very last item. May be null for no activitiy.

forEachTriple

public static <T> void forEachTriple(Iterator<T> it,
 TriConsumer<@Opt T,@Opt T,@Opt T> consumer)

Apply the given code to all adjacent triples of items es delivered by the iterator. If the iterator is completely empty, no code is called. Otherwise the schema for binding the parameters of the code e.g. from a four element list is as follows:

      null null #0
      null #0   #1
      #0   #1   #2
      #1   #2   #3
      #2   #3   null
      #3   null null
  

firstOf

public static <E> Optional<E> firstOf(Iterator<E> it)

Deliver the first value delivered by the given iterator, or an empty Optional if no such exists.

anyOf

public static <E> Optional<E> anyOf(Iterator<E> it)

Deliver an arbitrarily selected value delivered by the given iterator, or an empty Optional if no such exists.