Package com.globalmentor.collections.iterables

Class Iterables

java.lang.Object

com.globalmentor.collections.iterables.Iterables

public class Iterables
extends Object

Various utilities to be used with iterables.

Author:

Garret Wilson

See Also:

• Iterable

Constructor Summary

Constructors

Constructor	Description
Iterables()

Method Summary

Modifier and Type	Method	Description
static <T> Optional<T>	findFirst(Iterable<T> iterable)	Returns an Optional describing the first element of this iterable, or an empty Optional if the iterable is empty.
static <T> Optional<T>	findOnly(Iterable<T> iterable)	Returns an Optional describing the first and only element of this iterable, or an empty Optional if the iterable is empty.
static <T, X extends RuntimeException> Optional<T>	findOnly(Iterable<T> iterable, Supplier<X> manyElementsExceptionSupplier)	Returns an Optional describing the first and only element of this iterable, or an empty Optional if the iterable is empty.
static <E> E	getOnly(Iterable<E> iterable)	Retrieves the one and only one element expected to be in the iterable.
static <E, X extends RuntimeException> E	getOnly(Iterable<E> iterable, Supplier<X> manyElementsExceptionSupplier)	Retrieves the one and only one element expected to be in the iterable.

Methods inherited from class java.lang.Object

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

Constructor Details

Iterables

public Iterables()

Method Details

findFirst

public static <T> Optional<T> findFirst(@Nonnull
 Iterable<T> iterable)

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

Implementation Specification:

This implementation efficiently short-circuits and avoids creating an iterator if the iterable is an instance of a Collection, which has a known size. Otherwise this implementation delegates to Iterators.findNext(Iterator).

Type Parameters:

T - the type of elements returned by the iterator.

Parameters:

iterable - The iterable from which the first object should be retrieved.

Returns:

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

See Also:

• Good way to get *any* value from a Java Set?
• Iterator.next()
• Stream.findFirst()
• Iterators.findNext(Iterator)

findOnly

public static <T> Optional<T> findOnly(@Nonnull
 Iterable<T> iterable)

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

Implementation Specification:

This implementation efficiently short-circuits and avoids creating an iterator if the iterable is an instance of a Collection, which has a known size. Otherwise this implementation delegates to Iterators.findOnly(Iterator).

Type Parameters:

T - The type of elements returned by the iterable.

Parameters:

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

Returns:

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

Throws:

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

See Also:

• Iterator.next()

findOnly

public static <T,
X extends RuntimeException>
Optional<T> findOnly(@Nonnull
 Iterable<T> iterable,
 @Nonnull
 Supplier<X> manyElementsExceptionSupplier)

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

Implementation Specification:

This implementation efficiently short-circuits and avoids creating an iterator if the iterable is an instance of a Collection, which has a known size. Otherwise this implementation delegates to Iterators.findOnly(Iterator, Supplier).

Type Parameters:

T - The type of elements returned by the iterable.

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

Parameters:

iterable - The iterable 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 iterable, or an empty Optional if the iterable is empty.

Throws:

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

See Also:

• Iterator.next()

getOnly

public static <E> E getOnly(@Nonnull
 Iterable<E> iterable)

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

Implementation Specification:

This implementation delegates to Iterators.getOnly(Iterator).

Type Parameters:

E - The type of element in the iterable.

Parameters:

iterable - The iterable from which the element will be retrieved.

Returns:

The one and only one element in the iterable.

Throws:

NoSuchElementException - if the iterable has no more elements

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

getOnly

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

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

Implementation Specification:

This implementation delegates to Iterators.getOnly(Iterator, Supplier).

Type Parameters:

E - The type of element in the iterable.

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

Parameters:

iterable - The iterable from which the 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 iterable.

Throws:

NoSuchElementException - if the iterable has no more elements

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