enumj

Interface Enumerator<E>

Type Parameters:

E - type of enumerated elements.

All Superinterfaces:

Iterator<E>

All Known Implementing Classes:

AbstractEnumerator, ArrayEnumerator, CacheEnumerator, ChoiceEnumerator, EnumerationEnumerator, IntRangeEnumerator, IteratorEnumerator, LateBindingEnumerator, LazyEnumerator, LongRangeEnumerator, PipeEnumerator, PipeSource, ShareableEnumerator, SharingEnumerator, SuppliedEnumerator, TolerantEnumerator

public interface Enumerator<E>
extends Iterator<E>

Iterator with high composability.

Enumerators are Iterator objects with the following characteristics:

• High composability: some operations can be composed iteratively
• Shareability: shareable enumerators may participate in multiple pipelines, processed independently
• Fault tolerance: fault-tolerant enumerators allow for exceptions in the middle of the pipeline without stopping the whole computation
• Lazy evaluations: enumerators allow for lazy evaluation in both returned values and input sequences
• Choice composition and zipping: construction of enumerators from multiple sub-sequences by choosing or zipping
• Compatibility and fluent syntax: enumerators support fluent syntax like Stream classes and are compatible with most major collection and sequence constructions: Iterator, Iterable, Enumeration, Stream, Spliterator and Supplier of elements.

High composability

The following operations can be composed iteratively many times and the resulting enumerator will not overflow the stack when enumerating:

• as(java.lang.Class)
• asFiltered(java.lang.Class)
• asOptional()
• append(java.lang.Object...)
• concatOn(java.lang.Object...)
• concat(java.util.Enumeration)
• concat(java.lang.Iterable)
• concat(java.util.Iterator)
• concat(java.util.Spliterator)
• concat(java.util.stream.Stream)
• concat(java.util.function.Supplier)
• filter(java.util.function.Predicate)
• flatMap(java.util.function.Function)
• limit(long)
• limitWhile(java.util.function.Predicate)
• map(java.util.function.Function)
• map(java.util.function.BiFunction)
• peek(java.util.function.Consumer)
• prependOn(java.lang.Object...)
• prepend(java.util.Enumeration)
• prepend(java.lang.Iterable)
• prepend(java.util.Iterator)
• prepend(java.util.Spliterator)
• prepend(java.util.stream.Stream)
• prepend(java.util.function.Supplier)
• repeatEach(int)
• skip(long)
• skipWhile(java.util.function.Predicate)
• take(long)
• takeWhile(java.util.function.Predicate)
• zipAll(java.util.Iterator, java.util.Iterator...)
• zipAny(java.util.Iterator)
• zipBoth(java.util.Iterator)
• zipLeft(java.util.Iterator)
• zipRight(java.util.Iterator)

Shareability

ShareableEnumerator can spawn instances of SharingEnumerator which in turn can share the same sequence without traversing it more than once. asShareable() converts any enumerator into a ShareableEnumerator.

Fault tolerance

Fault-tolerant enumerators accept an error handler which is being called whenever the tryPipelineOut of enumerating throws an exception. The error handler consumes the error and the pipeline doesn't stop. asTolerant(java.util.function.Consumer) converts any enumerator into a fault-tolerant enumerator.

Lazy evaluations

The following calls allow lazy specification of input sequences:

• ofLazyEnumeration(java.util.function.Supplier)
• ofLazyIterable(java.util.function.Supplier)
• ofLazyIterator(java.util.function.Supplier)
• ofLazySpliterator(java.util.function.Supplier)
• ofLazyStream(java.util.function.Supplier)

Choice composition and zipping

Enumerators can be constructed of sub-sequences by choosing elements from them:

• choiceOf(java.util.function.IntSupplier, java.util.Iterator, java.util.Iterator, java.util.Iterator...)
• choiceOf(java.util.function.IntSupplier, java.util.function.IntUnaryOperator, java.util.Iterator, java.util.Iterator, java.util.Iterator...)

Enumerators also have four zipping operations:

• zipAny(java.util.Iterator)
• zipBoth(java.util.Iterator)
• zipLeft(java.util.Iterator)
• zipRight(java.util.Iterator)

Method Summary

Modifier and Type	Method and Description
default boolean	allMatch(Predicate<? super E> predicate) Returns whether all the elements of the current enumerator match the provided predicate.
default boolean	anyMatch(Predicate<? super E> predicate) Returns whether any elements of the current enumerator match the provided predicate.
default Enumerator<E>	append(E... elements) Appends the provided elements to the end of the current enumerator.
default <T> Enumerator<T>	as(Class<T> clazz) Casts the current enumerator to an enumerator of a different parameter type.
default OnceEnumerable<E>	asEnumerable() Returns a OnceEnumerable instance enumerating over the current enumerator.
default Enumeration<E>	asEnumeration() Returns an Enumeration enumerating over the current enumerator.
default <T> Enumerator<T>	asFiltered(Class<T> clazz) Casts the current enumerator to a different parameter type and filters the enumerated elements based on that type.
default Enumerator<Optional<E>>	asOptional() Returns an infinite enumerator of non-empty Optional instances containing the current elements as long as they last or empty Optional instances if the current enumerator has no more elements.
default ShareableEnumerator<E>	asShareable() Returns a ShareableEnumerator sharing the elements of the current enumerator.
default Spliterator<E>	asSpliterator() Returns a sequential Spliterator iterating over the current enumerator.
default Stream<E>	asStream() Returns a sequential Stream streaming over the current enumerator.
default Supplier<Optional<E>>	asSupplier() Returns a Supplier supplying the elements of the current enumerator.
default Enumerator<E>	asTolerant(Consumer<? super Exception> handler) Returns a fault-tolerant enumerator with no retries.
default Enumerator<E>	asTolerant(Consumer<? super Exception> handler, int retries) Returns a fault-tolerant enumerator with retries.
static <E> Enumerator<E>	choiceOf(IntSupplier indexSupplier, IntUnaryOperator altIndexSupplier, Iterator<E> first, Iterator<? extends E> second, Iterator<? extends E>... rest) Returns an enumerator that chooses elements from the provided iterators.
static <E> Enumerator<E>	choiceOf(IntSupplier indexSupplier, Iterator<E> first, Iterator<? extends E> second, Iterator<? extends E>... rest) Returns an enumerator that chooses elements from the provided iterators.
default <R,A> R	collect(Collector<? super E,A,R> collector) Collects the elements of the current enumerator according to the provided Collector.
default Enumerator<E>	concat(Enumeration<? extends E> elements) Concatenates the current enumerator with the provided Enumeration.
default Enumerator<E>	concat(Iterable<? extends E> elements) Concatenates the current enumerator with the provided Iterable.
default Enumerator<E>	concat(Iterator<? extends E> elements) Concatenates the current enumerator with the provided Iterator.
default Enumerator<E>	concat(Spliterator<? extends E> elements) Concatenates the current enumerator with the provided sequential Spliterator.
default Enumerator<E>	concat(Stream<? extends E> elements) Concatenates the current enumerator with the provided sequential Stream.
default Enumerator<E>	concat(Supplier<Optional<E>> elements) Concatenates the current enumerator with the sequence formed of the elements supplied by the provided Supplier.
default Enumerator<E>	concatOn(E... elements) Concatenates the current enumerator with the sequence formed of the provided elements
default boolean	contains(E element) Returns whether the current enumerator has an element equalling the provided value.
default long	count() Returns the number of elements in the current enumerator.
default Enumerator<E>	distinct() Returns an enumerator containing the elements of the current enumerator in the same order by without duplicates.
default Optional<E>	elementAt(long index) Returns the element at the provided index within the sequence of enumerated elements.
default <T> boolean	elementsEqual(Iterator<T> elements) Returns whether the current enumerator and the provided iterator have equal elements and in the same order.
static <E> Enumerator<E>	empty() Returns en enumerator with no elements.
boolean	enumerating() Returns whether the enumerator has started enumerating.
default Enumerator<E>	filter(Predicate<? super E> predicate) Returns an enumerator consisting of the elements of the current enumerator that match the provided predicate.
default Optional<E>	first() Returns the first element of the current enumerator, if any.
default <R> Enumerator<R>	flatMap(Function<? super E,? extends Iterator<? extends R>> mapper) Returns an enumerator consisting of the results of replacing each enumerated element with the content of a mapped enumerator obtained by applying the provided mapper on each enumerated element.
default void	forEach(Consumer<? super E> consumer) Performs an action on each enumerated element.
static <E> Enumerator<E>	iterate(E seed, UnaryOperator<E> f) Returns an infinite enumerator obtained by applying repeatedly the provided unary operator.
default Optional<E>	last() Returns the last element of the current enumerator, if any.
default Enumerator<E>	limit(long maxSize) Returns the current enumerator truncated to the given size.
default Enumerator<E>	limitWhile(Predicate<? super E> predicate) Returns an enumerator enumerating over the elements of the current enumerator while stopping at the first element that does not match the provided predicate.
default <R> Enumerator<R>	map(BiFunction<? super E,? super Long,? extends R> mapper) Returns an enumerator consisting of the results of applying the provided function on the enumerated elements.
default <R> Enumerator<R>	map(Function<? super E,? extends R> mapper) Returns an enumerator consisting of the results of applying the given function on the enumerated elements.
default Optional<E>	max(Comparator<? super E> comparator) Returns the maximum of the enumerated elements according to the provided comparator.
default Optional<E>	min(Comparator<? super E> comparator) Returns the minimum of the enumerated elements according to the provided comparator.
default boolean	noneMatch(Predicate<? super E> predicate) Returns whether no enumerated element matches the provided predicate.
static <E> Enumerator<E>	of(E[] elements) Returns an enumerator iterating over the given array.
static <E> Enumerator<E>	of(Enumeration<E> source) Returns an enumerator enumerating over the elements of an existing Enumeration.
static <E> Enumerator<E>	of(Iterable<E> source) Returns an enumerator enumerating over the elements of an existing Iterable.
static <E> Enumerator<E>	of(Iterator<E> source) Returns an enumerator enumerating over an existing Iterator.
static <E> Enumerator<E>	of(Spliterator<E> source) Returns an enumerator enumerating over the elements of an existing Spliterator.
static <E> Enumerator<E>	of(Stream<E> source) Returns an enumerator enumerating over the elements of an existing Stream.
static <E> Enumerator<E>	of(Supplier<Optional<E>> source) Returns an enumerator enumerating over the elements supplied by an existing Supplier.
static <E> LateBindingEnumerator<E>	ofLateBinding(Class<E> clazz) Returns an enumerator that supports late-binding.
static <E> Enumerator<E>	ofLazyEnumeration(Supplier<? extends Enumeration<E>> source) Returns an enumerator enumerating over an Enumeration supplied lazily.
static <E> Enumerator<E>	ofLazyIterable(Supplier<? extends Iterable<E>> source) Returns an enumerator enumerating over an Iterable supplied lazily.
static <E> Enumerator<E>	ofLazyIterator(Supplier<? extends Iterator<E>> source) Returns an enumerator enumerating over an Iterator supplied lazily.
static <E> Enumerator<E>	ofLazySpliterator(Supplier<? extends Spliterator<E>> source) Returns an enumerator enumerating over a Spliterator supplied lazily.
static <E> Enumerator<E>	ofLazyStream(Supplier<? extends Stream<E>> source) Returns an enumerator enumerating over a Stream supplied lazily.
static <E> Enumerator<E>	on(E... elements) Returns an enumerator returning the given elements.
default Enumerator<E>	peek(Consumer<? super E> action) Returns an enumerator with the same enumerated elements as the current stream, additionally performing the provided action on each enumerated element.
default Enumerator<E>	prepend(Enumeration<? extends E> elements) Prepends the current enumerator with the provided Enumeration.
default Enumerator<E>	prepend(Iterable<? extends E> elements) Prepends the current enumerator with the provided Iterable.
default Enumerator<E>	prepend(Iterator<? extends E> elements) Prepends the current enumerator with the provided Iterator.
default Enumerator<E>	prepend(Spliterator<? extends E> elements) Prepends the current enumerator with the provided sequential Spliterator.
default Enumerator<E>	prepend(Stream<? extends E> elements) Prepends the current enumerator with the provided sequential Stream.
default Enumerator<E>	prepend(Supplier<Optional<E>> elements) Prepends the current enumerator with the sequence formed of the elements supplied by the provided Supplier.
default Enumerator<E>	prependOn(E... elements) Prepends the current enumerator with the sequence formed of the provided elements.
static <E> Enumerator<E>	range(E startInclusive, E endExclusive, UnaryOperator<E> succ, Comparator<? super E> cmp) Returns an enumerator enumerating over an ordered sequence between a start and an exclusive end.
static <E> Enumerator<E>	rangeClosed(E startInclusive, E endInclusive, UnaryOperator<E> succ, Comparator<? super E> cmp) Returns an enumerator enumerating over an ordered sequence between a start and an inclusive end.
static IntRangeEnumerator	rangeInt(int startInclusive, int endExclusive) Returns an enumerator enumerating over an integral range, upper limit excluded.
static IntRangeEnumerator	rangeIntClosed(int startInclusive, int endInclusive) Returns an enumerator enumerating over an integral range, upper limit included.
static LongRangeEnumerator	rangeLong(long startInclusive, long endExclusive) Returns an enumerator enumerating over an long integral range, upper limit excluded.
static LongRangeEnumerator	rangeLongClosed(long startInclusive, long endInclusive) Returns an enumerator enumerating over an long integral range, upper limit included.
default Optional<E>	reduce(BinaryOperator<E> accumulator) Performs a reduction on enumerated elements using an associative accumulation function and returns the reduced value, if any.
default E	reduce(E identity, BinaryOperator<E> accumulator) Performs a reduction on enumerated elements using an identity element and an associative accumulation function and returns the reduced value.
static <E> Enumerator<E>	repeat(E element, long count) Returns an enumerator that enumerates the same element the given number of times.
default Enumerator<E>	repeatAll(int count) Returns an enumerator that keeps enumerating over the current sequence, a given number of times.
static <E> Enumerator<E>	repeatAll(Supplier<Iterator<E>> source, long count) Returns an enumerator that enumerates over the iterator supplied lazily the given number of times.
default Enumerator<E>	repeatEach(int count) Enumerates over the elements of the current enumerator the given number of times.
default Enumerator<E>	reverse() Returns an enumerator that reverses the order of the enumerated elements.
default E	single() Returns the one and only element of the current enumerator.
default Enumerator<E>	skip(long n) Returns the current enumerator with the given number of front elements dropped.
default Enumerator<E>	skipWhile(Predicate<? super E> predicate) Returns the current enumerator with front elements dropped as long as they match a given predicate.
default Enumerator<E>	sorted() Returns an enumerator the sorts the enumerated elements.
default Enumerator<E>	sorted(Comparator<? super E> comparator) Returns an enumerator that sorts the current elements according to the given comparator.
default Enumerator<E>	take(long n) Returns the current enumerator truncated to the given size.
default Enumerator<E>	takeWhile(Predicate<? super E> predicate) Returns an enumerator enumerating over the elements of the current enumerator while stopping at the first element that does not match the provided predicate.
default E[]	toArray(Class<E> clazz) Collects the current enumerator into an array of elements of given class.
default List<E>	toList() Collects the current enumerator into a list of elements.
default <K,V> Map<K,V>	toMap(Function<? super E,K> keyMapper, Function<? super E,V> valueMapper) Collects the current enumerator into a Map according to a key mapping function and a value mapping function.
default Set<E>	toSet() Collects the current enumerator into a set.
default Enumerator<E>	union(Enumeration<? extends E> others) Returns an enumerator enumerating over the current enumerator and the provided Enumeration, all duplicates removed.
default Enumerator<E>	union(Iterable<? extends E> others) Returns an enumerator enumerating over the current enumerator and the provided Iterable, all duplicates removed.
default Enumerator<E>	union(Iterator<? extends E> others) Returns an enumerator enumerating over the current enumerator and the provided enumerator, all duplicates removed.
default Enumerator<E>	union(Spliterator<? extends E> others) Returns an enumerator enumerating over the current enumerator and the provided Spliterator, all duplicates removed.
default Enumerator<E>	union(Stream<? extends E> others) Returns an enumerator enumerating over the current enumerator and the provided Stream, all duplicates removed.
default Enumerator<E>	union(Supplier<Optional<E>> others) Returns an enumerator enumerating over the current enumerator and the elements supplied by the provided Supplier, all duplicates removed.
default Enumerator<E>	unionOn(E... others) Returns an enumerator enumerating over the current enumerator and the given elements, all duplicates removed.
default Enumerator<Optional<E>[]>	zipAll(Iterator<? extends E> first, Iterator<? extends E>... rest) Returns an enumerator consisting of an array of Optional objects containing elements from the current enumerator and the given Iterator instances, while any has elements.
default <T> Enumerator<Pair<Optional<E>,Optional<T>>>	zipAny(Iterator<T> elements) Returns an enumerator consisting of pairs of elements from the current enumerator and the given Iterator, while any of them has elements.
default <T> Enumerator<Pair<E,T>>	zipBoth(Iterator<T> elements) Returns an enumerator consisting of pairs of elements from the current enumerator and the given Iterator, while both have elements.
default <T> Enumerator<Pair<E,Optional<T>>>	zipLeft(Iterator<T> elements) Returns an enumerator consisting of pairs of elements from the current enumerator and the given Iterator, while the current enumerator has elements.
default <T> Enumerator<Pair<Optional<E>,T>>	zipRight(Iterator<T> elements) Returns an enumerator consisting of pairs of elements from the current enumerator and the given Iterator, while the provided iterator has elements.

Methods inherited from interface java.util.Iterator

forEachRemaining, hasNext, next, remove

Method Detail

enumerating

boolean enumerating()

Returns whether the enumerator has started enumerating.

This method returns false before the first call to hasNext and true afterwards.

Returns:

true if the enumerator has started enumerating, false otherwise.

See Also:

Iterator.hasNext(), Iterator.next()

on

@SafeVarargs
static <E> Enumerator<E> on(E... elements)

Returns an enumerator returning the given elements.

Type Parameters:

E - the type of elements being enumerated.

Parameters:

elements - the elements returned by the enumerator.

Returns:

the new Enumerator.

of

static <E> Enumerator<E> of(E[] elements)

Returns an enumerator iterating over the given array.

Type Parameters:

E - type of enumerated elements.

Parameters:

elements - array to iterate upon.

Returns:

the new Enumerator.

of

static <E> Enumerator<E> of(Iterator<E> source)

Returns an enumerator enumerating over an existing Iterator.

If source is of type Enumerator then this method returns source.

Type Parameters:

E - the type of elements being enumerated.

Parameters:

source - the Iterator being enumerated upon.

Returns:

the new enumerator.

Throws:

IllegalArgumentException - source is null.

of

static <E> Enumerator<E> of(Iterable<E> source)

Returns an enumerator enumerating over the elements of an existing Iterable.

Type Parameters:

E - the type of elements being enumerated.

Parameters:

source - the Iterable being enumerated upon.

Returns:

the new enumerator.

Throws:

IllegalArgumentException - source is null.

of

static <E> Enumerator<E> of(Enumeration<E> source)

Returns an enumerator enumerating over the elements of an existing Enumeration.

Type Parameters:

E - the type of elements being enumerated.

Parameters:

source - the Enumeration being enumerated upon

Returns:

the new enumerator.

Throws:

IllegalArgumentException - source is null.

of

static <E> Enumerator<E> of(Stream<E> source)

Returns an enumerator enumerating over the elements of an existing Stream.

If BaseStream.isParallel() returns true on source then the order of elements is undetermined.

Type Parameters:

E - the type of elements being enumerated.

Parameters:

source - the Stream being enumerated upon.

Returns:

the new enumerator.

Throws:

IllegalArgumentException - source is null.

of

static <E> Enumerator<E> of(Spliterator<E> source)

Returns an enumerator enumerating over the elements of an existing Spliterator.

Type Parameters:

E - the type of elements being enumerated.

Parameters:

source - the Spliterator being enumerated upon.

Returns:

the new enumerator.

Throws:

IllegalArgumentException - source is null.

of

static <E> Enumerator<E> of(Supplier<Optional<E>> source)

Returns an enumerator enumerating over the elements supplied by an existing Supplier.

The enumerator extracts and returns elements from source up to the first empty Optional value.

Type Parameters:

E - the type of elements being enumerated.

Parameters:

source - the Supplier of elements being enumerated. Enumeration continues up to the first empty Optional.

Returns:

the new enumerator.

Throws:

IllegalArgumentException - source is null.

ofLazyIterator

static <E> Enumerator<E> ofLazyIterator(Supplier<? extends Iterator<E>> source)

Returns an enumerator enumerating over an Iterator supplied lazily.

This method works like of(java.util.Iterator) with the distinction that source is supplied by a Supplier.

Type Parameters:

E - the type of elements being enumerated.

Parameters:

source - the Supplier supplying the Iterator to enumerate upon.

Returns:

the new enumerator.

Throws:

IllegalArgumentException - source is null.

See Also:

of(java.util.Iterator)

ofLazyIterable

static <E> Enumerator<E> ofLazyIterable(Supplier<? extends Iterable<E>> source)

Returns an enumerator enumerating over an Iterable supplied lazily.

This method works like of(java.lang.Iterable) with the distinction that source is supplied by a Supplier.

Type Parameters:

E - the type of elements being enumerated.

Parameters:

source - the Supplier supplying the Iterable to enumerate upon.

Returns:

the new enumerator.

Throws:

IllegalArgumentException - source is null.

See Also:

of(java.lang.Iterable)

ofLazyEnumeration

static <E> Enumerator<E> ofLazyEnumeration(Supplier<? extends Enumeration<E>> source)

Returns an enumerator enumerating over an Enumeration supplied lazily.

This method works like of(java.util.Enumeration) with the distinction that source is supplied by a Supplier.

Type Parameters:

E - the type of elements being enumerated

Parameters:

source - the Supplier supplying the Enumeration to enumerate upon

Returns:

the new enumerator

Throws:

IllegalArgumentException - source is null.

See Also:

of(java.util.Enumeration)

ofLazyStream

static <E> Enumerator<E> ofLazyStream(Supplier<? extends Stream<E>> source)

Returns an enumerator enumerating over a Stream supplied lazily.

This method works like of(java.util.stream.Stream) with the distinction that source is supplied by a Supplier.

Type Parameters:

E - the type of elements being enumerated.

Parameters:

source - the Supplier supplying the Stream to enumerate upon.

Returns:

the new enumerator.

Throws:

IllegalArgumentException - source is null.

See Also:

of(java.util.stream.Stream)

ofLazySpliterator

static <E> Enumerator<E> ofLazySpliterator(Supplier<? extends Spliterator<E>> source)

Returns an enumerator enumerating over a Spliterator supplied lazily.

This method works like of(java.util.Spliterator) with the distinction that source is supplied by a Supplier.

Type Parameters:

E - the type of elements being enumerated.

Parameters:

source - the Supplier supplying the Spliterator to enumerate upon.

Returns:

the new enumerator.

Throws:

IllegalArgumentException - source is null.

See Also:

of(java.util.Spliterator)

ofLateBinding

static <E> LateBindingEnumerator<E> ofLateBinding(Class<E> clazz)

Returns an enumerator that supports late-binding.

Type Parameters:

E - type of enumerated elements.

Parameters:

clazz - class of enumerated elements.

Returns:

the new enumerator.

See Also:

LateBindingEnumerator

as

default <T> Enumerator<T> as(Class<T> clazz)

Casts the current enumerator to an enumerator of a different parameter type.

Casting takes place upon the enumerator only. Element casting is considered implicit.

This operation is highly composable.

Type Parameters:

T - type of elements of the resulted enumerator.

Parameters:

clazz - class of the type to cast to.

Returns:

the type-casted enumerator.

See Also:

asFiltered(java.lang.Class)

asFiltered

default <T> Enumerator<T> asFiltered(Class<T> clazz)

Casts the current enumerator to a different parameter type and filters the enumerated elements based on that type.

This method works exactly like this.filter(e -> clazz.isInstance(e)).as(clazz).

Type Parameters:

T - type of elements of the resulted enumerator.

Parameters:

clazz - class of the type to cast and filter to.

Returns:

the resulted enumerator.

See Also:

as(java.lang.Class), filter(java.util.function.Predicate)

asEnumerable

default OnceEnumerable<E> asEnumerable()

Returns a OnceEnumerable instance enumerating over the current enumerator.

This method satisfies the condition this.asEnumerable().iterator() == this.

Returns:

the new OnceEnumerable.

asEnumeration

default Enumeration<E> asEnumeration()

Returns an Enumeration enumerating over the current enumerator.

Returns:

the new Enumeration.

See Also:

asEnumerable()

asOptional

default Enumerator<Optional<E>> asOptional()

Returns an infinite enumerator of non-empty Optional instances containing the current elements as long as they last or empty Optional instances if the current enumerator has no more elements.

The current enumerator may not return null elements.

This operation is highly composable.

Returns:

the infinite enumerator of Optional instances.

asSpliterator

default Spliterator<E> asSpliterator()

Returns a sequential Spliterator iterating over the current enumerator.

Returns:

the new Spliterator.

See Also:

asStream()

asStream

default Stream<E> asStream()

Returns a sequential Stream streaming over the current enumerator.

Returns:

the new Stream.

See Also:

asSpliterator(), asSupplier()

asSupplier

default Supplier<Optional<E>> asSupplier()

Returns a Supplier supplying the elements of the current enumerator.

The resulted Supplier supplies non-empty Optional instances as long as the current enumerator has elements. The current enumerator may not yield null elements.

Returns:

the new Supplier.

See Also:

asStream()

asShareable

default ShareableEnumerator<E> asShareable()

Returns a ShareableEnumerator sharing the elements of the current enumerator.

A ShareableEnumerator can either enumerate the elements of the current enumerator itself or it can produce a collection of Enumerator instances that will share the elements of the current iterator when enumerating independently of each other. The two modes are mutually exclusive.

Returns:

the new ShareableEnumerator.

See Also:

SharingEnumerator

asTolerant

default Enumerator<E> asTolerant(Consumer<? super Exception> handler)

Returns a fault-tolerant enumerator with no retries. The resulted enumerator has the following characteristics:

• any exception thrown by Iterator.next() gets handled by calling handler.accept(? super Exception) and it doesn't stop enumeration
• any exception thrown by Iterator.hasNext() gets handled by calling handler.accept(? super Exception) and it stops enumeration
• any exception thrown by handler.accept(? super Exception) stops enumeration and does not re-throw

Parameters:

handler - Consumer handling Exception instances thrown by hasNext() or next().

Returns:

the new fault-tolerant enumerator.

Throws:

IllegalArgumentException - handler is null.

See Also:

asTolerant(java.util.function.Consumer, int)

asTolerant

default Enumerator<E> asTolerant(Consumer<? super Exception> handler,
                                 int retries)

Returns a fault-tolerant enumerator with retries. The resulted enumerator has the following characteristics:

• any exception thrown by Iterator.next() gets handled by calling handler.accept(? super Exception) and it doesn't stop enumeration
• any exception thrown by Iterator.hasNext() gets handled by calling handler.accept(? super Exception) and it stops enumeration after a number of retries.
• any exception thrown by handler.accept(? super Exception) stops enumeration and does not re-throw

Parameters:

handler - Consumer handling Exception instances thrown by hasNext() or next().

retries - number of retries to hasNext() before returning false if hasNext() throws.

Returns:

the new fault-tolerant enumerator.

Throws:

IllegalArgumentException - handler is null or retries is negative.

See Also:

asTolerant(java.util.function.Consumer)

allMatch

default boolean allMatch(Predicate<? super E> predicate)

Returns whether all the elements of the current enumerator match the provided predicate.

Parameters:

predicate - state-less predicate to apply to the enumerated elements.

Returns:

true if all the elements satisfy. predicate, false otherwise

Throws:

IllegalArgumentException - predicate is null.

See Also:

anyMatch(java.util.function.Predicate), noneMatch(java.util.function.Predicate)

anyMatch

default boolean anyMatch(Predicate<? super E> predicate)

Returns whether any elements of the current enumerator match the provided predicate.

Parameters:

predicate - state-less predicate to apply to the enumerated elements.

Returns:

true if some elements satisfy predicate, false otherwise.

Throws:

IllegalArgumentException - predicate is null.

See Also:

allMatch(java.util.function.Predicate), noneMatch(java.util.function.Predicate)

append

default Enumerator<E> append(E... elements)

Appends the provided elements to the end of the current enumerator.

This operation is highly composable.

Parameters:

elements - values to append.

Returns:

the appended enumerator.

See Also:

concatOn(java.lang.Object...)

choiceOf

static <E> Enumerator<E> choiceOf(IntSupplier indexSupplier,
                                  Iterator<E> first,
                                  Iterator<? extends E> second,
                                  Iterator<? extends E>... rest)

Returns an enumerator that chooses elements from the provided iterators.

This method works like choiceOf(java.util.function.IntSupplier, java.util.function.IntUnaryOperator, java.util.Iterator, java.util.Iterator, java.util.Iterator...) with the distinction that altIndexSupplier is i -> (i+1)%(2+rest.length).

Type Parameters:

E - the type of elements being enumerated.

Parameters:

indexSupplier - Supplier instance supplying the index of the iterator to get the next element from.

first - the first iterator to choose elements from.

second - the second iterator to choose elements from.

rest - other iterators to choose elements from.

Returns:

the new enumerator.

Throws:

IllegalArgumentException - any argument is null.

See Also:

choiceOf(java.util.function.IntSupplier, java.util.function.IntUnaryOperator, java.util.Iterator, java.util.Iterator, java.util.Iterator...), zipAny(java.util.Iterator), zipBoth(java.util.Iterator), zipLeft(java.util.Iterator), zipRight(java.util.Iterator)

choiceOf

static <E> Enumerator<E> choiceOf(IntSupplier indexSupplier,
                                  IntUnaryOperator altIndexSupplier,
                                  Iterator<E> first,
                                  Iterator<? extends E> second,
                                  Iterator<? extends E>... rest)

Returns an enumerator that chooses elements from the provided iterators.

The pair formed of indexSupplier and altIndexSupplier makes the choice algorithm. The resulted enumerator chooses its next element in a multi-step tryPipelineOut:

• it calls indexSupplier.get() to get the index of a provided iterator. That iterator will provide the next element. Index 0 means the first iterator, index 1 means the second iterator and so on.
• if the chosen iterator has no elements, the resulted enumerator calls altIndexSupplier.apply(index) repeatedly until reaching a provided iterator that has elements.
• it calls Iterator.next() on the chosen iterator and it returns the element

The resulted enumerator will always stop when all the supplied iterators have no elements. Continuing to extract elements requires that a non-finished participant iterator can be found in 2+rest.length steps or less. If such an iterator cannot be found in the required number of steps, then the resulted enumerator stops even though there may be elements left.

To avoid early stopping it is necessary that altIndexSupplier leads to a non-finished iterator in timely manner. It is the responsibility of the caller to provide the choice algorithm in such a way that no element is lost because the resulted enumerator stops too early.

 Example:
 
 Enumerator.choiceOf(() -> 0,
                     i -> (i+1)%4,
                     Enumerator.empty<Integer>(),
                     Enumerator.on(1, 2, 3),
                     Enumerator.on(4, 5),
                     Enumerator.on(6))
 
 will produce the sequence 1, 2, 3, 4, 5 and 6.
 

Type Parameters:

E - type of elements being enumerated.

Parameters:

indexSupplier - Supplier instance supplying the index of the provided iterator to get the next element from.

altIndexSupplier - IntUnaryOperator instance supplying the index of the next provided iterator if the iterator chosen by indexSupplier has no more elements.

first - the first iterator to choose elements from.

second - the second iterator to choose elements from.

rest - other iterators to choose elements from.

Returns:

the new enumerator.

Throws:

IllegalArgumentException - any argument is null.

collect

default <R,A> R collect(Collector<? super E,A,R> collector)

Collects the elements of the current enumerator according to the provided Collector.

This methods works exactly like this.asStream().collect(collector).

Type Parameters:

R - the collected type.

A - the type of the intermediate accumulator during collection.

Parameters:

collector - Collector instance collecting the enumerated elements.

Returns:

the result of the collection.

Throws:

IllegalArgumentException - collector is null.

See Also:

asStream(), Stream, Collector

concat

default Enumerator<E> concat(Iterator<? extends E> elements)

Concatenates the current enumerator with the provided Iterator.

This operation is highly composable.

Parameters:

elements - Iterator instance to concatenate with

Returns:

the concatenated enumerator.

Throws:

IllegalArgumentException - elements is null.

concat

default Enumerator<E> concat(Iterable<? extends E> elements)

Concatenates the current enumerator with the provided Iterable.

This operation is highly composable.

Parameters:

elements - Iterable instance to concatenate with.

Returns:

the concatenated enumerator.

Throws:

IllegalArgumentException - elements is null.

concat

default Enumerator<E> concat(Enumeration<? extends E> elements)

Concatenates the current enumerator with the provided Enumeration.

This operation is highly composable.

Parameters:

elements - Enumeration instance to concatenate with

Returns:

the concatenated enumerator.

Throws:

IllegalArgumentException - elements is null.

concat

default Enumerator<E> concat(Stream<? extends E> elements)

Concatenates the current enumerator with the provided sequential Stream.

This operation is highly composable.

Parameters:

elements - Stream instance to concatenate with

Returns:

the concatenated enumerator.

Throws:

IllegalArgumentException - elements is null.

concat

default Enumerator<E> concat(Spliterator<? extends E> elements)

Concatenates the current enumerator with the provided sequential Spliterator.

This operation is highly composable.

Parameters:

elements - Spliterator instance to concatenate with

Returns:

the concatenated enumerator.

Throws:

IllegalArgumentException - elements is null.

concat

default Enumerator<E> concat(Supplier<Optional<E>> elements)

Concatenates the current enumerator with the sequence formed of the elements supplied by the provided Supplier.

The first value supplied by elements that is an empty Optional marks the end of the sequence to concatenate to.

This operation is highly composable.

Parameters:

elements - Supplier instance supplying the elements to concatenate to.

Returns:

the concatenated enumerator.

Throws:

IllegalArgumentException - elements is null.

concatOn

default Enumerator<E> concatOn(E... elements)

Concatenates the current enumerator with the sequence formed of the provided elements

This method works exactly like append(java.lang.Object...).

This operation is highly composable.

Parameters:

elements - the values to concatenate at the end of the current enumerator.

Returns:

the concatenated enumerator.

contains

default boolean contains(E element)

Returns whether the current enumerator has an element equalling the provided value.

Parameters:

element - value to look for.

Returns:

true if value equals an element in the current enumerator, false otherwise.

Throws:

IllegalArgumentException - elements is null.

count

default long count()

Returns the number of elements in the current enumerator.

Returns:

the number of enumerated elements.

distinct

default Enumerator<E> distinct()

Returns an enumerator containing the elements of the current enumerator in the same order by without duplicates.

This operation is highly composable.

Returns:

the new enumerator.

See Also:

sorted()

elementAt

default Optional<E> elementAt(long index)

Returns the element at the provided index within the sequence of enumerated elements.

An index equal to 0 means the first element. This method returns an empty Optional if index is larger than or equal to this.count().

Parameters:

index - 0-based index for the element to return.

Returns:

Optional instance containing the element at the required index.

Throws:

IllegalArgumentException - index is negative.

elementsEqual

default <T> boolean elementsEqual(Iterator<T> elements)

Returns whether the current enumerator and the provided iterator have equal elements and in the same order.

 This method works exactly like:
 
 this.zipAny(elements)
     .matchAll(p -> p.getLeft().isPresent() == p.getRight().isPresent()
                    && p.getLeft.isPresent()
                    && Objects.equsls(p.getLeft().get(),
                                      p.getRight().get()))
 
 

Type Parameters:

T - type of elements to match the enumerated elements against.

Parameters:

elements - Iterator instance whose elements get matched against the enumerated elements.

Returns:

true if the enumerated elements match the elements of Iterator in both value and position, false otherwise

Throws:

IllegalArgumentException - elements is null.

empty

static <E> Enumerator<E> empty()

Returns en enumerator with no elements.

Type Parameters:

E - type of the enumerated elements.

Returns:

the empty enumerator.

filter

default Enumerator<E> filter(Predicate<? super E> predicate)

Returns an enumerator consisting of the elements of the current enumerator that match the provided predicate.

This operation is highly composable.

Parameters:

predicate - state-less predicate to apply on each element.

Returns:

the filtered enumerator.

first

default Optional<E> first()

Returns the first element of the current enumerator, if any.

Returns:

Optional instance containing the first element.

flatMap

default <R> Enumerator<R> flatMap(Function<? super E,? extends Iterator<? extends R>> mapper)

Returns an enumerator consisting of the results of replacing each enumerated element with the content of a mapped enumerator obtained by applying the provided mapper on each enumerated element.

This operation is highly composable.

 Example:
 
 Enumerator.on(1, 2, 3)
           .flatMap(i -> Enumerator.on(i*i, i*(i+1)))
 
 will produce the sequence 1, 2, 4, 6, 9 and 12.
 

Type Parameters:

R - the element type of the new enumerator.

Parameters:

mapper - Function instance to apply on each enumerated element of the current enumerator.

Returns:

the flattened enumerator.

Throws:

IllegalArgumentException - mapper is null.

forEach

default void forEach(Consumer<? super E> consumer)

Performs an action on each enumerated element.

Parameters:

consumer - action to perform on each enumerated element.

Throws:

IllegalArgumentException - consumer is null.

iterate

static <E> Enumerator<E> iterate(E seed,
                                 UnaryOperator<E> f)

Returns an infinite enumerator obtained by applying repeatedly the provided unary operator.

The resulted enumerator returns seed, f(seed), f(f(seed)) ...

Type Parameters:

E - the type of enumerated elements

Parameters:

seed - the initial element

f - state-less Function instance to apply on the previous element to obtain the next element

Returns:

the iterated enumerator

Throws:

IllegalArgumentException - f is null.

last

default Optional<E> last()

Returns the last element of the current enumerator, if any.

Returns:

Optional instance containing the last element.

limit

default Enumerator<E> limit(long maxSize)

Returns the current enumerator truncated to the given size.

This method works exactly like take(long).

This operation is highly composable.

Parameters:

maxSize - the maximum number of elements in the resulted enumerator.

Returns:

the truncated enumerator.

Throws:

IllegalArgumentException - maxSize is negative/

limitWhile

default Enumerator<E> limitWhile(Predicate<? super E> predicate)

Returns an enumerator enumerating over the elements of the current enumerator while stopping at the first element that does not match the provided predicate.

this method works exactly like takeWhile(java.util.function.Predicate).

This operation is highly composable.

Parameters:

predicate - state-less Predicate instance to apply on enumerated elements.

Returns:

the truncated enumerator.

Throws:

IllegalArgumentException - predicate is null.

map

default <R> Enumerator<R> map(Function<? super E,? extends R> mapper)

Returns an enumerator consisting of the results of applying the given function on the enumerated elements.

This operation is highly composable.

Type Parameters:

R - the element type of the new enumerator.

Parameters:

mapper - state-less Function to apply on each enumerated element.

Returns:

the mapped enumerator

See Also:

map(java.util.function.BiFunction)

map

default <R> Enumerator<R> map(BiFunction<? super E,? super Long,? extends R> mapper)

Returns an enumerator consisting of the results of applying the provided function on the enumerated elements.

This method works like map(java.util.function.Function) with the distinction that each enumerated element is accompanied by its 0-based index.

Type Parameters:

R - the element type of the resulted enumerator.

Parameters:

mapper - state-less BiFunction to apply on each enumerated element.

Returns:

the mapped enumerator.

Throws:

IllegalArgumentException - mapper is null.

See Also:

map(java.util.function.Function)

max

default Optional<E> max(Comparator<? super E> comparator)

Returns the maximum of the enumerated elements according to the provided comparator.

Parameters:

comparator - state-less Comparator instance to compare enumerated elements.

Returns:

Optional instance containing the maximal enumerated element.

Throws:

IllegalArgumentException - comparator is null.

See Also:

min(java.util.Comparator)

min

default Optional<E> min(Comparator<? super E> comparator)

Returns the minimum of the enumerated elements according to the provided comparator.

Parameters:

comparator - state-less Comparator instance to compare enumerated elements.

Returns:

Optional instance containing the minimal enumerated element.

Throws:

IllegalArgumentException - comparator is null.

See Also:

max(java.util.Comparator)

noneMatch

default boolean noneMatch(Predicate<? super E> predicate)

Returns whether no enumerated element matches the provided predicate.

Parameters:

predicate - state-less Predicate instance to apply to enumerated elements.

Returns:

true if no enumerated element matches predicate, false otherwise.

Throws:

IllegalArgumentException - predicate is null.

See Also:

allMatch(java.util.function.Predicate), anyMatch(java.util.function.Predicate)

peek

default Enumerator<E> peek(Consumer<? super E> action)

Returns an enumerator with the same enumerated elements as the current stream, additionally performing the provided action on each enumerated element.

This operation is highly composable.

Parameters:

action - Consumer instance to apply on the elements as they get enumerated.

Returns:

the peeked enumerator.

Throws:

IllegalArgumentException - action is null.

prepend

default Enumerator<E> prepend(Iterator<? extends E> elements)

Prepends the current enumerator with the provided Iterator.

This operation is highly composable.

Parameters:

elements - Iterator instance to prepend in front of the current enumerator.

Returns:

the prepended enumerator.

Throws:

IllegalArgumentException - elements is null.

prepend

default Enumerator<E> prepend(Iterable<? extends E> elements)

Prepends the current enumerator with the provided Iterable.

This operation is highly composable.

Parameters:

elements - Iterable instance to prepend in front of the current enumerator.

Returns:

the prepended enumerator.

Throws:

IllegalArgumentException - elements is null.

prepend

default Enumerator<E> prepend(Enumeration<? extends E> elements)

Prepends the current enumerator with the provided Enumeration.

This operation is highly composable.

Parameters:

elements - Enumeration instance to prepend in front of the current enumerator.

Returns:

the prepended enumerator.

Throws:

IllegalArgumentException - elements is null.

prepend

default Enumerator<E> prepend(Stream<? extends E> elements)

Prepends the current enumerator with the provided sequential Stream.

This operation is highly composable.

Parameters:

elements - Stream instance to prepend in front of the current enumerator.

Returns:

the prepended enumerator.

Throws:

IllegalArgumentException - elements is null.

prepend

default Enumerator<E> prepend(Spliterator<? extends E> elements)

Prepends the current enumerator with the provided sequential Spliterator.

This operation is highly composable.

Parameters:

elements - Spliterator instance to prepend in front of the current enumerator.

Returns:

the prepended enumerator.

Throws:

IllegalArgumentException - elements is null.

prepend

default Enumerator<E> prepend(Supplier<Optional<E>> elements)

Prepends the current enumerator with the sequence formed of the elements supplied by the provided Supplier.

The first value supplied by elements that is an empty Optional marks the end of the sequence to prepend with.

This operation is highly composable.

Parameters:

elements - Supplier instance supplying the elements to prepend in front of the current enumerator.

Returns:

the prepended enumerator.

Throws:

IllegalStateException - the current enumerator is enumerating.

IllegalArgumentException - elements is null.

prependOn

default Enumerator<E> prependOn(E... elements)

Prepends the current enumerator with the sequence formed of the provided elements.

This method works like concatOn(elements) but at the opposite end.

This operation is highly composable.

Parameters:

elements - the values to prepend at the beginning of the current enumerator.

Returns:

the prepended enumerator.

range

static <E> Enumerator<E> range(E startInclusive,
                               E endExclusive,
                               UnaryOperator<E> succ,
                               Comparator<? super E> cmp)

Returns an enumerator enumerating over an ordered sequence between a start and an exclusive end.

Type Parameters:

E - type of enumerated elements.

Parameters:

startInclusive - the first element in the sequence.

endExclusive - the exclusive sequence end.

succ - UnaryOperator instance returning the successor of a given element.

cmp - Comparator instance comparing enumerated elements

Returns:

the enumerator covering the range.

Throws:

IllegalArgumentException - succ or cmp is null.

rangeClosed

static <E> Enumerator<E> rangeClosed(E startInclusive,
                                     E endInclusive,
                                     UnaryOperator<E> succ,
                                     Comparator<? super E> cmp)

Returns an enumerator enumerating over an ordered sequence between a start and an inclusive end.

Type Parameters:

E - type of enumerated elements.

Parameters:

startInclusive - the first element in the sequence.

endInclusive - the last element in the sequence.

succ - UnaryOperator instance returning the successor of a given element.

cmp - Comparator instance comparing enumerated elements

Returns:

the enumerator covering the range.

Throws:

IllegalArgumentException - succ or cmp is null.

rangeInt

static IntRangeEnumerator rangeInt(int startInclusive,
                                   int endExclusive)

Returns an enumerator enumerating over an integral range, upper limit excluded.

Parameters:

startInclusive - the lower bound of the range.

endExclusive - the exclusive upper bound of the range.

Returns:

the enumerator covering the range.

rangeIntClosed

static IntRangeEnumerator rangeIntClosed(int startInclusive,
                                         int endInclusive)

Returns an enumerator enumerating over an integral range, upper limit included.

Parameters:

startInclusive - the lower bound of the range.

endInclusive - the inclusive upper bound of the range.

Returns:

the enumerator covering the range.

rangeLong

static LongRangeEnumerator rangeLong(long startInclusive,
                                     long endExclusive)

Returns an enumerator enumerating over an long integral range, upper limit excluded.

Parameters:

startInclusive - the lower bound of the range.

endExclusive - the exclusive upper bound of the range.

Returns:

the enumerator covering the range.

rangeLongClosed

static LongRangeEnumerator rangeLongClosed(long startInclusive,
                                           long endInclusive)

Returns an enumerator enumerating over an long integral range, upper limit included.

Parameters:

startInclusive - the lower bound of the range.

endInclusive - the inclusive upper bound of the range.

Returns:

the enumerator covering the range.

reduce

default Optional<E> reduce(BinaryOperator<E> accumulator)

Performs a reduction on enumerated elements using an associative accumulation function and returns the reduced value, if any.

Parameters:

accumulator - associative BinaryOperator combining two enumerated elements.

Returns:

Optional instance containing the reduced value.

Throws:

IllegalArgumentException - accumulator is null.

reduce

default E reduce(E identity,
                 BinaryOperator<E> accumulator)

Performs a reduction on enumerated elements using an identity element and an associative accumulation function and returns the reduced value.

Parameters:

identity - starting point for the reduction.

accumulator - associative BinaryOperator combining two enumerated elements.

Returns:

the reduced value.

Throws:

IllegalArgumentException - accumulator is null.

repeat

static <E> Enumerator<E> repeat(E element,
                                long count)

Returns an enumerator that enumerates the same element the given number of times.

Type Parameters:

E - type of enumerated element.

Parameters:

element - the element to return.

count - the number of elements to return.

Returns:

the enumerator repeating the element.

Throws:

IllegalArgumentException - count is negative.

See Also:

repeatAll(java.util.function.Supplier, long), repeatAll(int), repeatEach(int)

repeatAll

static <E> Enumerator<E> repeatAll(Supplier<Iterator<E>> source,
                                   long count)

Returns an enumerator that enumerates over the iterator supplied lazily the given number of times.

Type Parameters:

E - type of enumerated element.

Parameters:

source - supplier of the iterator to repeat.

count - the number of times to repeat.

Returns:

the repeated enumerator.

Throws:

IllegalArgumentException - source is null or count is negative.

See Also:

repeat(java.lang.Object, long), repeatAll(int), repeatEach(int)

repeatAll

default Enumerator<E> repeatAll(int count)

Returns an enumerator that keeps enumerating over the current sequence, a given number of times.

The current enumerator gets iterated only once.

Parameters:

count - the number of times to repeatAll the elements sequence.

Returns:

the repeating enumerator.

Throws:

IllegalArgumentException - elements is null or count is negative.

See Also:

repeat(java.lang.Object, long), repeatAll(java.util.function.Supplier, long), repeatEach(int)

repeatEach

default Enumerator<E> repeatEach(int count)

Enumerates over the elements of the current enumerator the given number of times.

This operation is highly composable.

Parameters:

count - the number of times to repeatAll the elements in the sequence.

Returns:

the enumerator of repeated elements.

Throws:

IllegalArgumentException - elements is null or count is negative.

See Also:

repeat(java.lang.Object, long), repeatAll(java.util.function.Supplier, long), repeatAll(int)

reverse

default Enumerator<E> reverse()

Returns an enumerator that reverses the order of the enumerated elements.

Returns:

the reversed enumerator.

single

default E single()

Returns the one and only element of the current enumerator.

Returns:

the single element.

Throws:

InputMismatchException - the current enumerator has 0 or more than 1 elements.

skip

default Enumerator<E> skip(long n)

Returns the current enumerator with the given number of front elements dropped.

This operation is highly composable.

Parameters:

n - the number of front elements to drop.

Returns:

the truncated enumerator.

skipWhile

default Enumerator<E> skipWhile(Predicate<? super E> predicate)

Returns the current enumerator with front elements dropped as long as they match a given predicate.

This operation is highly composable.

Parameters:

predicate - Predicate instance to match the enumerated elements against.

Returns:

the enumerator with front elements dropped.

sorted

default Enumerator<E> sorted()

Returns an enumerator the sorts the enumerated elements.

Returns:

the sorted enumerator.

sorted

default Enumerator<E> sorted(Comparator<? super E> comparator)

Returns an enumerator that sorts the current elements according to the given comparator.

Parameters:

comparator - Comparator instance to compare enumerated elements.

Returns:

the sorted enumerator.

Throws:

IllegalArgumentException - comparator is null.

take

default Enumerator<E> take(long n)

Returns the current enumerator truncated to the given size.

This method works exactly like limit(long).

This operation is highly composable.

Parameters:

n - the maximum number of elements in the resulted enumerator.

Returns:

the truncated enumerator.

Throws:

IllegalArgumentException - n is negative.

takeWhile

default Enumerator<E> takeWhile(Predicate<? super E> predicate)

Returns an enumerator enumerating over the elements of the current enumerator while stopping at the first element that does not match the provided predicate.

this method works exactly like limitWhile(Predicate).

This operation is highly composable.

Parameters:

predicate - state-less Predicate instance to apply on enumerated elements.

Returns:

the truncated enumerator.

Throws:

IllegalArgumentException - predicate is null.

toArray

default E[] toArray(Class<E> clazz)

Collects the current enumerator into an array of elements of given class.

Parameters:

clazz - Class of array elements.

Returns:

the array of elements.

Throws:

IllegalArgumentException - clazz is null.

toList

default List<E> toList()

Collects the current enumerator into a list of elements.

Returns:

the list of elements.

toMap

default <K,V> Map<K,V> toMap(Function<? super E,K> keyMapper,
                             Function<? super E,V> valueMapper)

Collects the current enumerator into a Map according to a key mapping function and a value mapping function.

Type Parameters:

K - the map key type.

V - the map value type.

Parameters:

keyMapper - Function instance extracting the map key from enumerated elements.

valueMapper - Function instance extracting the map value from enumerated elements.

Returns:

Map instance containing the results of key and value mappings.

toSet

default Set<E> toSet()

Collects the current enumerator into a set.

Returns:

the set of elements.

union

default Enumerator<E> union(Iterator<? extends E> others)

Returns an enumerator enumerating over the current enumerator and the provided enumerator, all duplicates removed.

This method works exactly like this.concat(others).distinct().

Parameters:

others - enumerator to perform union with.

Returns:

the unified enumerator.

Throws:

IllegalArgumentException - others is null.

union

default Enumerator<E> union(Iterable<? extends E> others)

Returns an enumerator enumerating over the current enumerator and the provided Iterable, all duplicates removed.

This method works exactly like this.union(on(others)).

Parameters:

others - Iterable to perform union with.

Returns:

the unified enumerator.

Throws:

IllegalArgumentException - others is null.

union

default Enumerator<E> union(Enumeration<? extends E> others)

Returns an enumerator enumerating over the current enumerator and the provided Enumeration, all duplicates removed.

This method works exactly like this.union(on(others)).

Parameters:

others - Enumeration to perform union with.

Returns:

the unified enumerator.

Throws:

IllegalArgumentException - others is null.

union

default Enumerator<E> union(Stream<? extends E> others)

Returns an enumerator enumerating over the current enumerator and the provided Stream, all duplicates removed.

This method works exactly like this.union(on(others)).

Parameters:

others - Stream to perform union with.

Returns:

the unified enumerator.

Throws:

IllegalArgumentException - others is null.

union

default Enumerator<E> union(Spliterator<? extends E> others)

Returns an enumerator enumerating over the current enumerator and the provided Spliterator, all duplicates removed.

This method works exactly like this.union(on(others)).

Parameters:

others - Spliterator to perform union with.

Returns:

the unified enumerator.

Throws:

IllegalArgumentException - others is null.

union

default Enumerator<E> union(Supplier<Optional<E>> others)

Returns an enumerator enumerating over the current enumerator and the elements supplied by the provided Supplier, all duplicates removed.

This method works exactly like this.union(on(others)).

Parameters:

others - Supplier to perform union with.

Returns:

the unified enumerator.

Throws:

IllegalArgumentException - others is null.

unionOn

default Enumerator<E> unionOn(E... others)

Returns an enumerator enumerating over the current enumerator and the given elements, all duplicates removed.

This method works exactly like this.union(on(others)).

Parameters:

others - elements to perform union with.

Returns:

the unified enumerator.

zipAny

default <T> Enumerator<Pair<Optional<E>,Optional<T>>> zipAny(Iterator<T> elements)

Returns an enumerator consisting of pairs of elements from the current enumerator and the given Iterator, while any of them has elements.

The resulted enumerator stops when both the current enumerator and the provided Iterator stop. The first element of a returned pair is empty Optional if the current enumerator has no elements. Likewise, the second element of a returned pair is empty Optional if the provided Iterator has no elements.

This operation is highly composable.

Type Parameters:

T - the of elements to zip with.

Parameters:

elements - Iterator to zip with.

Returns:

the zipped enumerator.

Throws:

IllegalArgumentException - elements is null.

See Also:

zipBoth(java.util.Iterator), zipLeft(java.util.Iterator), zipRight(java.util.Iterator)

zipBoth

default <T> Enumerator<Pair<E,T>> zipBoth(Iterator<T> elements)

Returns an enumerator consisting of pairs of elements from the current enumerator and the given Iterator, while both have elements.

The resulted enumerator stops when aby of the current enumerator or the provided Iterator stop.

This operation is highly composable.

Type Parameters:

T - the of elements to zip with.

Parameters:

elements - Iterator to zip with.

Returns:

the zipped enumerator.

Throws:

IllegalArgumentException - elements is null.

See Also:

zipAny(java.util.Iterator), zipLeft(java.util.Iterator), zipRight(java.util.Iterator)

zipLeft

default <T> Enumerator<Pair<E,Optional<T>>> zipLeft(Iterator<T> elements)

Returns an enumerator consisting of pairs of elements from the current enumerator and the given Iterator, while the current enumerator has elements.

The resulted enumerator stops when the current enumerator stops. The second element of a returned pair is empty Optional if the provided Iterator has no elements.

This operation is highly composable.

Type Parameters:

T - the of elements to zip with.

Parameters:

elements - Iterator to zip with.

Returns:

the zipped enumerator.

Throws:

IllegalArgumentException - elements is null.

See Also:

zipAny(java.util.Iterator), zipBoth(java.util.Iterator), zipRight(java.util.Iterator)

zipRight

default <T> Enumerator<Pair<Optional<E>,T>> zipRight(Iterator<T> elements)

Returns an enumerator consisting of pairs of elements from the current enumerator and the given Iterator, while the provided iterator has elements.

The resulted enumerator stops when the provided Iterator stops. The first element of a returned pair is empty Optional if the current enumerator has no elements.

This operation is highly composable.

Type Parameters:

T - the of elements to zip with.

Parameters:

elements - Iterator to zip with.

Returns:

the zipped enumerator.

Throws:

IllegalArgumentException - elements is null.

See Also:

zipAny(java.util.Iterator), zipBoth(java.util.Iterator), zipLeft(java.util.Iterator)

zipAll

default Enumerator<Optional<E>[]> zipAll(Iterator<? extends E> first,
                                         Iterator<? extends E>... rest)

Returns an enumerator consisting of an array of Optional objects containing elements from the current enumerator and the given Iterator instances, while any has elements.

This operation is highly composable.

Parameters:

first - first Iterator to zip with.

rest - the rest of iterators to zip with.

Returns:

the zipped enumerator of arrays of Optional instances.