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'

Core Functions

insert (t[, pos=len(t)], v) Enhance core table.insert to return its result.
maxn (t) Largest integer key in a table.
pack (...) Turn a tuple into a list, with tuple-size in field n
remove (t[, pos=len(t)]) Enhance core table.remove to respect __len when pos is omitted.
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 __len or maxn.

Deprecated Functions

flatten (t) Flatten a nested table into a list.
len (t) Find the length of the sequence part of a table, up to the first nil valued element, respecting any __len metamethod.
monkey_patch ([namespace=_G]) Overwrite core table functions with std enhanced versions.
okeys (t) Make an ordered list of keys in table.
shape (dims, t) Shape a table according to a list of dimensions.

Types

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

Accessor 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.
enpair (t) Turn a table into a list of pairs.
empty (t) Return whether table is empty.
new ([x=nil[, t={}]]) Make a table with a default value for unset keys.
project (fkey, tt) Project a list of fields from a list of tables.
size (t) Find the number of elements in a table.
values (t) Make the list of values of a table.

Mutator Functions

invert (t) Invert a table.
keys (t) Make the list of keys in table.
merge (t, u[, map={}[, nometa]]) Destructively merge one table's fields into another.
merge_select (t, u[, keys={}[, nometa]]) Destructively merge another table's named fields into table.


Core Functions

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 integer 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')
maxn (t)
Largest integer key in a table.

Parameters:

Returns:

    int largest integer key in t

Usage:

    --> 42
maxn {'a', b='c', 99, [42]='x', 'x', [5]=67}
pack (...)
Turn a tuple into a list, with tuple-size in field n

Parameters:

  • ... tuple

Returns:

    list-like table, with tuple-size in field n

Usage:

    --> {1, 2, 'ax', n=3}
pack(find('ax1', '(%D+)'))
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 integer 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
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 according to c

Usage:

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

Parameters:

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

Returns:

    ... values of numeric indices of t

Usage:

    return unpack(results_table)

Deprecated Functions

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}
len (t)
Find the length of the sequence part of a table, up to the first nil valued element, respecting any __len metamethod.

Parameters:

Returns:

    int length of t

Usage:

    --> 3
len {1, 2, 3}
monkey_patch ([namespace=_G])
Overwrite core table functions with std enhanced versions.

Parameters:

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

Returns:

    table the module table

Usage:

    require 'std.table'.monkey_patch()
okeys (t)
Make an ordered list of keys in table.

Parameters:

Returns:

    table ordered list of keys from t

Usage:

    globals = okeys(_G)
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.

Parameters:

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

Returns:

    reshaped list

Usage:

    --> {{1, 2, 3}, {4, 5, 6}}
shape({2, 3}, {1, 2, 3, 4, 5, 6})

Types

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

Parameters:

  • a any object
  • b any object

Returns:

    boolean true if a sorts before b, otherwise false

See also:

Usage:

    local reversor = function(a, b) return a > b end
sort(t, reversor)

Accessor Functions

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

Parameters:

  • t table source table
  • map table table of {old_key=new_key, ...} (default {})
  • nometa boolean 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 boolean 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}}
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'}
empty (t)
Return whether table is empty.

Parameters:

Returns:

    boolean true if t is empty, otherwise false

Usage:

    if empty(t) then error 'ohnoes' end
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)
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'})
size (t)
Find the number of elements in a table.

Parameters:

Returns:

    int number of non-nil values in t

Usage:

    --> 3
size {foo=true, bar=true, baz=false}
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}

Mutator Functions

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)
merge (t, u[, map={}[, nometa]])
Destructively merge one 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 boolean 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 boolean 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)
generated by LDoc 1.5.0 Last updated 2026-10-22 19:02:37