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

DOC_lua_base Lua base functions
DOC_lua_coroutines Lua coroutine functions
DOC_lua_debug Lua debug functions
DOC_lua_io Lua io functions
DOC_lua_math Lua math functions
DOC_lua_os Lua os functions
DOC_lua_package Lua package functions
DOC_lua Lua script extensions
DOC_lua_string Lua string functions

(Help topic: general=lua_tables)

DOC_contents Documentation contents page