Module std.functional

Functional programming.

A selection of higher-order functions to enable a functional style of programming in Lua.

Functions

bind (fn, argt) Partially apply a function.
callable (x) Identify callable types.
case (with, branches) A rudimentary case statement.
collect ([ifn=std.npairs], ...) Collect the results of an iterator.
compose (...) Compose functions.
cond (expr, branch, ...) A rudimentary condition-case statement.
curry (fn, n) Curry a function.
filter (pfn[, ifn=std.pairs], ...) Filter an iterator with a predicate.
foldl (fn[, d=t[1], t) Fold a binary function left associatively.
foldr (fn[, d=t[1], t) Fold a binary function right associatively.
id (...) Identity function.
lambda (s) Compile a lambda string into a Lua function.
map (fn[, ifn=std.pairs], ...) Map a function over an iterator.
map_with (fn, tt) Map a function over a table of argument lists.
memoize (fn[, normfn=std.tostring]) Memoize a function, by wrapping it in a functable.
nop () No operation.
reduce (fn, d[, ifn=std.pairs], ...) Fold a binary function into an iterator.
zip (tt) Zip a table of tables.
zip_with (fn, tt) Zip a list of tables together with a function.

Types

normalize (...) Signature of a memoize argument normalization callback function.
predicate (...) Signature of a filter predicate callback function.


Functions

Methods
bind (fn, argt)
Partially apply a function.

Parameters:

  • fn table function to apply partially
  • argt table table of *fn* arguments to bind

Returns:

    function with *argt* arguments already bound

Usage:

    cube = bind (std.operator.pow, {[2] = 3})
callable (x)
Identify callable types.

Parameters:

  • x an object or primitive

Returns:

    `true` if *x* can be called, otherwise `false`

Usage:

    if callable (functable) then functable (args) end
case (with, branches)
A rudimentary case statement. Match *with* against keys in *branches* table.

Parameters:

  • with expression to match
  • branches table map possible matches to functions

Returns:

    the value associated with a matching key, or the first non-key value if no key matches. Function or functable valued matches are called using *with* as the sole argument, and the result of that call returned; otherwise the matching value associated with the matching key is returned directly; or else `nil` if there is no match and no default.

See also:

Usage:

    return case (type (object), {
  table  = "table",
  string = function ()  return "string" end,
           function (s) error ("unhandled type: " .. s) end,
})
collect ([ifn=std.npairs], ...)
Collect the results of an iterator.

Parameters:

  • ifn table iterator function (default std.npairs)
  • ... *ifn* arguments

Returns:

    table of results from running *ifn* on *args*

See also:

Usage:

    --> {"a", "b", "c"}
collect {"a", "b", "c", x=1, y=2, z=5}
compose (...)
Compose functions.

Parameters:

  • ... table functions to compose

Returns:

    table composition of fnN .. fn1: note that this is the reverse of what you might expect, but means that code like:

    functional.compose (function (x) return f (x) end, function (x) return g (x) end))

    can be read from top to bottom.

Usage:

    vpairs = compose (table.invert, ipairs)
for v, i in vpairs {"a", "b", "c"} do process (v, i) end
cond (expr, branch, ...)
A rudimentary condition-case statement. If *expr* is "truthy" return *branch* if given, otherwise *expr* itself. If the return value is a function or functable, then call it with *expr* as the sole argument and return the result; otherwise return it explicitly. If *expr* is "falsey", then recurse with the first two arguments stripped.

Parameters:

  • expr a Lua expression
  • branch a function, functable or value to use if *expr* is "truthy"
  • ... additional arguments to retry if *expr* is "falsey"

See also:

Usage:

    -- recursively calculate the nth triangular number
function triangle (n)
  return cond (
    n <= 0, 0,
    n == 1, 1,
            function () return n + triangle (n - 1) end)
end
curry (fn, n)
Curry a function.

Parameters:

  • fn table function to curry
  • n table number of arguments

Returns:

    table curried version of *fn*

Usage:

    add = curry (function (x, y) return x + y end, 2)
incr, decr = add (1), add (-1)
filter (pfn[, ifn=std.pairs], ...)
Filter an iterator with a predicate.

Parameters:

  • pfn predicate predicate function
  • ifn predicate iterator function (default std.pairs)
  • ... iterator arguments

Returns:

    table elements e for which `pfn (e)` is not "falsey".

See also:

Usage:

    --> {2, 4}
filter (lambda '|e|e%2==0', std.elems, {1, 2, 3, 4})
foldl (fn[, d=t[1], t)
Fold a binary function left associatively. If parameter *d* is omitted, the first element of *t* is used, and *t* treated as if it had been passed without that element.

Parameters:

  • fn table binary function
  • d initial left-most argument (default t[1)
  • t table a table

Returns:

    result

See also:

Usage:

    foldl (std.operator.quot, {10000, 100, 10}) == (10000 / 100) / 10
foldr (fn[, d=t[1], t)
Fold a binary function right associatively. If parameter *d* is omitted, the last element of *t* is used, and *t* treated as if it had been passed without that element.

Parameters:

  • fn table binary function
  • d initial right-most argument (default t[1)
  • t table a table

Returns:

    result

See also:

Usage:

    foldr (std.operator.quot, {10000, 100, 10}) == 10000 / (100 / 10)
id (...)
Identity function.

Parameters:

  • ... arguments

Returns:

    *arguments*
lambda (s)
Compile a lambda string into a Lua function.

A valid lambda string takes one of the following forms:

1. `'=expression'`: equivalent to `function (...) return expression end` 1. `'|args|expression'`: equivalent to `function (args) return expression end`

The first form (starting with `'='`) automatically assigns the first nine arguments to parameters `'_1'` through `'_9'` for use within the expression body. The parameter `'_1'` is aliased to `'_'`, and if the first non-whitespace of the whole expression is `'_'`, then the leading `'='` can be omitted.

The results are memoized, so recompiling a previously compiled lambda string is extremely fast.

Parameters:

Returns:

    string compiled lambda string, can be called like a function

Usage:

    -- The following are equivalent:
lambda '= _1 < _2'
lambda '|a,b| a<b'
map (fn[, ifn=std.pairs], ...)
Map a function over an iterator.

Parameters:

  • fn string map function
  • ifn string iterator function (default std.pairs)
  • ... iterator arguments

Returns:

    table results

See also:

Usage:

    --> {1, 4, 9, 16}
map (lambda '=_1*_1', std.ielems, {1, 2, 3, 4})
map_with (fn, tt)
Map a function over a table of argument lists.

Parameters:

  • fn table map function
  • tt table a table of *fn* argument lists

Returns:

    table new table of *fn* results

See also:

Usage:

    --> {"123", "45"}, {a="123", b="45"}
conc = bind (map_with, {lambda '|...|table.concat {...}'})
conc {{1, 2, 3}, {4, 5}}, conc {a={1, 2, 3, x="y"}, b={4, 5, z=6}}
memoize (fn[, normfn=std.tostring])
Memoize a function, by wrapping it in a functable.

To ensure that memoize always returns the same results for the same arguments, it passes arguments to *fn*. You can specify a more sophisticated function if memoize should handle complicated argument equivalencies.

Parameters:

  • fn table pure function: a function with no side effects
  • normfn normalize function to normalize arguments (default std.tostring)

Returns:

    normalize memoized function

Usage:

    local fast = memoize (function (...) --[[ slow code ]] end)
nop ()
No operation. This function ignores all arguments, and returns no values.

See also:

Usage:

    if unsupported then vtable["memrmem"] = nop end
reduce (fn, d[, ifn=std.pairs], ...)
Fold a binary function into an iterator.

Parameters:

  • fn normalize reduce function
  • d initial first argument
  • ifn normalize iterator function (default std.pairs)
  • ... iterator arguments

Returns:

    result

See also:

Usage:

    --> 2 ^ 3 ^ 4 ==> 4096
reduce (std.operator.pow, 2, std.ielems, {3, 4})
zip (tt)
Zip a table of tables. Make a new table, with lists of elements at the same index in the original table. This function is effectively its own inverse.

Parameters:

  • tt table a table of tables

Returns:

    table new table with lists of elements of the same key from *tt*

See also:

Usage:

    --> {{1, 3, 5}, {2, 4}}, {a={x=1, y=3, z=5}, b={x=2, y=4}}
zip {{1, 2}, {3, 4}, {5}}, zip {x={a=1, b=2}, y={a=3, b=4}, z={a=5}}
zip_with (fn, tt)
Zip a list of tables together with a function.

Parameters:

  • fn table function
  • tt table table of tables

Returns:

    table a new table of results from calls to *fn* with arguments made from all elements the same key in the original tables; effectively the "columns" in a simple list of lists.

See also:

Usage:

    --> {"135", "24"}, {a="1", b="25"}
conc = bind (zip_with, {lambda '|...|table.concat {...}'})
conc {{1, 2}, {3, 4}, {5}}, conc {{a=1, b=2}, x={a=3, b=4}, {b=5}}

Types

normalize (...)
Signature of a memoize argument normalization callback function.

Parameters:

  • ... arguments

Returns:

    string normalized arguments

Usage:

    local normalize = function (name, value, props) return name end
local intern = std.functional.memoize (mksymbol, normalize)
predicate (...)
Signature of a filter predicate callback function.

Parameters:

  • ... arguments

Returns:

    string "truthy" if the predicate condition succeeds, "falsey" otherwise

Usage:

    local predicate = lambda '|k,v|type(v)=="string"'
local strvalues = filter (predicate, std.pairs, {name="Roberto", id=12345})
generated by LDoc 1.5.0 Last updated 2026-07-25 13:31:42