@eryx/iter Module

Any table that has an __iter metamethod

Lazily maps each item in an iterable.

Lazily filters an iterable by predicate. Matching items are reindexed densely from 1.

Calls a function on every item in an iterable

Materializes an iterable into an array. Table inputs are returned directly without cloning. Iterator inputs preserve their yielded numeric keys, which may produce a sparse table.

Helper for writing coroutine.yield-based generators.

For example:

local function foo()
	return iter.generator(function()
		coroutine.yield(1)
		coroutine.yield(2)
		coroutine.yield(3)
	end)
end
for i in foo() do
	print(i)  -- Prints `1` then `2` then `3`
end

Converts an array into a stateful iterator function.

Returns a reversed array. Table inputs may be reversed in place; iterator inputs are collected densely first.

Lazily yields only the first occurrence of each distinct value. Yielded items are reindexed densely from 1. Duplicate detection is based on direct Lua equality and table-key semantics.

Finds the first item matching a predicate. For table inputs, start can be used to resume searching from a later index. For iterator inputs, calling this consumes items until a match is found or the iterator ends.

Reduces an iterable into a single value.

Returns whether every item in the iterable matches a predicate.

Returns whether any item in the iterable matches a predicate.

Yields successive n-length permutations of elements from items.

Order matters: { "a", "b" } and { "b", "a" } are distinct permutations. Each yielded value is a new array. When n equals #items (the default), every possible ordering of the whole sequence is produced.

for _, perm in iter.permutations({ "a", "b", "c" }) do
    print(table.concat(perm, ""))
    -- abc, acb, bac, bca, cab, cba
end

for _, perm in iter.permutations({ 1, 2, 3, 4 }, 2) do
    print(table.concat(perm, ""))
    -- 12, 13, 14, 21, 23, 24, 31, 32, 34, 41, 42, 43
end

Yields successive n-length combinations of elements from items, without replacement.

Order does not matter: { "a", "b" } and { "b", "a" } are the same combination and only the first is yielded. Combinations are emitted in lexicographic order relative to the position of each element in the source array. Each yielded value is a new array.

for _, combo in iter.combinations({ "a", "b", "c", "d" }, 2) do
    print(table.concat(combo, ""))
    -- ab, ac, ad, bc, bd, cd
end

Yields the Cartesian product of one or more arrays.

Each yielded tuple contains one element chosen from each input array, in the order the arrays were passed. The rightmost array advances fastest. If any input array is empty, no tuples are produced. Each yielded value is a new array.

for _, pair in iter.product({ "x", "y" }, { 1, 2, 3 }) do
    print(pair[1], pair[2])
    -- x 1, x 2, x 3, y 1, y 2, y 3
end

-- Repeating the same pool simulates combinations with replacement
for _, pair in iter.product({ 1, 2, 3 }, { 1, 2, 3 }) do
    print(pair[1], pair[2])
    -- 1 1, 1 2, 1 3, 2 1, 2 2, 2 3, 3 1, 3 2, 3 3
end

A stateful iterator function yielding (index, value) pairs until it returns nil.

An array, a SimpleIterator, or any value with an __iter metamethod.