Package com.globalmentor.collections.iterators

Class Iterators

java.lang.Object

com.globalmentor.collections.iterators.Iterators

public class Iterators
extends Object

Various utilities to be used with iterators.

Author:

Garret Wilson

See Also:

• Iterator

Field Summary

Fields

Modifier and Type	Field	Description
static final Iterable<?>	EMPTY_ITERABLE	The singleton immutable empty iterable.
static final Iterator<?>	EMPTY_ITERATOR	The singleton immutable empty iterator.

Constructor Summary

Constructors

Constructor	Description
Iterators()

Method Summary

Modifier and Type	Method	Description
static <E> JoinIterator<E>	concat(Iterator<E>... iterators)	Returns an iterator concatenating the contents of multiple iterators.
static <E> JoinIterator<E>	concat(Iterator<E> iterator, Enumeration<E> enumeration)	Returns an iterator concatenating the contents of an iterator and an enumeration.
static <E> JoinIterator<E>	concat(Iterator<E> iterator1, Iterator<E> iterator2)	Returns an iterator concatenating the contents of two iterators.
static <E> ListIterator<E>	createCopy(Iterator<E> iterator)	Creates a copy of the iterator that contains the same data but will not reflect any modified values of the underlying collection.
static final <T> Iterable<T>	emptyIterable()
static final <T> Iterator<T>	emptyIterator()
static <E> Optional<E>	findNext(Iterator<E> iterator)	Returns an Optional describing the first element of this iterator, or an empty Optional if the iterator is empty.
static <E> Optional<E>	findOnly(Iterator<E> iterator)	Returns an Optional describing the first and only element of this iterator, or an empty Optional if the iterator is empty.
static <E, X extends RuntimeException> Optional<E>	findOnly(Iterator<E> iterator, Supplier<X> manyElementsExceptionSupplier)	Returns an Optional describing the first and only element of this iterator, or an empty Optional if the iterator is empty.
static <E> E	getOnly(Iterator<E> iterator)	Retrieves the one and only one element expected to be in the iterator.
static <E, X extends RuntimeException> E	getOnly(Iterator<E> iterator, Supplier<X> manyElementsExceptionSupplier)	Retrieves the one and only one element expected to be in the iterator.
static <E> E[]	toArray(Iterable<E> iterable, Class<E> elementClass)	Returns a copy of the contents of the iterable in a new array in iterator traversal order.
static <E> E[]	toArray(Iterator<E> iterator, Class<E> elementClass)	Returns a copy of the contents of the iterator in a new array in iterator traversal order.
static <E> Enumeration<E>	toEnumeration(Iterator<E> iterator)	Converts an iterator to an enumeration, if it isn't already.
static <E> Iterable<E>	toIterable(Iterator<E> iterator)	Returns a single-use iterable that returns the given iterator.
static <E> Iterator<E>	toIterator(Enumeration<E> enumeration)	Converts an enumeration to an iteration, if it isn't already.
static <E> Stream<E>	toStream(Iterator<E> iterator)	Returns a stream providing access to the contents of the given iterator.

Methods inherited from class java.lang.Object

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

Field Details

EMPTY_ITERATOR

public static final Iterator<?> EMPTY_ITERATOR

The singleton immutable empty iterator.

EMPTY_ITERABLE

public static final Iterable<?> EMPTY_ITERABLE

The singleton immutable empty iterable.

Constructor Details

Iterators

public Iterators()

Method Details

emptyIterator

public static final <T> Iterator<T> emptyIterator()

Type Parameters:

T - The type of the iterator.

Returns:

The immutable empty iterator.

emptyIterable

public static final <T> Iterable<T> emptyIterable()

Type Parameters:

T - The generic type of empty iterable to return.

Returns:

The immutable empty iterable.

concat

public static <E> JoinIterator<E> concat(@Nonnull
 Iterator<E> iterator1,
 @Nonnull
 Iterator<E> iterator2)

Returns an iterator concatenating the contents of two iterators.

Tip: The returned iterator can be used as an Iterator or an Enumeration.

Type Parameters:

E - The type of elements returned by the iterators.

Parameters:

iterator1 - The iterator the contents of which will appear first in the iteration.

iterator2 - The iterator the contents of which will appear second in the iteration.

Returns:

An iterator that will return the contents of the two iterators in order.

concat

@SafeVarargs
public static <E> JoinIterator<E> concat(@Nonnull
 Iterator<E>... iterators)

Returns an iterator concatenating the contents of multiple iterators.

Tip: The returned iterator can be used as an Iterator or an Enumeration.

Type Parameters:

E - The type of elements returned by the iterators.

Parameters:

iterators - The iterators to concatenate.

Returns:

An iterator that will return the contents of the given iterators in order.

Throws:

NullPointerException - if any of the given iterators is null.

concat

public static <E> JoinIterator<E> concat(@Nonnull
 Iterator<E> iterator,
 @Nonnull
 Enumeration<E> enumeration)

Returns an iterator concatenating the contents of an iterator and an enumeration.

Tip: The returned iterator can be used as an Iterator or an Enumeration.

Type Parameters:

E - The type of elements returned by the iterator and the enumeration.

Parameters:

iterator - An iterator the contents of which will appear first in the iteration.

enumeration - An enumeration the contents of which will appear after that of the iterator.

Returns:

An iterator that will return the contents of the iterator and the enumeration in order.

createCopy

public static <E> ListIterator<E> createCopy(Iterator<E> iterator)

Creates a copy of the iterator that contains the same data but will not reflect any modified values of the underlying collection. Creates a new collection, collects the values of the given iterator, then returns an iterator to the new collection.

Type Parameters:

E - The type of items that the iterator is set up to iterate.

Parameters:

iterator - The iterator to make a copy of.

Returns:

An iterator containing the same values as the given iterator but not reflecting the underlying values of the original collection.

findNext

public static <E> Optional<E> findNext(@Nonnull
 Iterator<E> iterator)

Returns an Optional describing the first element of this iterator, or an empty Optional if the iterator is empty.

API Note:

This method is equivalent to calling Iterator.next(), except an empty optional is returned rather than throwing an exception if there is no next item.

Type Parameters:

E - The type of elements returned by the iterator.

Parameters:

iterator - The iterator from which the next object should be retrieved.

Returns:

An Optional describing the first element of this iterator, or an empty Optional if the iterator is empty.

See Also:

• Iterator.next()
• Stream.findFirst()

findOnly

public static <E> Optional<E> findOnly(@Nonnull
 Iterator<E> iterator)

Returns an Optional describing the first and only element of this iterator, or an empty Optional if the iterator is empty.

Implementation Specification:

This implementation delegates to findOnly(Iterator, Supplier).

Type Parameters:

E - The type of elements returned by the iterator.

Parameters:

iterator - The iterator from which the only object should be retrieved.

Returns:

An Optional describing the only element of this iterator, or an empty Optional if the iterator is empty.

Throws:

IllegalArgumentException - if the given stream has more than one element.

See Also:

• Iterator.next()

findOnly

public static <E,
X extends RuntimeException>
Optional<E> findOnly(@Nonnull
 Iterator<E> iterator,
 @Nonnull
 Supplier<X> manyElementsExceptionSupplier)

Returns an Optional describing the first and only element of this iterator, or an empty Optional if the iterator is empty.

Type Parameters:

E - The type of elements returned by the iterator.

X - The type of exception to be thrown if there are many elements.

Parameters:

iterator - The iterator from which the only object should be retrieved.

manyElementsExceptionSupplier - The strategy for creating an exception to throw if more than one element is present.

Returns:

An Optional describing the only element of this iterator, or an empty Optional if the iterator is empty.

Throws:

RuntimeException - if the given stream has more than one element.

See Also:

• Iterator.next()

getOnly

public static <E> E getOnly(@Nonnull
 Iterator<E> iterator)

Retrieves the one and only one element expected to be in the iterator.

Type Parameters:

E - The type of element in the iterator.

Parameters:

iterator - The iterator from which the only element will be retrieved.

Returns:

The one and only one element in the iterator.

Throws:

NoSuchElementException - if the iterator has no more elements

IllegalArgumentException - if the given iterator has more than one element.

getOnly

public static <E,
X extends RuntimeException> E getOnly(@Nonnull
 Iterator<E> iterator,
 @Nonnull
 Supplier<X> manyElementsExceptionSupplier)

Retrieves the one and only one element expected to be in the iterator.

Type Parameters:

E - The type of element in the iterator.

X - The type of exception to be thrown if there are many elements.

Parameters:

iterator - The iterator from which only element will be retrieved.

manyElementsExceptionSupplier - The strategy for creating an exception to throw if more than one element is present.

Returns:

The one and only one element in the iterator.

Throws:

NoSuchElementException - if the iterator has no more elements

RuntimeException - if the given stream has more than one element.

toArray

public static <E> E[] toArray(Iterator<E> iterator,
 Class<E> elementClass)

Returns a copy of the contents of the iterator in a new array in iterator traversal order.

Type Parameters:

E - The type of the iterator.

Parameters:

iterator - The iterator the contents of which to return as an array.

elementClass - The class representing the type of elements returned by the iterable.

Returns:

A array containing the contents of the iterable.

Throws:

NullPointerException - if the given iterator and/or element class is null.

toArray

public static <E> E[] toArray(Iterable<E> iterable,
 Class<E> elementClass)

Returns a copy of the contents of the iterable in a new array in iterator traversal order.

Type Parameters:

E - The type of the iterator.

Parameters:

iterable - The iterable the contents of which to return as an array.

elementClass - The class representing the type of elements returned by the iterable.

Returns:

A array containing the contents of the iterable.

Throws:

NullPointerException - if the given iterable and/or element class is null.

toEnumeration

public static <E> Enumeration<E> toEnumeration(@Nonnull
 Iterator<E> iterator)

Converts an iterator to an enumeration, if it isn't already.

Type Parameters:

E - the type of elements returned by the iterator.

Parameters:

iterator - The iterator to be converted to an enumeration.

Returns:

An enumeration delegating to the given iterator, or the iterator itself it is also an Enumeration.

toIterable

public static <E> Iterable<E> toIterable(@Nonnull
 Iterator<E> iterator)

Returns a single-use iterable that returns the given iterator.

Unlike most iterables, the returned iterable may only be iterated a single time.

Type Parameters:

E - the type of elements returned by the iterator.

Parameters:

iterator - The iterator to be converted to an iterable.

Returns:

A single-user iterable that returns the given iterator.

toIterator

public static <E> Iterator<E> toIterator(@Nonnull
 Enumeration<E> enumeration)

Converts an enumeration to an iteration, if it isn't already.

Type Parameters:

E - the type of elements returned by the enumeration.

Parameters:

enumeration - The enumeration to be converted to an iterator.

Returns:

An iterator delegating to the given enumeration, or the enumeration itself it is also an Iterator.

toStream

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

Returns a stream providing access to the contents of the given iterator.

Type Parameters:

E - The type of elements returned by the iterator.

Parameters:

iterator - The iterator to be converted to a stream.

Returns:

A stream that returns the contents of the given iterator.