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 bool 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 bool 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:

    boolean 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 int 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:

    int 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:

    int 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 bool 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 bool 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 int 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:

    int 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 int first index to unpack (default 1)
  • j int 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:

    boolean 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.4.3 Last updated 2018-09-03 17:48:42