stdlib 41.2.3 Reference

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

  - merge
  - clone_select

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

  - clone
  - merge_select

  ### Usage:

      partialcopy = clone_select (original, {"this", "and_this"}, true)

depair (ls)
  Turn a list of pairs into a table.

  ### Parameters:

  - ls table list of lists

  ### Returns:

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

  ### See also:

  enpair

  ### Usage:

      --> {a=1, b=2, c=3}
      depair {{"a", 1}, {"b", 2}, {"c", 3}}

empty (t)
  Return whether table is empty.

  ### Parameters:

  - t table any table

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

  depair

  ### Usage:

      --> {{1, "a"}, {2, "b"}, {3, "c"}}
      enpair {"a", "b", "c"}

flatten (t)
  Flatten a nested table into a list.

  ### Parameters:

  - t table a table

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

  - t table a table

  ### Returns:

  table list of keys from *t*

  ### See also:

  - okeys
  - values

  ### Usage:

      globals = keys (_G)

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

  ### Parameters:

  - t table a table

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

  - t table a table

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

  - clone
  - merge_select

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

  - merge
  - clone_select

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

  - t table a table

  ### Returns:

  table ordered list of keys from *t*

  ### See also:

  keys

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

  - t table any table

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

  - t table any table

  ### Returns:

  table list of values in *t*

  ### See also:

  keys

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

  sort

  ### 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