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:

• Iterator

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>	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)	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 <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>	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 <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 underlying iterator are reflected in the result.

Removal requests are passed through to the underlying 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:

• Iterators.LookaheadIterator.lookahead()

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:

• Iterators.PushbackIterator.pushback(A)

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(int, java.util.Iterator<A>)
• Stream.skip(long)

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:

• drop(int, java.util.Iterator<A>)
• Stream.limit(long)

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