Module std.table

Extensions to the core table module.

The module table returned by `std.table` also contains all of the entries from the core table module. An hygienic way to import this module, then, is simply to override the core `table` locally:

local table = require "std.table"

Functions

clone (t[, map={}[, nometa]]) Make a shallow copy of a table, including any metatable.
clone_select (t[, keys={}[, nometa]]) Make a partial clone of a table.
depair (ls) Turn a list of pairs into a table.
empty (t) Return whether table is empty.
enpair (t) Turn a table into a list of pairs.
flatten (t) Flatten a nested table into a list.
insert (t[, pos=len (t)], v) Enhance core *table.insert* to return its result.
invert (t) Invert a table.
keys (t) Make the list of keys in table.
len (t) Equivalent to `#` operation, but respecting `__len` even on Lua 5.1.
maxn (t) Largest integer key in a table.
merge (t, u[, map={}[, nometa]]) Destructively merge another table's fields into another.
merge_select (t, u[, keys={}[, nometa]]) Destructively merge another table's named fields into *table*.
monkey_patch ([namespace=_G]) Overwrite core `table` methods with `std` enhanced versions.
new ([x=nil[, t={}]]) Make a table with a default value for unset keys.
okeys (t) Make an ordered list of keys in table.
pack (...) Turn a tuple into a list.
project (fkey, tt) Project a list of fields from a list of tables.
remove (t[, pos=len (t)]) Enhance core *table.remove* to respect `__len` when *pos* is omitted.
shape (dims, t) Shape a table according to a list of dimensions.
size (t) Find the number of elements in a table.
sort (t[, c=std.operator.lt]) Enhance core *table.sort* to return its result.
unpack (t[, i=1[, j=table.maxn(t)]]) Enhance core *table.unpack* to always unpack up to `maxn (t)`.
values (t) Make the list of values of a table.

Types

comparator (a, b) Signature of a sort comparator function.


Functions

Methods
clone (t[, map={}[, nometa]])
Make a shallow copy of a table, including any metatable.

To make deep copies, use tree.clone.

Parameters:

  • t table source table
  • map table table of `{old_key=new_key, ...}` (default {})
  • nometa table if non-nil don't copy metatable (optional)

Returns:

    copy of *t*, also sharing *t*'s metatable unless *nometa* is true, and with keys renamed according to *map*

See also:

Usage:

    shallowcopy = clone (original, {rename_this = "to_this"}, ":nometa")
clone_select (t[, keys={}[, nometa]])
Make a partial clone of a table.

Like `clone`, but does not copy any fields by default.

Parameters:

  • t table source table
  • keys table list of keys to copy (default {})
  • nometa table if non-nil don't copy metatable (optional)

Returns:

    table copy of fields in *selection* from *t*, also sharing *t*'s metatable unless *nometa*

See also:

Usage:

    partialcopy = clone_select (original, {"this", "and_this"}, true)
depair (ls)
Turn a list of pairs into a table.

Parameters:

Returns:

    table a flat table with keys and values from *ls*

See also:

Usage:

    --> {a=1, b=2, c=3}
depair {{"a", 1}, {"b", 2}, {"c", 3}}
empty (t)
Return whether table is empty.

Parameters:

Returns:

    table `true` if *t* is empty, otherwise `false`

Usage:

    if empty (t) then error "ohnoes" end
enpair (t)
Turn a table into a list of pairs.

Parameters:

  • t table a table `{i1=v1, ..., in=vn}`

Returns:

    table a new list of pairs containing `{{i1, v1}, ..., {in, vn}}`

See also:

Usage:

    --> {{1, "a"}, {2, "b"}, {3, "c"}}
enpair {"a", "b", "c"}
flatten (t)
Flatten a nested table into a list.

Parameters:

Returns:

    table a list of all non-table elements of *t*

Usage:

    --> {1, 2, 3, 4, 5}
flatten {{1, {{2}, 3}, 4}, 5}
insert (t[, pos=len (t)], v)
Enhance core *table.insert* to return its result. If *pos* is not given, respect `__len` metamethod when calculating default append. Also, diagnose out of bounds *pos* arguments consistently on any supported version of Lua.

Parameters:

  • t table a table
  • pos table index at which to insert new element (default len (t))
  • v value to insert into *t*

Returns:

    table *t*

Usage:

    --> {1, "x", 2, 3, "y"}
insert (insert ({1, 2, 3}, 2, "x"), "y")
invert (t)
Invert a table.

Parameters:

  • t table a table with `{k=v, ...}`

Returns:

    table inverted table `{v=k, ...}`

Usage:

    --> {a=1, b=2, c=3}
invert {"a", "b", "c"}
keys (t)
Make the list of keys in table.

Parameters:

Returns:

    table list of keys from *t*

See also:

Usage:

    globals = keys (_G)
len (t)
Equivalent to `#` operation, but respecting `__len` even on Lua 5.1.

Parameters:

Returns:

    table length of list part of *t*

Usage:

    for i = 1, len (t) do process (t[i]) end
maxn (t)
Largest integer key in a table.

Parameters:

Returns:

    table largest integer key in *t*

Usage:

    --> 42
maxn {"a", b="c", 99, [42]="x", "x", [5]=67}
merge (t, u[, map={}[, nometa]])
Destructively merge another table's fields into another.

Parameters:

  • t table destination table
  • u table table with fields to merge
  • map table table of `{old_key=new_key, ...}` (default {})
  • nometa table if `true` or ":nometa" don't copy metatable (optional)

Returns:

    table *t* with fields from *u* merged in

See also:

Usage:

    merge (_G, require "std.debug", {say = "log"}, ":nometa")
merge_select (t, u[, keys={}[, nometa]])
Destructively merge another table's named fields into *table*.

Like `merge`, but does not merge any fields by default.

Parameters:

  • t table destination table
  • u table table with fields to merge
  • keys table list of keys to copy (default {})
  • nometa table if `true` or ":nometa" don't copy metatable (optional)

Returns:

    table copy of fields in *selection* from *t*, also sharing *t*'s metatable unless *nometa*

See also:

Usage:

    merge_select (_G, require "std.debug", {"say"}, false)
monkey_patch ([namespace=_G])
Overwrite core `table` methods with `std` enhanced versions.

Parameters:

  • namespace table where to install global functions (default _G)

Returns:

    table the module table

Usage:

    local table = require "std.table".monkey_patch ()
new ([x=nil[, t={}]])
Make a table with a default value for unset keys.

Parameters:

  • x default entry value (default nil)
  • t table initial table (default {})

Returns:

    table table whose unset elements are *x*

Usage:

    t = new (0)
okeys (t)
Make an ordered list of keys in table.

Parameters:

Returns:

    table ordered list of keys from *t*

See also:

Usage:

    globals = keys (_G)
pack (...)
Turn a tuple into a list.

Parameters:

  • ... tuple

Returns:

    list

Usage:

    --> {1, 2, "ax"}
pack (("ax1"):find "(%D+)")
project (fkey, tt)
Project a list of fields from a list of tables.

Parameters:

  • fkey field to project
  • tt table a list of tables

Returns:

    table list of *fkey* fields from *tt*

Usage:

    --> {1, 3, "yy"}
project ("xx", {{"a", xx=1, yy="z"}, {"b", yy=2}, {"c", xx=3}, {xx="yy"})
remove (t[, pos=len (t)])
Enhance core *table.remove* to respect `__len` when *pos* is omitted. Also, diagnose out of bounds *pos* arguments consistently on any supported version of Lua.

Parameters:

  • t table a table
  • pos table index from which to remove an element (default len (t))

Returns:

    removed value, or else `nil`

Usage:

    --> {1, 2, 5}
t = {1, 2, "x", 5}
remove (t, 3) == "x" and t
shape (dims, t)
Shape a table according to a list of dimensions.

Dimensions are given outermost first and items from the original list are distributed breadth first; there may be one 0 indicating an indefinite number. Hence, `{0}` is a flat list, `{1}` is a singleton, `{2, 0}` is a list of two lists, and `{0, 2}` is a list of pairs.

Algorithm: turn shape into all positive numbers, calculating the zero if necessary and making sure there is at most one; recursively walk the shape, adding empty tables until the bottom level is reached at which point add table items instead, using a counter to walk the flattened original list.

Parameters:

  • dims table table of dimensions `{d1, ..., dn}`
  • t table a table of elements

Returns:

    reshaped list

Usage:

    --> {{"a", "b"}, {"c", "d"}, {"e", "f"}}
shape ({3, 2}, {"a", "b", "c", "d", "e", "f"})
size (t)
Find the number of elements in a table.

Parameters:

Returns:

    table number of non-nil values in *t*

Usage:

    --> 3
size {foo = true, bar = true, baz = false}
sort (t[, c=std.operator.lt])
Enhance core *table.sort* to return its result.

Parameters:

  • t table unsorted table
  • c comparator ordering function callback (default std.operator.lt)

Returns:

    *t* with keys sorted accordind to *c*

Usage:

    table.concat (sort (object))
unpack (t[, i=1[, j=table.maxn(t)]])
Enhance core *table.unpack* to always unpack up to `maxn (t)`.

Parameters:

  • t table table to act on
  • i table first index to unpack (default 1)
  • j table last index to unpack (default table.maxn(t))

Returns:

    ... values of numeric indices of *t*

Usage:

    return unpack (results_table)
values (t)
Make the list of values of a table.

Parameters:

Returns:

    table list of values in *t*

See also:

Usage:

    --> {"a", "c", 42}
values {"a", b="c", [-1]=42}

Types

comparator (a, b)
Signature of a sort comparator function.

Parameters:

  • a any object
  • b any object

Returns:

    table `true` if *a* sorts before *b*, otherwise `false`

See also:

Usage:

    local reversor = function (a, b) return a > b end
sort (t, reversor)
generated by LDoc 1.5.0 Last updated 2026-07-25 13:31:42