Tables
Tables
A table is a Lua data type that can store multiple values including /articles/Numbers|numbers, /articles/Boolean|booleans, /articles/String|strings, /articles/Function|functions, and more. Tables are constructed with curly braces ({}) as shown here:
Once constructed, a table can behave as either an array or a dictionary as illustrated in the following sections.
Arrays
An array is a simple list of ordered values, useful for storing collections of data such as a group of players with special permissions.
Creating Arrays
To create an array using a Lua table, simply store the values sequentially, separated by commas. An array value can be any non-nil type (boolean, number, string, function, userdata, or even another table).
-- Construct an array with three items
local testArray = {"A string", 3.14159, workspace.Part}
Reading From Arrays
To read from an array, add a pair of brackets after its reference and specify the index number of the element inside ([pos]):
[1], not [0].
Writing Into Arrays
The value of an array index can be defined or rewritten by indicating the index number in brackets ([pos]) followed by = and then the value:
Iterating Over Arrays
Arrays can be iterated over (looped through) in two ways:
- Use the built-in
ipairs()function in aforloop. - Get the array’s length using the
#operator and loop from 1 to that length value.
Inserting Items
An item can be inserted at the end of an array through either of these methods:
- Pass the array reference and the item value to Lua’s
table.insert()function. - Add the new item to the array using the
t[#t+1]syntax.
An item can also be inserted between the start and end by including a position value as the second argument of table.insert(). This will insert the new item and push the following items up one index position.
Removing Items
An item can be removed from an array with Lua’s table.remove() function. This will remove the item at the specified position and move any following items down one index position.
Dictionaries
Dictionaries are an extension of arrays. While an array stores an ordered list of items, a dictionary stores a set of key-value pairs.
| Key | Value |
|---|---|
| FruitName | Lemon |
| FruitColor | Yellow |
| Sour | true |
Creating Dictionaries
To create a dictionary table, define each key followed by = and then the value. Remember to separate each key-value pair with a comma:
local testDictionary = {
FruitName = "Lemon",
FruitColor = "Yellow",
Sour = true
}
When creating dictionaries, keys are not limited to just string names like FruitColor; for example, a key may also be an Instance. In this case, the key must be declared with surrounding brackets ([key]):
local part = Instance.new("Part")
local testDictionary = {
PartType = "Block",
[part] = true
}
Reading From Dictionaries
To read from a dictionary, add a pair of brackets after its reference and specify the key name:
- String keys like
PartTypemust be referenced with surrounding quotes as intestDictionary["PartType"]. - Non-string keys like
[part]should not be referenced with surrounding quotes.
Writing Into Dictionaries
The value of a new or existing dictionary key can be defined by indicating the key name in brackets ([key]) followed by = and then the value:
Iterating Over Dictionaries
Dictionaries can be iterated over with the built-in pairs() function in a for loop:
ipairs() on an array, dictionary iteration via pairs() does not necessarily return items in the same order they're declared within the dictionary.
Removing Key-Value Pairs
To remove a key-value pair from a dictionary, simply set its value to nil. As demonstrated below in the pairs() loop output, this completely erases the key-value pair from the dictionary:
Tables as References
If you store a table in a new variable, a copy of that table is not created. Instead, the variable becomes a reference (pointer) to the original table. This means that any changes to the original table will be reflected in any references: