In Lua, a table is an associative array/dictionary (i.e., a collection of key–value pairs) which can be indexed with any value type (including Vector3) except for nil. Tables are also used to represent many other data structures, including arrays (an ordered list of values). Tables are represented by the table data type.

Unlike other programming languages, the index of an array starts at 1 instead of 0.

Syntax

In Lua's syntax, tables are created by a table constructor which is an expression. The simplest constructor is {} (curly brackets) which creates an empty table. New values (expressions) can be set through keys, which can be any value type or another expression, and the table can be indexed for a specific value using the same key that was used to set the value. A key must be in between square brackets. If the key is a proper identifier (string index), the period (.) can be used instead for indexing the table, while the key itself can be used in a table constructor.

t = {}

-- assigning values to the table
t["x"] = 10
t["y"] = 20

-- representing the table as a record (using identifiers instead of string literals to assign values)
t.x = 10
t.y = 20

-- retrieving values by indexing the table
print(t.x, t.y)
-- or
print(t["x"], t["y"])

-- using other types
t[100] = "foo"
t[true] = "bar"

-- using expressions
i = 10
t[i + 1] = 1; t[i + 2] = 2
t[os.time()] = "today"

Arrays

A table constructor can initialize an array using a list of values or expressions separated by commas or semicolons. The index begins at 1 and the constructor stores the value of each element in the list to the corresponding index.

t = {"January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"}
print(t[10]) -- October

t = {os.clock(), os.clock()}
print(t[2] - t[1])

The array length operator (#) is used before an array to return the number of list values as an expression. This operator can be used for inserting items, although the built-in function table.insert can be used instead.

t = {"January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"}
print(#t) -- 12
t[#t + 1] = "January"
print(#t) -- 13
table.insert(t, "February")
print(#t) -- 14

Dictionaries

A table constructor can initialize a table as a dictionary using the syntax key = value.

user = {name = "builderman", id = 156}
-- is equivalent to
user = {}; user.name = "builderman"; user.id = 156

A dictionary is often represented as a record, which only uses identifiers (string indices) as keys, but it can also have other values besides identifiers as keys, such as "-" or true. A dictionary may also contain non-array indices such as negative indices or zero.

t = {[true] = "yes", [false] = "no", ["+"] = "add", ["-"] = "sub"}
print(t[true], t[false], t["+"], t["-"])

A dictionary can also be used with enum values as keys.

t = {
    [Enum.HumanoidStateType.Running] = true, 
    [Enum.HumanoidStateType.Jumping] = true, 
    [Enum.HumanoidStateType.Dead] = false
}
print(t[Humanoid:GetState()])

Mixed tables

A mixed table is a table that has both array/list values and dictionary values. A table constructor can initialize both of these values at the same time.

user = {name = "builderman", id = 156; "item1", "item2"}
-- is equivalent to
user = {}
user.name = "builderman"; user.id = 156
user[1] = "item1"; user[2] = "item2"

Functions

Iterators

The built-in functions pairs and ipairs are commonly used for iterating over a table. The former expects dictionary tables (mixed or arrays are also accepted) while the latter iterates using number indices and primarily used for arrays. The primitive next function can also be used for iterating over a dictionary, in place of the pairs function. Iterators are mostly used in for loops.

-- array
t = workspace:GetChildren()
for i, v in ipairs(t) do
    print(i, v)
end

-- dictionary
user = {name = "builderman", id = 156}
for i, v in pairs(user) do
    print(i, v)
end

-- next
user = {name = "builderman", id = 156}
for i, v in next, user do
    print(i, v)
end

External links

• Tables on the Roblox Creator Documentation
• 2.5 – Tables on the Lua website
• 3.6 – Table Constructors on the Lua website