class IterableTools

Returns true if all elements of as satisfy a predicate

[true, true, true].all(isTrue) == true;
[true, false, true].all(isTrue) == false;

Returns true if corresponding pairs of as and bs satisfy a predicate

[1, 2, 3].all2([1, 2, 3], equals) == true;
[1, 2, 3].all2([4, 2, 0], equals) == false;

Returns true if every element is true or if bs is empty

Returns true if as is not empty

Returns true if any element in as matches a predicate
NOTE: This will evaluate as until a match is found or as is exhausted, so be careful with infinite Iterables

Experimental
Apply a set of functions to each element of as. Can be called repeatedly if the return type is a function.

[ a -> b -> a + b
, a -> b -> a - b
].ap([1, 2])
 .ap([3, 4])

   | --------- a + b  -------- | --------  a - b  ------- |  
== [(1+3), (1+4), (2+3), (2+4), (1-3), (1-4), (2-3), (2-4)]  
== [  4,     5,     5,     6,    -2,    -3,    -1,    -2]

Returns a new Iterable that appends with onto the end of as

[1, 2, 3].append([4, 5, 6]) == [1, 2, 3, 4, 5, 6];

See also:

• Lambda.concat

Converts a single element to an Iterable containing that element
TODO: should this return Iterable1?

If as has any elements, returns the element at a positive index
Wraps around to the beginning if index is out of bounds

[1, 2, 3].atWrappedIndex(1)     == Some(2);
[1, 2, 3].atWrappedUndex(10)    == Some(2);
[1].atWrappedIndex(100)         == Some(1);
[].atWrappedIndex(1000)         == None;

If possible, draws a random element from as, using genRandom as a source of randomness

If possible, draws a random element from as, using Math.random as a source of randomness

Adds a value to the front of an Iterable

Returns true if a is present in as
NOTE: This will evaluate as until if finds a or as is exhausted,
so be careful with infinite Iterables

Counts the number of elements in as

    *NOTE*: This will fully evaluate `as`, so be careful with infinite `Iterable`s

Infinitely repeats an Iterable

[6, 9].cycle() == [6, 9, 6, 9, 6, ...];

A lazy unfold operation, which produces an Iterable from an initial seed. The opposite of foldl (which reduces an Iterable to a single value)

(x -> x == 0 
    ? None
    : Some(x.with(x - 1))
).distribute(5)

== [5, 4, 3, 2, 1]

If possible, returns an element from as at a specified index

[1, 2, 3].elementAt(1)  == Some(2);
[1, 2, 3].elementAt(10) == None;
[].elementAt(100)       == None;

Returns an empty Iterable

An alternative to indexed. Pairs every element of as with its index

Splits as into chunks of size n
If n <= 0, returns an empty Iterable

Returns elements of as that are not equal to except

Returns elements of as that do not appear in except

A fused combination of filter and flatMap

Returns elements of as that satisfy some predicate

A fused combination of filter and map

If possible, returns the first value of as that matches some predicate
NOTE: This will evaluate as until it finds a match or as is exhausted, so be careful with infinite Iterables

Returns the first element of as or a default value if as is empty

Projects each element of as into an Iterable of Bs using fn as a transform, and flattens the results into a single Iterable
This version is lazy

[1, 2, 3].flatMap(x -> x.replicate(3)) == [1, 1, 1, 2, 2, 2, 3, 3, 3];

See also:

• Lambda.flatMap

Projects each element of as into an Iterable of Bs using fn as a transform, and flattens the results into a single Iterable
This version is strict

[1, 2, 3].flatMapS(x -> x.replicate(3)) == [1, 1, 1, 2, 2, 2, 3, 3, 3];

See also:

• Lambda.flatMap

Appends one level of nested Iterables together

[[1, 2, 3], [4, 5, 6], [7, 8, 9]].flatten() == [1, 2, 3, 4, 5, 6, 7, 8, 9];
[].flatten() == [];

Applies fn over elements of as using seed as an initial value, reducing an Iterable to a single value. This version is left-associative

[1, 2, 3, 4, 5].foldl(0, (x, y) -> x + y) == 0+1+2+3+4+5 == 15;
[].foldl(0, (x, y) -> x + y) == 0;

NOTE: This may not terminate with an infinite Iterable

See also:

• Lambda.fold

Applies fn over elements of as using seed as an initial value, reducing an Iterable to a single value. This version is right-associative

[1, 2, 3, 4, 5].foldl(0, (x, y) -> x + y) == 0+5+4+3+2+1 == 15;
[].foldr(0, (x, y) -> x + y) == 0;

NOTE: This may not terminate with an infinite Iterable

An alternative to enumerate. Converts a plain Iterable to one that maintains an index for each element.

Returns an Iterable containing every Int >= 0
In theory this is infinite; in practice it will overflow MAX_INT

Returns all elements of as except the last one

Inserts separator in between Iterables and flattens the result

[[1, 2], [3, 4], [5, 6]].intercalate([0, 0]) == [1, 2, 0, 0, 3, 4, 0, 0, 5, 6];

Returns an Iterable with separator interspersed between every element of as

[1, 2, 3, 4].intersperse(0) == [1, 0, 2, 0, 3, 0, 4];

Returns true iff as does not have any elements

Creates an infinite sequence of T values by applying fn to the first value, then to the result of that, then...

iterate(0, add1) == [x, f(x), f(f(x)), f(f(f(x))), ...] == [0, 1, 2, 3, 4, 5, ...];

If possible, returns the last value of as that matches some predicate
NOTE: This will evaluate as until it finds a match or as is exhausted, so be careful with infinite Iterables

Projects as into an Iterable of Bs using fn as a transform
This version is lazy

[1, 2, 3].mapL(Std.string) == ['1', '2', '3'];

See also:

• Lambda.map

A version of mapL that can discard elements. Only Some values are transformed and returned in the output.

A version of mapL that can discard elements. Only Success values are transformed and returned in the output.

Projects as into an Iterable of Bs using fn as a transform
This version is strict

[1, 2, 3].mapS(Std.string) == ['1', '2', '3']

See also:

• Lambda.map

Attempts to get the first element of as, if there is one

[a, b, c].maybeFirst() == Some(a);
[].maybeFirst() == None;

Attempts to get the last element of as, if there is one

[a, b, c].maybeLast() == Some(c);
[].maybeLast() == None;

NOTE: this will not terminate if as is infinite

Calls mutator on every element of as. Essentially a for loop specifically for mutating values

Calls mutator on every element of as and their indices. Essentially a for loop specifically for mutating values

Returns an infinite Iterable of natural numbers

natural() == [1, 2, 3, 4, 5, 6, ...];

Returns only the non-null elements of an Iterable

['a', null, 'b', null, 'c'].nonNull() == ['a', 'b', 'c']

Returns the input Iterable if it has any elements, or some default if empty

Returns the input Iterable if it has any elements, or some default if empty The default is required to have at least one element

Common use of zip, useful for comparing an element with the next one

[1, 2, 3, 4].pairs() == [(1, 2), (2, 3), (3, 4)];

Splits an Iterable into two subarrays based on a predicate

0.iterate(add1).partition(isEven) == ([0, 2, 4, ...], [1, 3, 5, ...]);

TODO: add a lazy version that doesn't evaluate the source list twice

Peeks at the next element of an Iterable without consuming it

[1, 2, 3].peek() == Some(1);

NOTE This will evaluate the next element, so be careful if evaulation causes side effects

Cartesian product of two Iterables
A deck of playing cards could be represented as suits.product(ranks, Card.new)

Returns an Iterable containing a range of numbers between start and start+count

0.range(5) == [0, 1, 2, 3, 4];

Returns an Iterable where a is infinitely repeated

Returns an Iterable where a is repeated count times

Applies fn to each element of as, passing an accumulator value through the computation
This version includes the seed as the first element of the output

[0, 1, 2, 3].scan(1, (x, y) -> x + y) == [1, 1, 2, 4, 7];

Applies fn to each element of as, passing an accumulator value through the computation
This version does not include the seed in the output

[0, 1, 2, 3].scan_(1, (x, y) -> x + y) == [1, 2, 4, 7];

Returns elements of as in a random order, using genRandom as a source of randomness

Returns elements of as in a random order, using Std.random as a source of randomness

Returns all of the elements of as after the first count items
If as has <= count items, return empty list

[a, b, c].skip(2) == [c];
[a, b, c].skip(200) == [];

Skips elements of as until they no longer match predicate
If all elements match, returns an empty Iterable

[1, 2, 3, 4].skipWhile(x -> x < 3) == [3, 4];
[1, 2, 3, 4].skipWhile(x -> x > 0) == [];

NOTE: This may not terminate if every element of an infinite Iterable matches the predicate

Returns all the Some values from a set of Options

Returns a Pair containing the longest prefix of as that match some predicate and the rest of the Iterable

[1, 2, 3, 4, 1, 2, 3].span(x -> x < 3) == ([1, 2], [3, 4, 1, 2, 3]);

Returns all the Success values from a set of Outcomes

Return all elements of an Iterable except the first one.
Returns [] if as is empty or only has one element

[1, 2, 3].tail() == [2, 3];
[1].tail() == [];
[].tail() == [];

Returns up to the first count elements of as
If as does not have >= count elements, it returns as many as it can

[a, b, c, d].take(2) == [a, b];
[].take(2) == [];

Returns elements from as until one is found that doesn't match predicate

[1, 2, 3, 4, 5, 6].takeWhile(x -> x < 4) == [1, 2, 3];

Converts an Iterable into an Array.
NOTE: Since this fully evaluates the Iterable, it may not terminate if as is infinite.

Returns Pairs of values from as and bs. If the two Iterables are not the same length, zip stops at the end of the shorter one

[1, 2, 3].zip(['a', 'b', 'c']) == [(1, 'a'), (2, 'b'), (3, 'c')]  ;
[1, 2, 3].zip([]) == [];

Applies a transform function to corresponsing pairs of elements in as and bs
If the Iterables don't have the same number of elements, zipWith will only apply until it reaches the end of the shorter one

[1, 2, 3].zipWith([4, 5, 6], (x, y) -> x + y) == [1+4, 2+5, 3+6] == [5, 7, 9];