Package software.kes.enhancediterables

Interface EnhancedIterable<A>

Type Parameters:

A - the element type

All Superinterfaces:

com.jnape.palatable.lambda.functor.Functor<A,EnhancedIterable<?>>, java.lang.Iterable<A>

All Known Subinterfaces:

FiniteIterable<A>, ImmutableFiniteIterable<A>, ImmutableIterable<A>, ImmutableNonEmptyFiniteIterable<A>, ImmutableNonEmptyIterable<A>, NonEmptyFiniteIterable<A>, NonEmptyIterable<A>

public interface EnhancedIterable<A>
extends java.lang.Iterable<A>, com.jnape.palatable.lambda.functor.Functor<A,EnhancedIterable<?>>

An Iterable with some additional methods.

May be infinite, finite, or empty.

Any Iterable can be upgraded to an EnhancedIterable by calling enhance(Iterable)}.

Method Summary

Modifier and Type	Method	Description
default NonEmptyIterable<A>	append(A element)	Lazily appends an element to the end of this EnhancedIterable, yielding a new NonEmptyIterable.
default EnhancedIterable<A>	concat(java.lang.Iterable<A> other)	Lazily concatenates another Iterable to the end of this EnhancedIterable, yielding a new EnhancedIterable.
default NonEmptyIterable<A>	concat(NonEmptyIterable<A> other)	Lazily concatenates a NonEmptyIterable to the end of this EnhancedIterable, yielding a new NonEmptyIterable.
static <A> ImmutableFiniteIterable<A>	copyFrom(int maxCount, java.lang.Iterable<A> source)	Creates an ImmutableFiniteIterable by copying elements from an Iterable.
static <A> ImmutableFiniteIterable<A>	copyFrom(java.util.Collection<A> source)	Creates an ImmutableFiniteIterable by copying elements from a Collection.
static <A> ImmutableFiniteIterable<A>	copyFrom(FiniteIterable<A> source)	Creates an ImmutableFiniteIterable by copying elements from a FiniteIterable.
default EnhancedIterable<A>	drop(int count)	Returns a new EnhancedIterable that drops the first count elements of this EnhancedIterable.
default EnhancedIterable<A>	dropWhile(com.jnape.palatable.lambda.functions.Fn1<? super A,? extends java.lang.Boolean> predicate)	Returns a new EnhancedIterable that skips the first contiguous group of elements of this EnhancedIterable that satisfy a predicate.
static <A> ImmutableFiniteIterable<A>	emptyEnhancedIterable()	Creates an empty EnhancedIterable.
static <A> EnhancedIterable<A>	enhance(java.lang.Iterable<A> underlying)	Wraps an existing Iterable in an EnhancedIterable.
default EnhancedIterable<A>	filter(com.jnape.palatable.lambda.functions.Fn1<? super A,? extends java.lang.Boolean> predicate)	Returns a new EnhancedIterable that contains all elements of this EnhancedIterable that satisfy a predicate.
default com.jnape.palatable.lambda.adt.Maybe<A>	find(com.jnape.palatable.lambda.functions.Fn1<? super A,? extends java.lang.Boolean> predicate)	Finds the first element of this EnhancedIterable that satisfies a predicate, if any.
default <B> EnhancedIterable<B>	fmap(com.jnape.palatable.lambda.functions.Fn1<? super A,? extends B> f)	Returns a new EnhancedIterable by applying a function to all elements of this EnhancedIterable.
default EnhancedIterable<A>	intersperse(A separator)	Returns a new EnhancedIterable with the provided separator value injected between each value of this EnhancedIterable.
default boolean	isEmpty()	Tests whether this EnhancedIterable is empty.
default EnhancedIterable<? extends NonEmptyIterable<A>>	magnetizeBy(com.jnape.palatable.lambda.functions.Fn2<A,A,java.lang.Boolean> predicate)	Returns an Iterable of contiguous groups of elements in this EnhancedIterable that match a predicate pairwise.
static <A> ImmutableNonEmptyFiniteIterable<A>	of(A first, A... more)	Creates an EnhancedIterable containing the given elements.
default <B,C> com.jnape.palatable.lambda.adt.hlist.Tuple2<? extends EnhancedIterable<B>,? extends EnhancedIterable<C>>	partition(com.jnape.palatable.lambda.functions.Fn1<? super A,? extends com.jnape.palatable.lambda.adt.coproduct.CoProduct2<B,C,?>> function)	Partitions this EnhancedIterable given a disjoint mapping function.
default NonEmptyIterable<A>	prepend(A element)	Lazily prepends an element to the front of this EnhancedIterable, yielding a new NonEmptyIterable.
default EnhancedIterable<A>	prependAll(A separator)	Returns a new EnhancedIterable with the provided separator value injected before each value of this EnhancedIterable.
static <A> ImmutableNonEmptyIterable<A>	repeat(A element)	Returns an infinite ImmutableNonEmptyIterable that repeatedly iterates a given element.
default EnhancedIterable<? extends NonEmptyFiniteIterable<A>>	slide(int k)	"Slides" a window of k elements across the EnhancedIterable by one element at a time.
default com.jnape.palatable.lambda.adt.hlist.Tuple2<? extends EnhancedIterable<A>,? extends EnhancedIterable<A>>	span(com.jnape.palatable.lambda.functions.Fn1<? super A,? extends java.lang.Boolean> predicate)	Returns a Tuple2 where the first slot is the front contiguous elements of this EnhancedIterable matching a predicate and the second slot is all the remaining elements.
default ImmutableNonEmptyIterable<? extends EnhancedIterable<A>>	tails()	Returns an ImmutableNonEmptyIterable containing all of the subsequences of tail elements of this EnhancedIterable, ordered by size, starting with the full list.
default FiniteIterable<A>	take(int count)	Returns a new FiniteIterable that takes the first count elements of this EnhancedIterable.
default EnhancedIterable<A>	takeWhile(com.jnape.palatable.lambda.functions.Fn1<? super A,? extends java.lang.Boolean> predicate)	Returns a new EnhancedIterable that limits to the first contiguous group of elements of this EnhancedIterable that satisfy a predicate.
default A[]	toArray(java.lang.Class<A[]> arrayType)	Writes all the elements of this EnhancedIterable directly into an array of the specified type.
default <C extends java.util.Collection<A>> C	toCollection(com.jnape.palatable.lambda.functions.Fn0<C> cSupplier)	Creates an instance of a Collection of type C, and adds to it all elements in this EnhancedIterable.
default com.jnape.palatable.lambda.adt.Maybe<? extends FiniteIterable<A>>	toFinite()	Converts this EnhancedIterable to a FiniteIterable if there is enough information to do so without iterating it.
default com.jnape.palatable.lambda.adt.Maybe<? extends NonEmptyIterable<A>>	toNonEmpty()	Converts this EnhancedIterable to a NonEmptyIterable if it contains one or more elements.
default <B,C> EnhancedIterable<C>	zipWith(com.jnape.palatable.lambda.functions.Fn2<A,B,C> fn, java.lang.Iterable<B> other)	Zips together this EnhancedIterable with another Iterable by applying a zipping function.
default <B,C> FiniteIterable<C>	zipWith(com.jnape.palatable.lambda.functions.Fn2<A,B,C> fn, java.util.Collection<B> other)	Zips together this EnhancedIterable with a Collection by applying a zipping function.
default <B,C> FiniteIterable<C>	zipWith(com.jnape.palatable.lambda.functions.Fn2<A,B,C> fn, FiniteIterable<B> other)	Zips together this EnhancedIterable with a FiniteIterable by applying a zipping function.

Methods inherited from interface com.jnape.palatable.lambda.functor.Functor

coerce

Methods inherited from interface java.lang.Iterable

forEach, iterator, spliterator

Method Detail

append

default NonEmptyIterable<A> append(A element)

Lazily appends an element to the end of this EnhancedIterable, yielding a new NonEmptyIterable.

Parameters:

element - the element to append

Returns:

a NonEmptyIterable<A>

concat

default EnhancedIterable<A> concat(java.lang.Iterable<A> other)

Lazily concatenates another Iterable to the end of this EnhancedIterable, yielding a new EnhancedIterable.

Parameters:

other - the other Iterable

Returns:

an EnhancedIterable<A>

concat

default NonEmptyIterable<A> concat(NonEmptyIterable<A> other)

Lazily concatenates a NonEmptyIterable to the end of this EnhancedIterable, yielding a new NonEmptyIterable.

Parameters:

other - a NonEmptyIterable

Returns:

a NonEmptyIterable<A>

drop

default EnhancedIterable<A> drop(int count)

Returns a new EnhancedIterable that drops the first count elements of this EnhancedIterable.

Parameters:

count - the number of elements to drop from this EnhancedIterable. Must be >= 0. May exceed size of this EnhancedIterable, in which case, the result will be an empty EnhancedIterable.

Returns:

an EnhancedIterable<A>

dropWhile

default EnhancedIterable<A> dropWhile(com.jnape.palatable.lambda.functions.Fn1<? super A,? extends java.lang.Boolean> predicate)

Returns a new EnhancedIterable that skips the first contiguous group of elements of this EnhancedIterable that satisfy a predicate.

Iteration begins at the first element for which the predicate evaluates to false.

Parameters:

predicate - a predicate; should be referentially transparent and not have side-effects

Returns:

an EnhancedIterable<A>

filter

default EnhancedIterable<A> filter(com.jnape.palatable.lambda.functions.Fn1<? super A,? extends java.lang.Boolean> predicate)

Returns a new EnhancedIterable that contains all elements of this EnhancedIterable that satisfy a predicate.

Parameters:

predicate - a predicate; should be referentially transparent and not have side-effects

Returns:

an EnhancedIterable<A>

find

default com.jnape.palatable.lambda.adt.Maybe<A> find(com.jnape.palatable.lambda.functions.Fn1<? super A,? extends java.lang.Boolean> predicate)

Finds the first element of this EnhancedIterable that satisfies a predicate, if any.

Parameters:

predicate - a predicate; not null

Returns:

an element wrapped in a Maybe.just(A) if a matching element is found; Maybe.nothing() otherwise.

fmap

default <B> EnhancedIterable<B> fmap(com.jnape.palatable.lambda.functions.Fn1<? super A,? extends B> f)

Returns a new EnhancedIterable by applying a function to all elements of this EnhancedIterable.

Specified by:

fmap in interface com.jnape.palatable.lambda.functor.Functor<A,EnhancedIterable<?>>

Type Parameters:

B - the type returned by f

Parameters:

f - a function from A to B. This function should be referentially transparent and not perform side-effects. It may be called zero or more times for each element.

Returns:

an EnhancedIterable<B>

intersperse

default EnhancedIterable<A> intersperse(A separator)

Returns a new EnhancedIterable with the provided separator value injected between each value of this EnhancedIterable.

If this EnhancedIterable contains fewer than two elements, it is left untouched.

Parameters:

separator - the separator value

Returns:

an EnhancedIterable<A>

isEmpty

default boolean isEmpty()

Tests whether this EnhancedIterable is empty.

Returns:

true if this EnhancedIterable contains no elements, false otherwise

magnetizeBy

default EnhancedIterable<? extends NonEmptyIterable<A>> magnetizeBy(com.jnape.palatable.lambda.functions.Fn2<A,A,java.lang.Boolean> predicate)

Returns an Iterable of contiguous groups of elements in this EnhancedIterable that match a predicate pairwise.

Parameters:

predicate - the predicate function. This function should be referentially transparent and not perform side-effects. It may be called zero or more times for each element.

Returns:

an EnhancedIterable<NonEmptyIterable<A>> containing the contiguous groups

partition

default <B,C> com.jnape.palatable.lambda.adt.hlist.Tuple2<? extends EnhancedIterable<B>,? extends EnhancedIterable<C>> partition(com.jnape.palatable.lambda.functions.Fn1<? super A,? extends com.jnape.palatable.lambda.adt.coproduct.CoProduct2<B,C,?>> function)

Partitions this EnhancedIterable given a disjoint mapping function.

Note that while the returned tuple must be constructed eagerly, the left and right iterables contained therein are both lazy, so comprehension over infinite iterables is supported.

Type Parameters:

B - the output left Iterable element type, as well as the CoProduct2 A type

C - the output right Iterable element type, as well as the CoProduct2 B type

Parameters:

function - the mapping function

Returns:

a Tuple2<EnhancedIterable&lt;B&gt;, EnhancedIterable&lt;C&gt;>

prepend

default NonEmptyIterable<A> prepend(A element)

Lazily prepends an element to the front of this EnhancedIterable, yielding a new NonEmptyIterable.

Parameters:

element - the element to prepend

Returns:

a NonEmptyIterable<A>

prependAll

default EnhancedIterable<A> prependAll(A separator)

Returns a new EnhancedIterable with the provided separator value injected before each value of this EnhancedIterable.

If this EnhancedIterable is empty, it is left untouched.

Parameters:

separator - the separator value

Returns:

an EnhancedIterable<A>

slide

default EnhancedIterable<? extends NonEmptyFiniteIterable<A>> slide(int k)

"Slides" a window of k elements across the EnhancedIterable by one element at a time.

Example: EnhancedIterable.of(1, 2, 3, 4, 5).slide(2); // [[1, 2], [2, 3], [3, 4], [4, 5]]

Parameters:

k - the number of elements in the sliding window. Must be >= 1.

Returns:

an EnhancedIterable<NonEmptyFiniteIterable<A>>

span

default com.jnape.palatable.lambda.adt.hlist.Tuple2<? extends EnhancedIterable<A>,? extends EnhancedIterable<A>> span(com.jnape.palatable.lambda.functions.Fn1<? super A,? extends java.lang.Boolean> predicate)

Returns a Tuple2 where the first slot is the front contiguous elements of this EnhancedIterable matching a predicate and the second slot is all the remaining elements.

Parameters:

predicate - a predicate; should be referentially transparent and not have side-effects

Returns:

a Tuple2<EnhancedIterable&lt;B&gt;, EnhancedIterable&lt;C&gt;>

tails

default ImmutableNonEmptyIterable<? extends EnhancedIterable<A>> tails()

Returns an ImmutableNonEmptyIterable containing all of the subsequences of tail elements of this EnhancedIterable, ordered by size, starting with the full list. Example: EnhancedIterable.of(1, 2, 3).tails(); // [[1, 2, 3], [2, 3], [3], []]

Returns:

an ImmutableNonEmptyIterable<EnhancedIterable<A>>

take

default FiniteIterable<A> take(int count)

Returns a new FiniteIterable that takes the first count elements of this EnhancedIterable.

Parameters:

count - the number of elements to take from this EnhancedIterable. Must be >= 0. May exceed size of this EnhancedIterable, in which case, the result will contain as many elements available.

Returns:

a FiniteIterable<A>

takeWhile

default EnhancedIterable<A> takeWhile(com.jnape.palatable.lambda.functions.Fn1<? super A,? extends java.lang.Boolean> predicate)

Returns a new EnhancedIterable that limits to the first contiguous group of elements of this EnhancedIterable that satisfy a predicate.

Iteration ends at, but does not include, the first element for which the predicate evaluates to false.

Parameters:

predicate - a predicate; should be referentially transparent and not have side-effects

Returns:

an EnhancedIterable<A>

toArray

default A[] toArray(java.lang.Class<A[]> arrayType)

Writes all the elements of this EnhancedIterable directly into an array of the specified type.

Parameters:

arrayType - the type of the array

Returns:

a new array

toCollection

default <C extends java.util.Collection<A>> C toCollection(com.jnape.palatable.lambda.functions.Fn0<C> cSupplier)

Creates an instance of a Collection of type C, and adds to it all elements in this EnhancedIterable.

Note that instances of C must support Collection.add(E) (which is to say, must not throw on invocation).

Type Parameters:

C - the resulting collection type

Parameters:

cSupplier - a function that instantiates a new Collection of type C

Returns:

a new Collection of type C

toFinite

default com.jnape.palatable.lambda.adt.Maybe<? extends FiniteIterable<A>> toFinite()

Converts this EnhancedIterable to a FiniteIterable if there is enough information to do so without iterating it.

Note that if this method returns nothing(), it does NOT necessarily mean this EnhancedIterable is infinite.

Returns:

a Maybe<FiniteIterable<A>

toNonEmpty

default com.jnape.palatable.lambda.adt.Maybe<? extends NonEmptyIterable<A>> toNonEmpty()

Converts this EnhancedIterable to a NonEmptyIterable if it contains one or more elements.

Returns:

a Maybe<NonEmptyIterable<A>

zipWith

default <B,C> EnhancedIterable<C> zipWith(com.jnape.palatable.lambda.functions.Fn2<A,B,C> fn,
                                                java.lang.Iterable<B> other)

Zips together this EnhancedIterable with another Iterable by applying a zipping function.

Applies the function to the successive elements of each Iterable until one of them runs out of elements.

Type Parameters:

B - the element type of the other Iterable

C - the element type of the result

Parameters:

fn - the zipping function. Not null. This function should be referentially transparent and not perform side-effects. It may be called zero or more times for each element.

other - the other Iterable

Returns:

an EnhancedIterable<C>

zipWith

default <B,C> FiniteIterable<C> zipWith(com.jnape.palatable.lambda.functions.Fn2<A,B,C> fn,
                                              FiniteIterable<B> other)

Zips together this EnhancedIterable with a FiniteIterable by applying a zipping function.

Applies the function to the successive elements of each Iterable until one of them runs out of elements.

Type Parameters:

B - the element type of the other Iterable

C - the element type of the result

Parameters:

fn - the zipping function. Not null. This function should be referentially transparent and not perform side-effects. It may be called zero or more times for each element.

other - the other Iterable

Returns:

a FiniteIterable<C>

zipWith

default <B,C> FiniteIterable<C> zipWith(com.jnape.palatable.lambda.functions.Fn2<A,B,C> fn,
                                              java.util.Collection<B> other)

Zips together this EnhancedIterable with a Collection by applying a zipping function.

Applies the function to the successive elements of each Iterable until one of them runs out of elements.

Type Parameters:

B - the element type of the other Iterable

C - the element type of the result

Parameters:

fn - the zipping function. Not null. This function should be referentially transparent and not perform side-effects. It may be called zero or more times for each element.

other - the other Iterable

Returns:

a FiniteIterable<C>

emptyEnhancedIterable

static <A> ImmutableFiniteIterable<A> emptyEnhancedIterable()

Creates an empty EnhancedIterable.

Type Parameters:

A - the element type

Returns:

an ImmutableFiniteIterable<A>

copyFrom

static <A> ImmutableFiniteIterable<A> copyFrom(FiniteIterable<A> source)

Creates an ImmutableFiniteIterable by copying elements from a FiniteIterable.

If source is already an ImmutableFiniteIterable, this method will return it without copying.

Type Parameters:

A - the element type

Parameters:

source - the source to copy from

Returns:

an ImmutableFiniteIterable<A>

copyFrom

static <A> ImmutableFiniteIterable<A> copyFrom(java.util.Collection<A> source)

Creates an ImmutableFiniteIterable by copying elements from a Collection.

Type Parameters:

A - the element type

Parameters:

source - the source to copy from

Returns:

an ImmutableFiniteIterable<A>

copyFrom

static <A> ImmutableFiniteIterable<A> copyFrom(int maxCount,
                                               java.lang.Iterable<A> source)

Creates an ImmutableFiniteIterable by copying elements from an Iterable.

If source is already an ImmutableIterable, no copying will be performed.

Type Parameters:

A - the element type

Parameters:

maxCount - the maximum number of elements to take from the supplied Iterable. Must be >= 0. May exceed size of the Iterable, in which case, the result will contain as many elements available.

source - the source to copy from

Returns:

an ImmutableFiniteIterable<A>

enhance

static <A> EnhancedIterable<A> enhance(java.lang.Iterable<A> underlying)

Wraps an existing Iterable in an EnhancedIterable.

If underlying is already an EnhancedIterable, returns it directly.

Type Parameters:

A - the element type

Parameters:

underlying - the Iterable to wrap. May be finite or infinite.

Returns:

an EnhancedIterable<A>

repeat

static <A> ImmutableNonEmptyIterable<A> repeat(A element)

Returns an infinite ImmutableNonEmptyIterable that repeatedly iterates a given element.

Type Parameters:

A - the element type

Parameters:

element - the value to repeat

Returns:

an ImmutableNonEmptyIterable<A>

of

@SafeVarargs
static <A> ImmutableNonEmptyFiniteIterable<A> of(A first,
                                                 A... more)

Creates an EnhancedIterable containing the given elements.

Note that this method actually returns an ImmutableNonEmptyFiniteIterable, which is also an EnhancedIterable.

Type Parameters:

A - the element type

Parameters:

first - the first element

more - the remaining elements

Returns:

an ImmutableNonEmptyFiniteIterable<A>