table

Table manipulation functions of Lua 5.1 / LuaJIT 2.1.

Table functions of Lua 5.1 / LuaJIT 2.1, unchanged by the client, working on the array part of a table (indices 1 to #t).

At a glance

Function	Description
`table.insert(t, [pos,] value)`	append or insert an element
`table.remove(t, pos)`	remove an element
`table.concat(t, sep, i, j)`	join elements into a string
`table.sort(t, comp)`	sort in place
`table.move(a1, f, e, t, a2)`	copy a range of elements
`table.maxn(t)`	largest positive numeric key
`require("table.new")`, `require("table.clear")`	preallocate or empty a table
`table.getn`, `table.foreach`, `table.foreachi`	deprecated

table.pack and table.unpack (Lua 5.2) do not exist: use {...} with select("#", ...) and the global unpack.

Functions

table.concat(t, sep, i, j): string

table.concat(t: table, sep?: string = "", i?: number = 1, j?: number = #t): string

Name	Type	Description
`t`	table	array of strings or numbers
`sep`	string	separator
`i`, `j`	number	first and last index

Returns: t[i] .. sep .. t[i+1] ... t[j], "" when i > j. Errors: invalid value (table) at index 1 in table for 'concat' for an element that is not a string or a number.

print(table.concat({ "a", "b", "c" }, ", "))

table.insert(t, pos, value)

table.insert(t: table, pos?: number, value: any)

Name	Type	Description
`t`	table	array
`pos`	number	position; without it, `value` is appended at `#t + 1`
`value`	any	value to insert

With pos, the elements pos to #t move up by one. LuaJIT does not check pos: a value above #t + 1 leaves a hole.

Returns: nothing. Errors: wrong number of arguments to 'insert' with more than 3 arguments.

local t = { 1, 2, 3 }
table.insert(t, 4)
table.insert(t, 1, 0)
print(table.concat(t, " "))

table.remove(t, pos): any

table.remove(t: table, pos?: number = #t): any

Name	Type	Description
`t`	table	array
`pos`	number	position to remove, 1 to `#t`

The following elements move down by one.

Returns: the removed value, or nothing when the table is empty or pos is outside 1 to #t.

local queue = { "a", "b", "c" }
print(table.remove(queue, 1), #queue)

table.sort(t, comp)

table.sort(t: table, comp?: function(a: any, b: any): boolean)

Name	Type	Description
`t`	table	array to sort in place, `t[1]` to `t[#t]`
`comp`	function	returns `true` when `a` comes before `b`, default `<`

Returns: nothing. The sort is not stable. Errors: invalid order function for sorting for an inconsistent comp (for example one using <=), attempt to compare number with nil and the like without comp.

local t = { 3, 1, 2 }
table.sort(t, function(a, b) return a > b end)

table.move(a1, f, e, t, a2): table

table.move(a1: table, f: number, e: number, t: number, a2?: table = a1): table

Name	Type	Description
`a1`	table	source
`f`, `e`	number	first and last source index
`t`	number	first destination index
`a2`	table	destination

Copies a1[f] to a1[e] into a2[t] onward, overlapping ranges included.

Returns: a2.

local copy = table.move({ 1, 2, 3 }, 1, 3, 1, {})
print(#copy)

table.maxn(t): number

table.maxn(t: table): number

Name	Type	Description
`t`	table	table

Returns: the largest positive numeric key, or 0. It traverses the whole table, so it also works on tables with holes.

table.new(narray, nhash): table

local new_table = require("table.new")
new_table(narray: number, nhash: number): table

Name	Type	Description
`narray`	number	slots to preallocate in the array part
`nhash`	number	slots to preallocate in the hash part

Returns: an empty table with that room, which avoids rehashing while it fills.

table.clear(t)

local clear_table = require("table.clear")
clear_table(t: table)

Name	Type	Description
`t`	table	table to empty

Removes every key but keeps the allocated room, to reuse a table every frame without creating garbage.

Returns: nothing.

Deprecated

Kept for compatibility, prefer the modern forms.

table.getn(t): number

table.getn(t: table): number

Name	Type	Description
`t`	table	array

Returns: #t.

table.foreach(t, f): any

table.foreach(t: table, f: function(key: any, value: any): any): any

Name	Type	Description
`t`	table	table
`f`	function	called for every pair, in unspecified order

Returns: the first non-nil value returned by f, which also stops the loop. Prefer pairs.

table.foreachi(t, f): any

table.foreachi(t: table, f: function(index: number, value: any): any): any

Name	Type	Description
`t`	table	array
`f`	function	called for indices 1 to `#t`, in order

Returns: the first non-nil value returned by f, which also stops the loop. Prefer ipairs.

Complete example

Keep the 3 nearest entities, reusing one table every frame.

local clear_table = require("table.clear")
local nearest = {}

local function pick(entities, max)
    clear_table(nearest)
    for _, e in ipairs(entities) do
        nearest[#nearest + 1] = e
    end
    table.sort(nearest, function(a, b) return a.distance < b.distance end)
    for i = #nearest, max + 1, -1 do
        table.remove(nearest, i)
    end
    return nearest
end

local list = pick({ { name = "a", distance = 9 }, { name = "b", distance = 2 },
    { name = "c", distance = 5 }, { name = "d", distance = 1 } }, 3)
local names = {}
for i, e in ipairs(list) do names[i] = e.name end
print(table.concat(names, ", "))