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__leneven 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 tablemethods withstdenhanced 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 __lenwhen 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:- ls table list of lists
 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:- t table any table
 Returns:- 
           boolean
        
 trueif t is empty, otherwisefalseUsage: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"} 
- t
            table
          a table 
- 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 __lenmetamethod 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"} 
- t
            table
         a table with 
- keys (t)
- 
    Make the list of keys in table.
    Parameters:- t table a table
 Returns:- 
           table
        list of keys from t
    
 See also:Usage:globals = keys (_G) 
- len (t)
- 
    Equivalent to #operation, but respecting__leneven on Lua 5.1.Parameters:- t table a table
 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:- t table a table
 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 trueor ":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 trueor ":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 tablemethods withstdenhanced 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: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 __lenwhen 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 
 nilUsage:--> {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: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:- 
           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:- t table any table
 Returns:- 
           table
        list of values in t
    
 See also:Usage:--> {"a", "c", 42} values {"a", b="c", [-1]=42}