Package software.kes.enhancediterables

Interface FiniteIterable<A>

Type Parameters:

A - the element type

All Superinterfaces:

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

All Known Subinterfaces:

ImmutableFiniteIterable<A>, ImmutableNonEmptyFiniteIterable<A>, NonEmptyFiniteIterable<A>

public interface FiniteIterable<A>
extends EnhancedIterable<A>

An EnhancedIterable that is finite.

Method Summary

Modifier and Type	Method	Description
default NonEmptyFiniteIterable<A>	append(A element)	Lazily appends an element to the end of this FiniteIterable, yielding a new NonEmptyFiniteIterable.
default FiniteIterable<A>	concat(java.util.Collection<A> other)	Lazily concatenates a Collection to the end of this FiniteIterable, yielding a new FiniteIterable.
default FiniteIterable<A>	concat(FiniteIterable<A> other)	Lazily concatenates another FiniteIterable to the end of this FiniteIterable, yielding a new FiniteIterable.
default NonEmptyFiniteIterable<A>	concat(NonEmptyFiniteIterable<A> other)	Lazily concatenates a NonEmptyFiniteIterable to the end of this FiniteIterable, yielding a new NonEmptyFiniteIterable.
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 <B> FiniteIterable<com.jnape.palatable.lambda.adt.hlist.Tuple2<A,B>>	cross(java.util.Collection<B> other)	Returns the lazily computed cartesian product of this FiniteIterable with a Collection.
default <B> FiniteIterable<com.jnape.palatable.lambda.adt.hlist.Tuple2<A,B>>	cross(FiniteIterable<B> other)	Returns the lazily computed cartesian product of this FiniteIterable with another FiniteIterable.
default EnhancedIterable<A>	cycle()	Returns an infinite EnhancedIterable that repeatedly cycles this FiniteIterable's elements, in order.
default FiniteIterable<A>	distinct()	Returns a FiniteIterable of the distinct values from this FiniteIterable.
default FiniteIterable<A>	drop(int count)	Returns a new FiniteIterable that drops the first count elements of this FiniteIterable.
default FiniteIterable<A>	dropWhile(com.jnape.palatable.lambda.functions.Fn1<? super A,? extends java.lang.Boolean> predicate)	Returns a new FiniteIterable that skips the first contiguous group of elements of this FiniteIterable that satisfy a predicate.
static <A> ImmutableFiniteIterable<A>	emptyFiniteIterable()	Creates an empty FiniteIterable.
default FiniteIterable<A>	filter(com.jnape.palatable.lambda.functions.Fn1<? super A,? extends java.lang.Boolean> predicate)	Returns a new FiniteIterable that contains all elements of this FiniteIterable that satisfy a predicate.
static <A> FiniteIterable<A>	finiteIterable(int maxCount, java.lang.Iterable<A> iterable)	Creates a FiniteIterable by wrapping an Iterable.
static <A> FiniteIterable<A>	finiteIterable(java.util.Collection<A> collection)	Creates a FiniteIterable by wrapping a Collection.
default <B> FiniteIterable<B>	fmap(com.jnape.palatable.lambda.functions.Fn1<? super A,? extends B> f)	Returns a new FiniteIterable by applying a function to all elements of this FiniteIterable.
default <B> B	foldLeft(com.jnape.palatable.lambda.functions.Fn2<? super B,? super A,? extends B> op, B z)	Applies a binary operator to a start value and all elements of this FiniteIterable, going left to right.
default <B> com.jnape.palatable.lambda.functor.builtin.Lazy<B>	foldRight(com.jnape.palatable.lambda.functions.Fn2<? super A,? super com.jnape.palatable.lambda.functor.builtin.Lazy<B>,? extends com.jnape.palatable.lambda.functor.builtin.Lazy<B>> op, com.jnape.palatable.lambda.functor.builtin.Lazy<B> z)	Applies a binary operator to a start value and all elements of this FiniteIterable, going right to left.
default ImmutableNonEmptyFiniteIterable<? extends FiniteIterable<A>>	inits()	Returns a ImmutableNonEmptyIterable containing all of the subsequences of initial elements of this FiniteIterable, ordered by size, starting with the empty list.
default FiniteIterable<A>	intersperse(A separator)	Returns a new FiniteIterable with the provided separator value injected between each value of this FiniteIterable.
default FiniteIterable<? extends NonEmptyFiniteIterable<A>>	magnetizeBy(com.jnape.palatable.lambda.functions.Fn2<A,A,java.lang.Boolean> predicate)	Returns an Iterable of contiguous groups of elements in this FiniteIterable that match a predicate pairwise.
static <A> ImmutableNonEmptyFiniteIterable<A>	of(A first, A... more)	Creates a FiniteIterable containing the given elements.
default <B,C> com.jnape.palatable.lambda.adt.hlist.Tuple2<? extends FiniteIterable<B>,? extends FiniteIterable<C>>	partition(com.jnape.palatable.lambda.functions.Fn1<? super A,? extends com.jnape.palatable.lambda.adt.coproduct.CoProduct2<B,C,?>> function)	Partitions this FiniteIterable given a disjoint mapping function.
default NonEmptyFiniteIterable<A>	prepend(A element)	Lazily prepends an element to the front of this FiniteIterable, yielding a new NonEmptyFiniteIterable.
default FiniteIterable<A>	prependAll(A separator)	Returns a new FiniteIterable with the provided separator value injected before each value of this FiniteIterable.
default FiniteIterable<A>	reverse()	Returns a reversed representation of this FiniteIterable.
default int	size()	Returns the number of elements in this FiniteIterable.
default FiniteIterable<? extends NonEmptyFiniteIterable<A>>	slide(int k)	"Slides" a window of k elements across the FiniteIterable by one element at a time.
default com.jnape.palatable.lambda.adt.hlist.Tuple2<? extends FiniteIterable<A>,? extends FiniteIterable<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 FiniteIterable matching a predicate and the second slot is all the remaining elements.
default ImmutableNonEmptyIterable<? extends FiniteIterable<A>>	tails()	Returns an ImmutableNonEmptyIterable containing all of the subsequences of tail elements of this FiniteIterable, ordered by size, starting with the full list.
default FiniteIterable<A>	takeWhile(com.jnape.palatable.lambda.functions.Fn1<? super A,? extends java.lang.Boolean> predicate)	Returns a new FiniteIterable that limits to the first contiguous group of elements of this FiniteIterable that satisfy a predicate.
default com.jnape.palatable.lambda.adt.Maybe<? extends FiniteIterable<A>>	toFinite()	Always succeeds because FiniteIterables are always finite.
default com.jnape.palatable.lambda.adt.Maybe<? extends NonEmptyFiniteIterable<A>>	toNonEmpty()	Converts this FiniteIterable to a NonEmptyFiniteIterable if it contains one or more elements.
default <B,C> FiniteIterable<C>	zipWith(com.jnape.palatable.lambda.functions.Fn2<A,B,C> fn, java.lang.Iterable<B> other)	Zips together this FiniteIterable with another Iterable by applying a zipping function.

Methods inherited from interface software.kes.enhancediterables.EnhancedIterable

concat, concat, find, isEmpty, take, toArray, toCollection, zipWith, zipWith

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 NonEmptyFiniteIterable<A> append(A element)

Lazily appends an element to the end of this FiniteIterable, yielding a new NonEmptyFiniteIterable.

Specified by:

append in interface EnhancedIterable<A>

Parameters:

element - the element to append

Returns:

a NonEmptyFiniteIterable<A>

concat

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

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

Parameters:

other - the other FiniteIterable

Returns:

a FiniteIterable<A>

concat

default FiniteIterable<A> concat(java.util.Collection<A> other)

Lazily concatenates a Collection to the end of this FiniteIterable, yielding a new FiniteIterable.

Parameters:

other - a Collection

Returns:

a FiniteIterable<A>

concat

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

Lazily concatenates a NonEmptyFiniteIterable to the end of this FiniteIterable, yielding a new NonEmptyFiniteIterable.

Parameters:

other - a NonEmptyFiniteIterable

Returns:

a NonEmptyFiniteIterable<A>

cross

default <B> FiniteIterable<com.jnape.palatable.lambda.adt.hlist.Tuple2<A,B>> cross(FiniteIterable<B> other)

Returns the lazily computed cartesian product of this FiniteIterable with another FiniteIterable.

Type Parameters:

B - the type of the other FiniteIterable

Parameters:

other - a FiniteIterable of any type

Returns:

a FiniteIterable<Tuple2<A, B>>

cross

default <B> FiniteIterable<com.jnape.palatable.lambda.adt.hlist.Tuple2<A,B>> cross(java.util.Collection<B> other)

Returns the lazily computed cartesian product of this FiniteIterable with a Collection.

Type Parameters:

B - the type of the other Collection

Parameters:

other - a Collection of any type

Returns:

a FiniteIterable<Tuple2<A, B>>

cycle

default EnhancedIterable<A> cycle()

Returns an infinite EnhancedIterable that repeatedly cycles this FiniteIterable's elements, in order.

Returns:

an EnhancedIterable<A>

distinct

default FiniteIterable<A> distinct()

Returns a FiniteIterable of the distinct values from this FiniteIterable.

Returns:

a FiniteIterable<A>

drop

default FiniteIterable<A> drop(int count)

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

Specified by:

drop in interface EnhancedIterable<A>

Parameters:

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

Returns:

a FiniteIterable<A>

dropWhile

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

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

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

Specified by:

dropWhile in interface EnhancedIterable<A>

Parameters:

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

Returns:

a FiniteIterable<A>

filter

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

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

Specified by:

filter in interface EnhancedIterable<A>

Parameters:

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

Returns:

a FiniteIterable<A>

fmap

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

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

Specified by:

fmap in interface EnhancedIterable<A>

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:

a FiniteIterableonEmptyFiniteIterable<B>

foldLeft

default <B> B foldLeft(com.jnape.palatable.lambda.functions.Fn2<? super B,? super A,? extends B> op,
                       B z)

Applies a binary operator to a start value and all elements of this FiniteIterable, going left to right.

Type Parameters:

B - the result type of the binary operator

Parameters:

z - the start value

op - the binary operator

Returns:

the result of inserting op between consecutive elements of this FiniteIterable, going left to right with the start value z on the left: op(...op(z, x_1), x_2, ..., x_n) where x,,1,,, ..., x,,n,, are the elements of this FiniteIterable Returns z if this FiniteIterable is empty.

foldRight

default <B> com.jnape.palatable.lambda.functor.builtin.Lazy<B> foldRight(com.jnape.palatable.lambda.functions.Fn2<? super A,? super com.jnape.palatable.lambda.functor.builtin.Lazy<B>,? extends com.jnape.palatable.lambda.functor.builtin.Lazy<B>> op,
                                                                         com.jnape.palatable.lambda.functor.builtin.Lazy<B> z)

Applies a binary operator to a start value and all elements of this FiniteIterable, going right to left.

This method is computationally the iterative inverse of foldLeft(com.jnape.palatable.lambda.functions.Fn2<? super B, ? super A, ? extends B>, B), but uses Lazy to support stack-safe execution.

Type Parameters:

B - the result type of the binary operator

Parameters:

z - the start value

op - the binary operator

Returns:

a Lazy<B> that evaluates to the result of inserting op between consecutive elements of this FiniteIterable, going right to left with the start value z on the right: op(x_1, op(x_2, ... op(x_n, z)...)) where x,,1,,, ..., x,,n,, are the elements of this FiniteIterable Returns z if this FiniteIterable is empty.

inits

default ImmutableNonEmptyFiniteIterable<? extends FiniteIterable<A>> inits()

Returns a ImmutableNonEmptyIterable containing all of the subsequences of initial elements of this FiniteIterable, ordered by size, starting with the empty list. Example: FiniteIterable.of(1, 2, 3).inits(); // [[], [1], [1, 2], [1, 2, 3]]

Returns:

a ImmutableNonEmptyFiniteIterable<FiniteIterable<A>>

intersperse

default FiniteIterable<A> intersperse(A separator)

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

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

Specified by:

intersperse in interface EnhancedIterable<A>

Parameters:

separator - the separator value

Returns:

a FiniteIterable<A>

magnetizeBy

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

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

Specified by:

magnetizeBy in interface EnhancedIterable<A>

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:

a FiniteIterable<NonEmptyFiniteIterable<A>> containing the contiguous groups

partition

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

Partitions this FiniteIterable given a disjoint mapping function.

Specified by:

partition in interface EnhancedIterable<A>

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<FiniteIterable&lt;B&gt;, FiniteIterable&lt;C&gt;>

prepend

default NonEmptyFiniteIterable<A> prepend(A element)

Lazily prepends an element to the front of this FiniteIterable, yielding a new NonEmptyFiniteIterable.

Specified by:

prepend in interface EnhancedIterable<A>

Parameters:

element - the element to prepend

Returns:

a NonEmptyFiniteIterable<A>

prependAll

default FiniteIterable<A> prependAll(A separator)

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

If this FiniteIterable is empty, it is left untouched.

Specified by:

prependAll in interface EnhancedIterable<A>

Parameters:

separator - the separator value

Returns:

a FiniteIterable<A>

reverse

default FiniteIterable<A> reverse()

Returns a reversed representation of this FiniteIterable.

Note that reversing is deferred until the returned Iterable is iterated.

Returns:

a FiniteIterable<A>

size

default int size()

Returns the number of elements in this FiniteIterable.

If this FiniteIterable contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Returns:

the number of elements in this FiniteIterable

slide

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

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

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

Specified by:

slide in interface EnhancedIterable<A>

Parameters:

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

Returns:

a FiniteIterable<NonEmptyFiniteIterable<A>>

span

default com.jnape.palatable.lambda.adt.hlist.Tuple2<? extends FiniteIterable<A>,? extends FiniteIterable<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 FiniteIterable matching a predicate and the second slot is all the remaining elements.

Specified by:

span in interface EnhancedIterable<A>

Parameters:

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

Returns:

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

tails

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

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

Specified by:

tails in interface EnhancedIterable<A>

Returns:

an ImmutableNonEmptyIterable<FiniteIterable<A>>

takeWhile

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

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

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

Specified by:

takeWhile in interface EnhancedIterable<A>

Parameters:

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

Returns:

a FiniteIterable<A>

toFinite

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

Always succeeds because FiniteIterables are always finite.

Specified by:

toFinite in interface EnhancedIterable<A>

Returns:

this FiniteIterable wrapped in a `just`

toNonEmpty

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

Converts this FiniteIterable to a NonEmptyFiniteIterable if it contains one or more elements.

Specified by:

toNonEmpty in interface EnhancedIterable<A>

Returns:

a Maybe<NonEmptyFiniteIterable<A>

zipWith

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

Zips together this FiniteIterable 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.

Specified by:

zipWith in interface EnhancedIterable<A>

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 FiniteIterable<C>

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>

emptyFiniteIterable

static <A> ImmutableFiniteIterable<A> emptyFiniteIterable()

Creates an empty FiniteIterable.

Type Parameters:

A - the element type

Returns:

an ImmutableFiniteIterable<A>

finiteIterable

static <A> FiniteIterable<A> finiteIterable(java.util.Collection<A> collection)

Creates a FiniteIterable by wrapping a Collection.

Does not make a copy of the Collection.

Type Parameters:

A - the element type

Parameters:

collection - the source Collection

Returns:

a FiniteIterable<A>

finiteIterable

static <A> FiniteIterable<A> finiteIterable(int maxCount,
                                            java.lang.Iterable<A> iterable)

Creates a FiniteIterable by wrapping an Iterable.

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.

iterable - the source Iterable

Returns:

a FiniteIterable<A>

of

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

Creates a FiniteIterable containing the given elements.

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

Type Parameters:

A - the element type

Parameters:

first - the first element

more - the remaining elements

Returns:

an ImmutableNonEmptyFiniteIterable<A>