tableLuaLuauLuwu

The table library creates and copies tables, inserts and removes array elements, searches and sorts arrays, joins them into strings and freezes tables against changes.

Copyconst players = { "nyla", "ada", "lin" }
table.insert(players, "bo")
table.sort(players)
print(table.concat(players, ", "))
print(table.find(players, "lin"))

const roster = table.freeze(table.clone(players))
print(table.isfrozen(roster))

ada, bo, lin, nyla
3
true

See Tables

Creates an array with room for count items. When value is given, every index from 1 to count is set to it. Without it the array is empty and has its space reserved for filling later.

Copyconst scores = table.create(4, 0)
print(table.concat(scores, ", "))

0, 0, 0, 0

A negative count is an error.

Returns a shallow copy of the table with the same keys, values and metatable. The copy is never frozen, even when t is. Nested tables are shared between the two.

Copyconst original = { tags = { "new" }, count = 1 }
const copy = table.clone(original)
copy.count = 2
table.insert(copy.tags, "sale")
print(original.count)
print(#original.tags)

1
2

A table whose metatable has a __metatable field can't be cloned.

Copies the items at indices a to b of src into dst starting at index t and returns dst. Without dst the items are copied within src. Overlapping ranges in the same table are copied correctly.

It reads src and writes dst directly without calling __index or __newindex.

Copyconst first = { 1, 2, 3 }
const second = { 4, 5 }
const both = table.move(second, 1, #second, #first + 1, first)
print(table.concat(both, ", "))

1, 2, 3, 4, 5

An empty range (b less than a) copies nothing. Moving into a frozen table is an error.

With two arguments, appends value to the end of the array like t[#t + 1] = value. With three, inserts it at index and moves the items from there to the end up by one.

It writes to t directly without calling __newindex.

Copyconst queue = { "Grace", "Alan" }
table.insert(queue, "Linus")
table.insert(queue, 1, "Ada")
print(table.concat(queue, ", "))

Ada, Grace, Alan, Linus

An index outside 1 to #t moves nothing and sets t[index] directly. Calling it with any other number of arguments is an error.

Removes the item at index and returns it. The items after it move down by one and the array keeps no hole. Without index or when it's nil, the last item is removed. An index outside 1 to #t removes nothing and returns nothing.

It reads and writes t directly without calling __index or __newindex.

Copyconst queue = { "Ada", "Grace", "Alan" }
print(table.remove(queue, 1))
print(table.remove(queue))
print(table.concat(queue, ", "))

Ada
Alan
Grace

Since a nil index removes the last item, table.remove(t, table.find(t, value)) removes the wrong item when the value is missing. Luwu warns about an index that might be nil. Use table.drop to remove items by value.

Removes the items equal to value and returns how many it removed. By default every match is removed. When count is given, only the first count matches are. The items after a removed one move down and the array keeps no holes. A missing value removes nothing and returns 0.

It reads and writes t directly without calling __index or __newindex. Comparisons use == and respect __eq.

Copyconst queue = { "retry", "done", "retry", "retry" }
print(table.drop(queue, "retry", 2))
print(table.drop(queue, "skip"))
print(table.concat(queue, ", "))

2
0
done, retry

A frozen table is an error, and so is a count of zero or less. The Library Extensions guide page explains the bug it replaces.

Removes every key from the table but keeps the memory it has allocated. Filling the table again up to the same size doesn't reallocate. Clearing a frozen table is an error.

Returns the index of the first item equal to needle or nil if there's none. The search starts at init (1 by default) and stops at the first nil. An init below 1 is an error.

It reads haystack directly without calling __index. Comparisons use == and respect __eq.

Copyconst fruits = { "apple", "kiwi", "pear", "kiwi" }
print(table.find(fruits, "kiwi"))
print(table.find(fruits, "kiwi", 3))
print(table.find(fruits, "plum"))

2
4
nil

Sorts the array in place. Without comp items are sorted in ascending order with <. With it, comp(a, b) returns true when a should come before b.

It reads and writes t directly without calling __index or __newindex.

Copyconst names = { "Grace", "Ada", "Alan" }
table.sort(names)
print(table.concat(names, ", "))

const scores = { 40, 95, 70 }
table.sort(scores, function(a, b)
    return a > b
end)
print(table.concat(scores, ", "))

Ada, Alan, Grace
95, 70, 40

• The sort isn't stable. Items that compare equal can end up in any order.
• comp has to be a strict ordering: comp(a, a) is false. An inconsistent function can raise an "invalid order function for sorting" error.
• Sorting a frozen table is an error. So is growing the table from inside comp.

Returns the largest positive numeric key in the table, or 0 if there's none. Unlike # it looks at every key and isn't confused by holes.

Copyconst sparse = { [1] = "a", [2] = "b", [10] = "j" }
print(table.maxn(sparse))

10

Returns an array of its arguments with the field n set to how many there were. Unlike #, n counts nil arguments.

Copyconst packed = table.pack("a", nil, "c")
print(packed.n)

3

Returns the items from index i to j as separate values. i defaults to 1 and j to #list. The global unpack is the same function.

It reads list directly without calling __index.

Copyconst point = { 3, 4, 5 }
const x, y = table.unpack(point, 1, 2)
print(x + y)
print(math.max(table.unpack(point)))

7
5

Unpacking more values than fit on the stack is an error.

Joins the items from index i to j into one string with separator between them. i defaults to 1, j to #t and separator to an empty string.

It reads t directly without calling __index.

Copyconst words = { "red", "green", "blue", 7 }
print(table.concat(words, ", "))
print(table.concat(words, "-", 2, 3))

red, green, blue, 7
green-blue

Every item in the range has to be a string or a number. Anything else is an error that names its index.

Freezes the table and returns it. After that, assigning to any key or setting its metatable is an error. Freezing is shallow: tables stored inside a frozen table can still change.

Copyconst colors = table.freeze({ "red", "green" })
const ok = pcall(function()
    colors[3] = "blue"
    return true
end)
print(ok)
print(table.isfrozen(colors))

false
true

Freezing a table that is already frozen is an error. So is freezing one whose metatable has a __metatable field.

Returns true when the table is frozen by table.freeze or by the program that embeds Luwu.

Returns the length of the array.

Calls f with every key and value in the table in no particular order. When f returns a value other than nil, the loop stops and table.foreach returns that value.

Calls f with every index and item from 1 to #t in order. When f returns a value other than nil, the loop stops and table.foreachi returns that value.