Any table that has an __iter metamethod
@eryx/iter Module
Utilities for working with sequence-like data through a small iterator API.
Functions in this module accept three kinds of iterable input:
- Dense array-like tables such as
{ "a", "b", "c" } - Simple iterator functions of the form
() -> (index?, value) - Tables or userdata with an
__itermetamethod
Most transforming helpers return a SimpleIterator, which is a stateful
iterator function yielding (index, value) pairs until it returns nil.
Use this module when you want to write code against "something iterable"
without caring whether the source is an array, an iterator callback, or a
custom object with __iter.
Sequence-style transforms such as filter, unique, and reverse produce
dense array-like results or dense iterator indices. flatten, by contrast,
preserves the yielded numeric keys from the underlying iterable.
The iter.Iterable<T, any> type can be used to describe any iterable
sequence that results in items of type T. iter.SimpleIterator<T> on the
other hand describes the iterator types returned by these functions.
local iter = require("@eryx/iter")
local evens = iter.filter({ 1, 2, 3, 4, 5, 6 }, function(value)
return value % 2 == 0
end)
for index, value in evens do
print(index, value) -- 1 2, then 2 4, then 3 6
end
local iter = require("@eryx/iter")
local values = iter.reverse(
iter.unique(
iter.map({ "pear", "apple", "pear", "plum" }, string.upper)
)
)
print(values) -- { "PLUM", "APPLE", "PEAR" }
Summary
Classes
Functions
API Reference
Classes
MetaIterator<T, Invariant>
Properties
Functions
iter.map
Lazily maps each item in an iterable.
Parameters
Iterable source to read from.
mapper: ((T) → U)
Transform applied to each yielded value.
Returns
Iterator that yields the original index with the mapped value.
iter.filter
Lazily filters an iterable by predicate.
Matching items are reindexed densely from 1.
Parameters
Iterable source to read from.
Predicate used to decide whether an item should be yielded.
Returns
Iterator that yields only items matching filter.
iter.forEach
Calls a function on every item in an iterable
Parameters
iter.flatten
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.
Parameters
Iterable source to flatten.
Returns
{ T }
Array containing all yielded values, keyed by their yielded indices.
iter.tableIterator
Converts an array into a stateful iterator function.
Parameters
array: { T }
Array to iterate over.
Returns
Iterator that yields sequential array indices and values.
iter.reverse
Returns a reversed array. Table inputs may be reversed in place; iterator inputs are collected densely first.
Parameters
Iterable source to reverse.
Returns
{ T }
Reversed array.
Parameters
iterable: { T }
Iterable source to reverse.
When true reverse the table in place.
Returns
{ T }
Reversed array.
iter.unique
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.
Parameters
Iterable source to deduplicate.
Returns
Iterator that skips values that have already been seen.
iter.find
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.
Parameters
iterable: { T }
Iterable source to search.
Predicate used to test each item.
Starting index.
Returns
Matching index and value, or nil if no match is found.
iter.find<T, I>(iterable: SimpleIterator<T> | MetaIterator<T, I>, match: ((T) → boolean)) → (number?, T)
Parameters
Iterable source to search.
Predicate used to test each item.
Returns
Matching index and value, or nil if no match is found.
iter.reduce
Reduces an iterable into a single value.
Parameters
Iterable source to reduce.
reducer: ((U, T) → U)
Accumulator function called with the current reduced value and next item.
initial: U
Initial accumulator value.
Returns
U
Final reduced value.
iter.all
Returns whether every item in the iterable matches a predicate.
Parameters
Iterable source to test.
Predicate used to test each item.
Returns
true when all yielded items match, otherwise false.
iter.any
Returns whether any item in the iterable matches a predicate.
Parameters
Iterable source to test.
Predicate used to test each item.
Returns
true when any yielded item matches, otherwise false.
Types
SimpleIterator<T>
A stateful iterator function yielding (index, value) pairs until it returns nil.