com.github.robtimus.util.iterator

Class IteratorUtils

java.lang.Object

com.github.robtimus.util.iterator.IteratorUtils

public final class IteratorUtils
extends Object

A utility class for Iterators.

Author:

Rob Spoor

Method Summary

Modifier and Type	Method and Description
static <E> boolean	allMatch(Iterator<E> iterator, Predicate<? super E> predicate) Returns whether or not all elements of an iterator match a specific predicate.
static <E> boolean	anyMatch(Iterator<E> iterator, Predicate<? super E> predicate) Returns whether or not at least one element of an iterator matches a specific predicate.
static <E> Iterator<E>	chainIterables(Iterable<? extends E>... iterables) Returns an iterator that contains the elements of several other iterables.
static <E> Iterator<E>	chainIterables(Iterable<? extends Iterable<? extends E>> iterables) Returns an iterator that contains the elements of several other iterables.
static <E> Iterator<E>	chainIterators(Iterable<? extends Iterator<? extends E>> iterators) Returns an iterator that contains the elements of several other iterators.
static <E> Iterator<E>	chainIterators(Iterator<? extends E>... iterators) Returns an iterator that contains the elements of several other iterators.
static <E,R,A> R	collect(Iterator<E> iterator, Collector<? super E,A,R> collector) Performs a reduction on the elements of an iterator.
static <E,R> R	collect(Iterator<E> iterator, Supplier<R> supplier, BiConsumer<R,? super E> accumulator) Performs a reduction on the elements of an iterator.
static long	count(Iterator<?> iterator) Returns the number of elements of an iterator.
static <E> Iterator<E>	distinct(Iterator<E> iterator) Returns an iterator that returns the distinct elements of another iterator (according to Object.equals(Object)).
static <E> Iterator<E>	dropWhile(Iterator<E> iterator, Predicate<? super E> predicate) Returns an iterator that discards elements of another iterator until an element does not match a specific predicate.
static <E> Iterator<E>	filter(Iterator<E> iterator, Predicate<? super E> predicate) Returns an iterator that filters out elements of another iterator.
static <E> Optional<E>	findFirst(Iterator<E> iterator) Returns the first element of an iterator.
static <E,R> Iterator<R>	flatMap(Iterator<E> iterator, Function<? super E,? extends Iterator<? extends R>> mapper) Returns an iterator that replaces the elements of another iterator with the elements of a mapped iterator produced by applying a function to each element.
static <E> Iterator<E>	iterate(E seed, Predicate<? super E> hasNext, UnaryOperator<E> next) Returns an iterator for which the elements are produced by iterative application of a function.
static <E> Iterator<E>	limit(Iterator<E> iterator, long maxSize) Returns an iterator that truncates another iterator.
static <E,R> Iterator<R>	map(Iterator<E> iterator, Function<? super E,? extends R> mapper) Returns an iterator that applies a function to the elements of another iterator.
static <E> Optional<E>	max(Iterator<E> iterator, Comparator<? super E> comparator) Returns the maximum element of an iterator according to a specific comparator.
static <E> Optional<E>	min(Iterator<E> iterator, Comparator<? super E> comparator) Returns the minimum element of an iterator according to a specific comparator.
static <E> boolean	noneMatch(Iterator<E> iterator, Predicate<? super E> predicate) Returns whether or not no element of an iterator matches a specific predicate.
static <E> Iterator<E>	peek(Iterator<E> iterator, Consumer<? super E> action) Returns an iterator that performs an additional action for each element of another iterator.
static <E> Optional<E>	reduce(Iterator<E> iterator, BinaryOperator<E> accumulator) Performs a reduction on the elements of an iterator.
static <E> E	reduce(Iterator<E> iterator, E identity, BinaryOperator<E> accumulator) Performs a reduction on the elements of an iterator.
static <E,U> U	reduce(Iterator<E> iterator, U identity, BiFunction<U,? super E,U> accumulator) Performs a reduction on the elements of an iterator.
static <E> Iterator<E>	singletonIterator(E element) Returns an iterator that returns a single element.
static <E> Iterator<E>	skip(Iterator<E> iterator, long n) Returns an iterator that discards a number of elements at the start of another iterator.
static <E> Iterator<E>	takeWhile(Iterator<E> iterator, Predicate<? super E> predicate) Returns an iterator that discards elements of another iterator once an element matches a specific predicate.
static <E> Stream<E>	toStream(Iterator<E> iterator) Returns a stream based on an iterator.
static <E> Stream<E>	toStream(Iterator<E> iterator, int characteristics) Returns a stream based on an iterator.
static <E> Stream<E>	toStream(Iterator<E> iterator, long size) Returns a stream based on an iterator.
static <E> Stream<E>	toStream(Iterator<E> iterator, long size, int characteristics) Returns a stream based on an iterator.
static <E> Iterator<E>	unmodifiableIterator(Iterator<E> iterator) Returns an unmodifiable view of an iterator.

Methods inherited from class java.lang.Object

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

Method Detail

singletonIterator

public static <E> Iterator<E> singletonIterator(E element)

Returns an iterator that returns a single element. This method is like using the iterator of Collections.singleton(Object).

API Note:

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

Type Parameters:

E - The element type.

Parameters:

element - The element to return.

Returns:

An iterator that returns the given element.

unmodifiableIterator

public static <E> Iterator<E> unmodifiableIterator(Iterator<E> iterator)

Returns an unmodifiable view of an iterator. Calling Iterator.remove() will result in an UnsupportedOperationException.

Type Parameters:

E - The element type.

Parameters:

iterator - The iterator to return an unmodifiable view of.

Returns:

An unmodifiable view of the given iterator.

Throws:

NullPointerException - If the given iterator is null.

filter

public static <E> Iterator<E> filter(Iterator<E> iterator,
                                     Predicate<? super E> predicate)

Returns an iterator that filters out elements of another iterator.

API Note:

The returned iterator supports the Iterator.remove() operation if the given iterator does.

Type Parameters:

E - The element type.

Parameters:

iterator - The iterator for which to filter out elements.

predicate - A predicate that determines whether or not elements should be included.

Returns:

An iterator that filters out elements of the given iterator.

Throws:

NullPointerException - If the given iterator or predicate is null.

See Also:

Stream.filter(Predicate)

map

public static <E,R> Iterator<R> map(Iterator<E> iterator,
                                    Function<? super E,? extends R> mapper)

Returns an iterator that applies a function to the elements of another iterator.

API Note:

The returned iterator supports the Iterator.remove() operation if the given iterator does.

Type Parameters:

E - The element type of the input iterator.

R - The element type of the resulting iterator.

Parameters:

iterator - The iterator with the elements to apply the function to.

mapper - The function to apply.

Returns:

An iterator that applies the given function to the elements of the given iterator.

Throws:

NullPointerException - If the given iterator or function is null.

See Also:

Stream.map(Function)

flatMap

public static <E,R> Iterator<R> flatMap(Iterator<E> iterator,
                                        Function<? super E,? extends Iterator<? extends R>> mapper)

Returns an iterator that replaces the elements of another iterator with the elements of a mapped iterator produced by applying a function to each element.

API Note:

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

Type Parameters:

E - The element type of the input iterator.

R - The element type of the resulting iterator.

Parameters:

iterator - The iterator with the elements to apply the function to.

mapper - The function to apply.

Returns:

An iterator that applies the given function to the elements of the given iterator.

Throws:

NullPointerException - If the given iterator or function is null.

See Also:

Stream.flatMap(Function)

distinct

public static <E> Iterator<E> distinct(Iterator<E> iterator)

Returns an iterator that returns the distinct elements of another iterator (according to Object.equals(Object)).

API Note:

The returned iterator supports the Iterator.remove() operation if the given iterator does. If elements occur more than once in the original iterator, only the first occurrence will be returned by the returned iterator, and therefore only the first occurrence can be removed.

Type Parameters:

E - The element type.

Parameters:

iterator - The element to return distinct elements of.

Returns:

An iterator that returns the distinct elements of the given iterator.

Throws:

NullPointerException - If the given iterator is null.

See Also:

Stream.distinct()

peek

public static <E> Iterator<E> peek(Iterator<E> iterator,
                                   Consumer<? super E> action)

Returns an iterator that performs an additional action for each element of another iterator.

API Note:

The returned iterator supports the Iterator.remove() operation if the given iterator does.

Type Parameters:

E - The element type.

Parameters:

iterator - The iterator with the element to perform an action for.

action - The action to perform.

Returns:

An iterator that performs the given action for each element of the given iterator.

Throws:

NullPointerException - If the given iterator or action is null.

See Also:

Stream.peek(Consumer)

limit

public static <E> Iterator<E> limit(Iterator<E> iterator,
                                    long maxSize)

Returns an iterator that truncates another iterator.

API Note:

The returned iterator supports the Iterator.remove() operation if the given iterator does. Discarded elements will not be returned by the returned iterator, and therefore cannot be removed.

Type Parameters:

E - The element type.

Parameters:

iterator - The iterator to truncate.

maxSize - The maximum number of elements in the returned iterator.

Returns:

An iterator that truncates the given iterator.

Throws:

NullPointerException - If the given iterator is null.

IllegalArgumentException - If the given maximum number of elements is negative.

See Also:

Stream.limit(long)

skip

public static <E> Iterator<E> skip(Iterator<E> iterator,
                                   long n)

Returns an iterator that discards a number of elements at the start of another iterator.

API Note:

The returned iterator supports the Iterator.remove() operation if the given iterator does. Discarded elements will not be returned by the returned iterator, and therefore cannot be removed.

Type Parameters:

E - The element type.

Parameters:

iterator - The iterator for which to discard the first elements.

n - The number of elements to discard.

Returns:

An iterator that discards the first n elements of the given iterator.

Throws:

NullPointerException - If the given iterator is null.

IllegalArgumentException - If the given number of elements is negative.

See Also:

Stream.skip(long)

takeWhile

public static <E> Iterator<E> takeWhile(Iterator<E> iterator,
                                        Predicate<? super E> predicate)

Returns an iterator that discards elements of another iterator once an element matches a specific predicate.

API Note:

The returned iterator supports the Iterator.remove() operation if the given iterator does. Discarded elements will not be returned by the returned iterator, and therefore cannot be removed.

Type Parameters:

E - The element type.

Parameters:

iterator - The iterator for which to discard elements.

predicate - The predicate that determines when elements are discarded.

Returns:

An iterator that discards elements of the given iterator once an element matches the given predicate.

Throws:

NullPointerException - If the given iterator or predicate is null.

dropWhile

public static <E> Iterator<E> dropWhile(Iterator<E> iterator,
                                        Predicate<? super E> predicate)

Returns an iterator that discards elements of another iterator until an element does not match a specific predicate.

API Note:

The returned iterator supports the Iterator.remove() operation if the given iterator does. Discarded elements will not be returned by the returned iterator, and therefore cannot be removed.

Type Parameters:

E - The element type.

Parameters:

iterator - The iterator for which to discard elements.

predicate - The predicate that determines until when elements are discarded.

Returns:

An iterator that discards elements of the given iterator until an element does not match the given predicate.

Throws:

NullPointerException - If the given iterator or predicate is null.

reduce

public static <E> E reduce(Iterator<E> iterator,
                           E identity,
                           BinaryOperator<E> accumulator)

Performs a reduction on the elements of an iterator.

Type Parameters:

E - The element type.

Parameters:

iterator - The iterator with the elements to perform a reduction on.

identity - The identity value for the accumulating function.

accumulator - A function for combining two values.

Returns:

The result of the reduction.

Throws:

NullPointerException - If the given iterator or accumulator function is null.

See Also:

Stream.reduce(Object, BinaryOperator)

reduce

public static <E> Optional<E> reduce(Iterator<E> iterator,
                                     BinaryOperator<E> accumulator)

Performs a reduction on the elements of an iterator.

Type Parameters:

E - The element type.

Parameters:

iterator - The iterator with the elements to perform a reduction on.

accumulator - A function for combining two values.

Returns:

An Optional describing the result of the reduction, or Optional.empty() if the given iterator has no elements.

Throws:

NullPointerException - If the given iterator or accumulator function or the result of the reduction is null.

See Also:

Stream.reduce(BinaryOperator)

reduce

public static <E,U> U reduce(Iterator<E> iterator,
                             U identity,
                             BiFunction<U,? super E,U> accumulator)

Performs a reduction on the elements of an iterator.

Type Parameters:

E - The element type of the input iterator.

U - The element type of the resulting iterator.

Parameters:

iterator - The iterator with the elements to perform a reduction on.

identity - The identity value for the accumulating function.

accumulator - A function for combining two values.

Returns:

The result of the reduction.

Throws:

NullPointerException - If the given iterator or accumulator function is null.

See Also:

Stream.reduce(Object, BiFunction, BinaryOperator)

collect

public static <E,R> R collect(Iterator<E> iterator,
                              Supplier<R> supplier,
                              BiConsumer<R,? super E> accumulator)

Performs a reduction on the elements of an iterator.

Type Parameters:

E - The element type of the input iterator.

R - The element type of the resulting iterator.

Parameters:

iterator - The iterator with the elements to perform a reduction on.

supplier - A supplier for mutable result containers.

accumulator - A function that folds elements into a result container.

Returns:

The result of the reduction.

Throws:

NullPointerException - If the given iterator, supplier or accumulator function is null.

See Also:

Stream.collect(Supplier, BiConsumer, BiConsumer)

collect

public static <E,R,A> R collect(Iterator<E> iterator,
                                Collector<? super E,A,R> collector)

Performs a reduction on the elements of an iterator.

Type Parameters:

E - The element type of the input iterator.

R - The element type of the resulting iterator.

A - The intermediate accumulation type of the collector.

Parameters:

iterator - The iterator with the elements to perform a reduction on.

collector - The collector to use for the reduction.

Returns:

The result of the reduction.

Throws:

NullPointerException - If the given iterator or collector is null.

See Also:

Stream.collect(Collector)

min

public static <E> Optional<E> min(Iterator<E> iterator,
                                  Comparator<? super E> comparator)

Returns the minimum element of an iterator according to a specific comparator.

Type Parameters:

E - The element type.

Parameters:

iterator - The iterator to return the minimum element of.

comparator - The comparator to use for comparing elements.

Returns:

An Optional describing the minimum element, or Optional.empty() if the given iterator has no elements.

Throws:

NullPointerException - If the given iterator or comparator is null.

See Also:

Stream.min(Comparator)

max

public static <E> Optional<E> max(Iterator<E> iterator,
                                  Comparator<? super E> comparator)

Returns the maximum element of an iterator according to a specific comparator.

Type Parameters:

E - The element type.

Parameters:

iterator - The iterator to return the maximum element of.

comparator - The comparator to use for comparing elements.

Returns:

An Optional describing the maximum element, or Optional.empty() if the given iterator has no elements.

Throws:

NullPointerException - If the given iterator or comparator is null.

See Also:

Stream.max(Comparator)

count

public static long count(Iterator<?> iterator)

Returns the number of elements of an iterator.

Parameters:

iterator - The iterator to return the number of elements of.

Returns:

The number of elements of the given iterator.

Throws:

NullPointerException - If the given iterator is null.

See Also:

Stream.count()

anyMatch

public static <E> boolean anyMatch(Iterator<E> iterator,
                                   Predicate<? super E> predicate)

Returns whether or not at least one element of an iterator matches a specific predicate.

Type Parameters:

E - The element type.

Parameters:

iterator - The iterator with the elements to match.

predicate - The predicate to apply to elements of the given iterator.

Returns:

true if at least one element of the given iterator matches the given predicate, or false otherwise.

Throws:

NullPointerException - If the given iterator or predicate is null.

See Also:

Stream.anyMatch(Predicate)

allMatch

public static <E> boolean allMatch(Iterator<E> iterator,
                                   Predicate<? super E> predicate)

Returns whether or not all elements of an iterator match a specific predicate.

Type Parameters:

E - The element type.

Parameters:

iterator - The iterator with the elements to match.

predicate - The predicate to apply to elements of the given iterator.

Returns:

true if all elements of the given iterator match the given predicate, or false otherwise.

Throws:

NullPointerException - If the given iterator or predicate is null.

See Also:

Stream.allMatch(Predicate)

noneMatch

public static <E> boolean noneMatch(Iterator<E> iterator,
                                    Predicate<? super E> predicate)

Returns whether or not no element of an iterator matches a specific predicate.

Type Parameters:

E - The element type.

Parameters:

iterator - The iterator with the elements to match.

predicate - The predicate to apply to elements of the given iterator.

Returns:

true if no element of the given iterator matches the given predicate, or false otherwise.

Throws:

NullPointerException - If the given iterator or predicate is null.

See Also:

Stream.noneMatch(Predicate)

findFirst

public static <E> Optional<E> findFirst(Iterator<E> iterator)

Returns the first element of an iterator.

Type Parameters:

E - The element type.

Parameters:

iterator - The iterator to return the first element of.

Returns:

An Optional describing the first element, or Optional.empty() if the given iterator has no elements.

Throws:

NullPointerException - If the given iterator is null.

See Also:

Stream.findFirst()

toStream

public static <E> Stream<E> toStream(Iterator<E> iterator)

Returns a stream based on an iterator.

Type Parameters:

E - The element type.

Parameters:

iterator - The iterator to return a stream for.

Returns:

A stream based on the given iterator.

Throws:

NullPointerException - If the given iterator is null.

See Also:

Spliterators.spliteratorUnknownSize(Iterator, int), StreamSupport.stream(Spliterator, boolean)

toStream

public static <E> Stream<E> toStream(Iterator<E> iterator,
                                     int characteristics)

Returns a stream based on an iterator.

Type Parameters:

E - The element type.

Parameters:

iterator - The iterator to return a stream for.

characteristics - Characteristics of the iterator's elements.

Returns:

A stream based on the given iterator.

Throws:

NullPointerException - If the given iterator is null.

See Also:

Spliterators.spliteratorUnknownSize(Iterator, int), StreamSupport.stream(Spliterator, boolean)

toStream

public static <E> Stream<E> toStream(Iterator<E> iterator,
                                     long size)

Returns a stream based on an iterator.

Type Parameters:

E - The element type.

Parameters:

iterator - The iterator to return a stream for.

size - The number of elements in the iterator.

Returns:

A stream based on the given iterator.

Throws:

NullPointerException - If the given iterator is null.

See Also:

Spliterators.spliterator(Iterator, long, int), StreamSupport.stream(Spliterator, boolean)

toStream

public static <E> Stream<E> toStream(Iterator<E> iterator,
                                     long size,
                                     int characteristics)

Returns a stream based on an iterator.

Type Parameters:

E - The element type.

Parameters:

iterator - The iterator to return a stream for.

size - The number of elements in the iterator.

characteristics - Characteristics of the iterator's elements.

Returns:

A stream based on the given iterator.

Throws:

NullPointerException - If the given iterator is null.

See Also:

Spliterators.spliterator(Iterator, long, int), StreamSupport.stream(Spliterator, boolean)

chainIterators

@SafeVarargs
public static <E> Iterator<E> chainIterators(Iterator<? extends E>... iterators)

Returns an iterator that contains the elements of several other iterators.

Type Parameters:

E - The element type.

Parameters:

iterators - The iterators with the elements for the returned iterator.

Returns:

An iterator that contains the elements of the given iterators.

Throws:

NullPointerException - If any of the given iterators is null.

chainIterators

public static <E> Iterator<E> chainIterators(Iterable<? extends Iterator<? extends E>> iterators)

Returns an iterator that contains the elements of several other iterators.

Type Parameters:

E - The element type.

Parameters:

iterators - The iterators with the elements for the returned iterator.

Returns:

An iterator that contains the elements of the given iterators.

Throws:

NullPointerException - If any of the given iterators is null.

chainIterables

@SafeVarargs
public static <E> Iterator<E> chainIterables(Iterable<? extends E>... iterables)

Returns an iterator that contains the elements of several other iterables.

Type Parameters:

E - The element type.

Parameters:

iterables - The iterables with the elements for the returned iterator.

Returns:

An iterator that contains the elements of the given iterables.

Throws:

NullPointerException - If any of the given iterables is null.

chainIterables

public static <E> Iterator<E> chainIterables(Iterable<? extends Iterable<? extends E>> iterables)

Returns an iterator that contains the elements of several other iterables.

Type Parameters:

E - The element type.

Parameters:

iterables - The iterables with the elements for the returned iterator.

Returns:

An iterator that contains the elements of the given iterables.

Throws:

NullPointerException - If any of the given iterables is null.

iterate

public static <E> Iterator<E> iterate(E seed,
                                      Predicate<? super E> hasNext,
                                      UnaryOperator<E> next)

Returns an iterator for which the elements are produced by iterative application of a function.

Type Parameters:

E - The element type.

Parameters:

seed - The initial element.

hasNext - A predicate that determines when iteration ends.

next - A function that determines the next element based on the previous one.

Returns:

An iterator for which the elements are produced by iterative application of the given function.