table

The complete table library. Functions marked (Luau) are Luau extensions beyond standard Lua 5.1.

Construction & copying

table.create(count, value?) (Luau)

Preallocates an array of count slots, optionally filled with value. Faster than growing a table incrementally.

local t = table.create(5, 0)   -- {0, 0, 0, 0, 0}
print(t[5])                    --> 0

table.clone(t) (Luau)

Shallow copy — nested tables are shared, not duplicated.

local orig = {1, 2, 3, name = "cube"}
local copy = table.clone(orig)
copy[1] = 99
print(orig[1], copy.name)  --> 1  cube

table.pack(...)

Captures varargs into a table with an n field counting all arguments (including nils).

local t = table.pack(1, nil, 3)
print(t.n)  --> 3

table.unpack(list, i?, j?)

Expands a table back into varargs.

print(table.unpack({10, 20, 30}))       --> 10  20  30
print(table.unpack({1, 2, 3, 4}, 2, 3)) --> 2  3

table.clear(t) (Luau)

Removes all entries in one pass; capacity is retained for reuse.

local cache = {a = 1, b = 2}
table.clear(cache)
print(next(cache))  --> nil

Manipulation

table.insert(list, value) / table.insert(list, pos, value)

Append, or insert at a position shifting elements up.

local t = {1, 2}
table.insert(t, 3)        --> {1, 2, 3}
table.insert(t, 1, 0)     --> {0, 1, 2, 3}

table.remove(list, pos?)

Removes and returns the element at pos (default: last), shifting elements down.

local t = {"a", "b", "c"}
print(table.remove(t))      --> c
print(table.remove(t, 1))   --> a
print(t[1])                 --> b

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

Moves elements f..e of a1 to start at index t (in a2 if given — otherwise a1 in place).

local src = {1, 2, 3, 4}
table.move(src, 1, 2, 3)          --> {1, 2, 1, 2}
local dst = {}
table.move(src, 3, 4, 1, dst)     --> dst = {1, 2}
print(dst[1] + dst[2])            --> 3

table.sort(list, comp?)

In-place sort; comp(a, b) must return true when a should come first. Default is <. Not guaranteed stable.

local t = {3, 1, 2}
table.sort(t)
print(table.concat(t, ","))  --> 1,2,3

table.sort(t, function(a, b) return a > b end)
print(table.concat(t, ","))  --> 3,2,1

Querying

table.getn(list)

The array length — same as the # operator.

print(table.getn({1, 2, 3}))  --> 3

table.maxn(t)

The largest positive numeric key in t.

print(table.maxn({[10] = "x"}))  --> 10

table.find(t, value, init?) (Luau)

Linear search returning the index, or nil.

local langs = {"luau", "csharp", "python"}
print(table.find(langs, "luau"))  --> 1
print(table.find(langs, "asm"))   --> nil

table.concat(list, sep?, i?, j?)

Joins array elements into a string.

print(table.concat({1, 2, 3}, "-"))     --> 1-2-3
print(table.concat({"a", "b", "c"}, "", 2))  --> bc

Freezing (Luau)

table.freeze(t)

Makes the table read-only. Mutation of a frozen table raises a runtime error; nested tables are not frozen.

local cfg = table.freeze({speed = 1.0})
print(cfg.speed)     --> 1.0
cfg.speed = 2.0      -- error: attempt to modify a readonly table

table.isfrozen(t)

local t = table.freeze({})
print(table.isfrozen(t))  --> true

Iteration (legacy)

table.foreach(t, f)

Calls f(key, value) for every entry until one returns non-nil.

table.foreach({a = 1, b = 2}, function(k, v)
    print(k, v)
end)

table.foreachi(t, f)

Same, but only for the sequential array part, in order 1..n.

table.foreachi({"x", "y"}, function(i, v)
    print(i, v)
end)

Note

foreach/foreachi are deprecated in Lua 5.1 but present and working in Luau. Prefer pairs/ipairs in new code; they’re documented here for completeness.