Lua table functions
Lua table functions These are the functions in the "table" table. A table's size (which is only relevant for "numeric" indexed tables) is one less than the first integer index with a nil value. If the table has "holes" in it - that is, numeric keys with gaps in the sequence - then the table size is not guaranteed to be the the last gap. Lua does a binary search to try to find a gap, it does not necessarily find the first or last one. If you are planning to treat your tables as vectors (that is, with numeric keys and a size) then we recommend that you do not allow gaps in the sequence. If you want to know if a table is empty, or not, you can test:
    if next (t) == nil then
      -- table t is empty
    end -- if empty
table.concat (t, sep, start, end) Returns the (numeric) entries in the table t, concatenated together with "sep" as the separator, starting at index 'start' and ending at index 'end'. The entries are returned as a single string variable. Contrast this to the "unpack" function which returns a table as individual variables. Start defaults to 1 and end the table size. Sep defaults to an empty string.
    t = { "the", "quick", "brown", "fox" }
    print (table.concat (t, ';')) --> the;quick;brown;fox
table.foreach (t, f) Executes f for each element in table t. Function f is called with the arguments (key, value). If f returns a non-nil value the loop is broken, and this value is returned as the result from table.foreach. Effectively this could be used to find an element inside a table matching a certain condition.
    t = { "the", "quick", "brown", "fox", name = "Nick" }
    table.foreach (t, print)

     -->

    1 the
    2 quick
    3 brown
    4 fox
    name Nick
Warning the use of table.foreach is deprecated. This means it may not be available in future versions of Lua. You are recommended to rewrite such uses by using the 'pairs' function. table.foreachi (t, f) Similar to table.foreach, except that only numeric keys in the range 1 to n are processed.
    t = { "the", "quick", "brown", "fox", name = 'Nick' }
    table.foreachi (t, print)

     -->

    1 the
    2 quick
    3 brown
    4 fox
In this example the entry for "name = 'Nick'" was not returned because it did not have a numeric key. Warning the use of table.foreachi is deprecated. This means it may not be available in future versions of Lua. You are recommended to rewrite such uses by using the 'ipairs' function. table.getn (t) Returns the size of the table using the rules described at the start of this page.
    table.getn { "the", "quick", "brown", "fox", name = "Nick" } --> 4
Note that the length here is 4 and not 5, because the non-numeric entry (name = "Nick") is not considered to be part of the table's "length". You can also use #t to find the length of a table.
    # { "the", "quick", "brown", "fox", name = "Nick" } --> 4
table.insert (t, pos, value) Inserts the value at (optional) position 'pos', renumbering existing elements if necessary to make room. Thus the new element becomes the one with index 'pos'. If called with 2 arguments, the value is inserted at n+1, that is, the end of the table.
    t = { "the", "quick", "brown", "fox" }
    table.insert (t, 2, "very") -- new element 2
    table.insert (t, "jumped")  -- add to end of table
    table.foreachi (t, print)

     -->

    1 the
    2 very
    3 quick
    4 brown
    5 fox
    6 jumped
The Lua authors recommend using the idiom "#t + 1" to insert to the end of a table nowadays. For example:
    t = {}
    t [#t + 1] = "hello, "
    t [#t + 1] = "world"
table.maxn (t) Returns the highest numeric key in the table, by examining each entry in the entire table. This will necessarily be slower than doing table.getn, but would be needed if the keys have gaps in the sequence. table.remove (t, pos) Removes the element at position 'pos' from the table, returning the value of the removed element. If 'pos' is omitted it defaults to the end of the table (n), thus removing the last element.
    t = { "the", "quick", "brown", "fox" }
    print (table.remove (t, 3))
    table.foreachi (t, print)

     -->

    brown
    1 the
    2 quick
    3 fox
The Lua authors recommend using this method for removing from the end of a table nowadays:
    t [#t] = nil  -- remove last entry
table.setn (t, n) This has been removed from Lua 5.1. Attempting to call it will raise an error. The length of a table can not be set, it is implied by the highest numeric key, providing there are no gaps in the sequence of numeric keys. table.sort (t, f) Sorts the table using the supplied function f as the comparison function for each element. Function f should return true if the first element is < the second element. If the function omitted it defaults to the operator <. Sorting is not stable, that is, the sequence of equal keys is not necessarily preserved.
    t = { "the", "quick", "brown", "fox" }
    table.sort (t)
    table.foreachi (t, print)

     -->

    1 brown
    2 fox
    3 quick
    4 the
Sorting is really only relevant for numerically keyed tables. If you want to sort the keys for other types of tables you need to make a copy of the keys and sort that, like this:
    t = { str = 42, dex = 10, wis = 100 }
    ts = {} -- table to hold the keys
    table.foreach (t, function (k, v) table.insert (ts, k) end )
    table.sort (ts) -- sort keys
    table.foreachi (ts, print) -- print sorted keys

     -->

    1 dex
    2 str
    3 wis
Here is an example of a custom sort function. This is needed here because we are sorting tables, which do not have a natural "less than" operator:
    t = {
        { str = 42, dex = 10, wis = 100 },
        { str = 18, dex = 30, wis = 5 }
        }

    table.sort (t, function (k1, k2) return k1.str < k2.str end )

    table.foreachi (t, function (k, v) table.foreach (v, print) end )

     -->

    str 18
    dex 30
    wis 5
    str 42
    dex 10
    wis 100
We can see from the results that the two tables were sorted into "str" order. An alternative approach to supplying a comparison function for the sort would be to set up a metatable for the individual table items (not the container table) which specifies a __lt (less than) operator. Here is an example:
    t = {
        { str = 42, dex = 10, wis = 100 },
        { str = 18, dex = 30, wis = 5 }
        }

    mt =  { __lt = function (k1, k2) return k1.wis < k2.wis end }

    -- apply metatable to all tables inside our table
    for _, v in ipairs (t) do
      setmetatable (v, mt)
    end -- for

    table.sort (t)

    table.foreachi (t, function (k, v) table.foreach (v, print) end )

     -->

    str 18
    dex 30
    wis 5
    str 42
    dex 10
    wis 100
In this case I have made a metatable "mt" which is then applied to each table item. It compares the "wis" field in this case. With this in place the sort can be called without a helper function. Of course, for speed purposes you would do this once (perhaps when creating the individual table entries) rather than every time you wanted to sort it. See Also ... Topics Lua base functions Lua coroutine functions Lua debug functions Lua io functions Lua math functions Lua os functions Lua package functions Lua script extensions Lua string functions (Help topic: general=lua_tables) Documentation contents page