Reducing

The section contains functions to analyze iteration values and recombine through use of a given combining operation the results of recursively processing its constituent parts, building up a return value

Note

An attempt to use infinity iterators with the most function from the module causes an infinite loop.

Folds

fun.foldl(accfun, initval, gen, param, state)
iterator:reduce(accfun, initval)
Parameters

  • accfun – an accumulating function

  • initval – an initial value that passed to accfun on the first iteration

The function reduces the iterator from left to right using the binary operator accfun and the initial value initval. Equivalent to:

local val = initval
for _k, ... in gen, param, state do
    val = accfun(val, ...)
end
return val

Examples:

> print(foldl(function(acc, x) return acc + x end, 0, range(5)))
15

> print(foldl(operator.add, 0, range(5)))
15

> print(foldl(function(acc, x, y) return acc + x * y; end, 0,
    zip(range(1, 5), {4, 3, 2, 1})))
20
fun.reduce(accfun, initval, gen, param, state)
iterator:reduce(accfun, initval)

An alias to foldl().

fun.length(gen, param, state)
iterator:length()

Return a number of remaining elements in gen, param, state iterator.

Examples:

> print(length({"a", "b", "c", "d", "e"}))
5

> print(length(drop_n(3, {"a", "b", "c", "d", "e"})))
2

> print(length({}))
0

> print(length(range(0)))
0

Warning

An attempt to call this function on an infinite iterator will result an infinite loop.

Note

This function has O(n) complexity for all iterators except basic array and string iterators, where it has O(1) complexity.

fun.totable(gen, param, state)
Returns

a new table (array) from iterated values.

The function reduces the iterator from left to right using table.insert.

Examples:

> local tab = totable("abcdef")
> print(type(tab), #tab)
table 6
> each(print, tab)
a
b
c
d
e
f
fun.tomap(gen, param, state)
Returns

a new table (map) from iterated values.

The function reduces the iterator from left to right using tab[val1] = val2 expression.

Examples:

> local tab = tomap(zip(range(1, 7), 'abcdef'))
> print(type(tab), #tab)
table   6
> each(print, iter(tab))
a
b
c
d
e
f

Predicates

fun.is_prefix_of(iterator1, iterator2)
iterator1:is_prefix_of(iterator2)

The function takes two iterators and returns true if the first iterator is a prefix of the second.

Examples:

> print(is_prefix_of({"a"}, {"a", "b", "c"}))
true

> print(is_prefix_of(range(6), range(5)))
false
fun.is_null(gen, param, state)
iterator:is_null()
Returns

true when gen, param, state` iterator is empty or finished.

Returns

false otherwise.

Example:

> print(is_null({"a", "b", "c", "d", "e"}))
false

> print(is_null({}))
true

> print(is_null(range(0)))
true
fun.all(predicate, gen, param, state)
iterator:all(predicate)
Parameters

predicate – a predicate

Returns true if all return values of iterator satisfy the predicate.

Examples:

> print(all(function(x) return x end, {true, true, true, true}))
true

> print(all(function(x) return x end, {true, true, true, false}))
false
fun.every(predicate, gen, param, state)

An alias for all().

fun.any(predicate, gen, param, state)
iterator:any(predicate)
Parameters

predicate – a predicate

Returns true if at least one return values of iterator satisfy the predicate. The iteration stops on the first such value. Therefore, infinity iterators that have at least one satisfying value might work.

Examples:

> print(any(function(x) return x end, {false, false, false, false}))
false

> print(any(function(x) return x end, {false, false, false, true}))
true
fun.some(predicate, gen, param, state)

An alias for any().

Special folds

fun.sum(gen, param, state)
iterator:sum()

Sum up all iteration values. An optimized alias for:

foldl(operator.add, 0, gen, param, state)

For an empty iterator 0 is returned.

Examples:

> print(sum(range(5)))
15
fun.product(gen, param, state)
iterator:product()

Multiply all iteration values. An optimized alias for:

foldl(operator.mul, 1, gen, param, state)

For an empty iterator 1 is returned.

Examples:

> print(product(range(1, 5)))
120
fun.min(gen, param, state)
iterator:min()

Return a minimum value from the iterator using operator.min() or < for numbers and other types respectively. The iterator must be non-null, otherwise an error is raised.

Examples:

> print(min(range(1, 10, 1)))
1

> print(min({"f", "d", "c", "d", "e"}))
c

> print(min({}))
error: min: iterator is empty
fun.minimum(gen, param, state)

An alias for min().

fun.min_by(cmp, gen, param, state)
iterator:min_by(cmp)

Return a minimum value from the iterator using the cmp as a < operator. The iterator must be non-null, otherwise an error is raised.

Examples:

> function min_cmp(a, b) if -a < -b then return a else return b end end
> print(min_by(min_cmp, range(1, 10, 1)))
9
fun.minimum_by(cmp, gen, param, state)

An alias for min_by().

fun.max(gen, param, state)
iterator:max()

Return a maximum value from the iterator using operator.max() or > for numbers and other types respectively.

The iterator must be non-null, otherwise an error is raised.

Examples:

> print(max(range(1, 10, 1)))
9

> print(max({"f", "d", "c", "d", "e"}))
f

> print(max({}))
error: max: iterator is empty
fun.maximum(gen, param, state)

An alias for max().

fun.max_by(cmp, gen, param, state)
iterator:max_by(cmp)

Return a maximum value from the iterator using the cmp as a > operator. The iterator must be non-null, otherwise an error is raised.

Examples:

> function max_cmp(a, b) if -a > -b then return a else return b end end
> print(max_by(max_cmp, range(1, 10, 1)))
1
fun.maximum_by(cmp, gen, param, state)

An alias for max_by().