creator-docs/content/en-us/luau/tables.md at main · Aseminaunz/creator-docs

title	description
Tables	Data type which can store multiple values of any non-nil type, including booleans, numbers, strings, functions, and other tables.

The table data type can store multiple values of any type that isn't nil, including booleans, numbers, strings, functions, and other tables. Construct tables with curly braces ({}):

-- Construct an empty table assigned to variable "t"
local t = {}
print(t) -- {}

You can use a table as an array or dictionary. Arrays use an ordered list of numbers as indices, but dictionaries can have numbers, strings, and objects as indices.

For more information on built-in functions for working with tables, see the Library.table library.

Arrays

An array is an ordered list of values. Arrays are useful for storing collections of data, such as a group of players with special permissions.

Create arrays

To create an array using a Luau table, declare the values in sequential order, separated by commas.

-- Construct an array with three items
local testArray = {"A string", 3.14159, true}
print(testArray)

Read from arrays

To read from an array, add a pair of square brackets after its reference and specify the index number of the element inside ([pos]):

-- Construct an array with three items
local testArray = {"A string", 3.14159, true}

print(testArray[1]) -- A string
print(testArray[2]) -- 3.14159
print(testArray[3]) -- true

Unlike some languages, Luau uses 1-based indexing for arrays, so the first item in the array is `[1]`, not `[0]`.

Write to arrays

To define or rewrite the value of an array at an index, declare the index number in square brackets ([index]) followed by = and the value:

local testArray = {"A string", 3.14159, true}

testArray[2] = 12345
testArray[4] = "New string"

print(testArray[2]) --12345
print(testArray[4]) -- New string

Iterate over arrays

To iterate over an array, you can use a for loop. Because the arrays have numerical indices, you can also use a numeric for loop from 1 to the length of the array (#array).

local testArray = {"A string", 3.14159, true, "New string"}

-- Loop using general iteration
for index, value in testArray do
	print(index, value)
end

-- Iterate using the array length operator (#)
for index = 1, #testArray do
	print(index, testArray[index])
end

Insert items

There are two built-in ways to insert an item to the end of an array:

Pass a reference to the array and the item value to Luau's Library.table.insert() function.
Add the new item to the array using the array[#array+1] syntax.

local testArray = {"A string", 3.14159}

table.insert(testArray, "New string")
testArray[#testArray+1] = "Another new string"

print(testArray[3]) -- New string
print(testArray[4]) -- Another new string

To insert an item between the start and end of an array, include a position value as the second argument of Library.table.insert(). This inserts the new item and pushes the following items up one index position.

local testArray = {"First item", "Next item"}

table.insert(testArray, 2, "NEW ITEM #2")

print(testArray[1]) -- First item
print(testArray[2]) -- NEW ITEM #2
print(testArray[3]) -- Next item

Remove items

To remove an item from an array, use Library.table.remove(). This removes the item at the specified position and moves any following items back one index position.

local testArray = {"First item", "Next item", "Last item"}

table.remove(testArray, 2)

print(testArray[1]) -- First item
print(testArray[2]) -- Last item

Dictionaries

Dictionaries are an extension of arrays. Dictionaries store a set of key-value pairs, where the keys can be any number, string, or object.

Create dictionaries

To create a dictionary table, define each key followed by = and the value. Separate each key-value pair with a comma:

local testDictionary = {
	fruitName = "Lemon",
	fruitColor = "Yellow",
	sour = true
}

The keys for dictionaries can be numbers, strings, and objects. For example, a key may also be an Class.Instance. To use objects as keys, declare the key in square brackets ([key]):

local part = Instance.new("Part")

local testDictionary = {
	partType = "Block",
	[part] = true
}

Read from dictionaries

To read from a dictionary, add a pair of brackets after its reference and specify the key name. Directly reference a string key using either (["key"]) or (.key), or instead use a variable value ([key]).

local part = Instance.new("Part")

local testDictionary = {
	partType = "Block",
	[part] = true
}
-- Include quotes for string keys
print(testDictionary["partType"]) -- Block
-- Or use . to index string keys without spaces
print(testDictionary.partType) -- Block
-- Omit quotes for non-string keys
print(testDictionary[part]) -- true

Write to dictionaries

To define or rewrite the value of a new or existing dictionary key, declare the key name in brackets ([key]) or, if the key is a string, use (.key) followed by = and the value:

local testDictionary = {
	fruitName = "Lemon",
	sour = true
}

-- Change value of existing keys
testDictionary["fruitName"] = "Cherry"
testDictionary.sour = false

-- Insert new key-value pair
testDictionary.fruitCount = 10

print(testDictionary.fruitName) -- Cherry
print(testDictionary.sour) -- false
print(testDictionary.fruitCount) -- 10

Iterate over dictionaries

To iterate over a dictionary, use a for loop:

local testDictionary = {
	fruitName = "Lemon",
	fruitColor = "Yellow",
	sour = true
}

for key, value in testDictionary do
	print(key, value)
end

--[[ Resulting output:
fruitName Lemon
sour true
fruitColor Yellow
]]

Remove key-value pairs

To remove or erase a key-value pair from a dictionary, set its value for a key to nil.

local testDictionary = {
	fruitName = "Lemon",
	fruitColor = "Yellow",
	sour = true
}

testDictionary.sour = nil

for key, value in testDictionary do
	print(key, value)
end
--[[ Resulting output:
fruitName Lemon
fruitColor Yellow
]]

Tables as references

If you store a table in a new variable, Luau doesn't create a copy of that table. Instead, the variable becomes a reference, or pointer, to the original table. Any reference to a table reflects any changes to the original table:

local originalArray = {10, 20}

local arrayReference = originalArray

print("Original:", originalArray[1], originalArray[2])
print("Reference:", arrayReference[1], arrayReference[2])

-- Change values in original array
originalArray[1] = 1000
originalArray[2] = 2000

print("Reference:", arrayReference[1], arrayReference[2])

--[[ Resulting output:
Original: 10 20
Reference: 10 20
Reference: 1000 2000
]]

Clone tables

Shallow clones

To copy a table without any nested tables, Luau offers the Library.table.clone() method.

local original = {
	key = "value",
	engine = "Roblox",
	playerID = 505306092
}

local clone = table.clone(original)

Deep clones

To copy a more complex table with nested tables inside it, you'll need to use a recursive function similar to the following:

-- The function used for deep cloning a table
local function deepClone(original)
	-- Define the new table for the copy
	local clone = table.clone(original) 

	-- Loop through the original table to check for table values
	-- If a table is found as a value, deep clone it to the key (index)
	for key, value in original do
		if type(value) == "table" then
			clone[key] = deepClone(value)
		end
	end

	-- Return the finalized copy of the deep cloned table
	return clone
end

With the function in place, you can make a deep copy as follows:

local original = {
	key = "value",
	playerInfo = {
		playerID = 505306092,
		playerName = "PlayerName"
	},
	otherInfo = {
		{
			{1, 3, 5, 7, 9}
		}
	}
}

local clone = deepClone(original)

Freeze tables

Freezing a table makes it read-only, which is useful for creating constant values that you don't want to change. Freezing is permanent; there's no "unfreeze" or "thaw" method. To check if a table is frozen, use Library.table.isfrozen().

Shallow freezes

To freeze a table without any nested tables, Luau offers the Library.table.freeze() method.

local target = {
	key = "value",
	engine = "Roblox",
	playerID = 505306092
}

table.freeze(target)
target.playerID = 1 --> attempt to modify a readonly table

Deep freezes

To freeze a more complex table with nested tables inside it, use a recursive function similar to the following:

local function deepFreeze(target)
	-- Shallow freeze the table
	table.freeze(target)

	-- Check each key of the table and freeze it if it's a table
	for _, value in target do
		-- Make sure the value isn't frozen; if it already is, an error will occur
		if type(value) == "table" and table.isfrozen(value) == false then
			deepFreeze(value)
		end
	end
end

With the function in place, you can deep freeze a table as follows:

local target = {
	key = "value",
	playerInfo = {
		playerID = 505306092,
		playerName = "PlayerName"
	},
	otherInfo = {
		{
			{1, 3, 5, 7, 9}
		}
	}
}

deepFreeze(target)
target.playerInfo.playerID = 1 --> attempt to modify a readonly table

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Arrays

Create arrays

Read from arrays

Write to arrays

Iterate over arrays

Insert items

Remove items

Dictionaries

Create dictionaries

Read from dictionaries

Write to dictionaries

Iterate over dictionaries

Remove key-value pairs

Tables as references

Clone tables

Shallow clones

Deep clones

Freeze tables

Shallow freezes

Deep freezes

FilesExpand file tree

tables.md

Latest commit

History

tables.md

File metadata and controls

Arrays

Create arrays

Read from arrays

Write to arrays

Iterate over arrays

Insert items

Remove items

Dictionaries

Create dictionaries

Read from dictionaries

Write to dictionaries

Iterate over dictionaries

Remove key-value pairs

Tables as references

Clone tables

Shallow clones

Deep clones

Freeze tables

Shallow freezes

Deep freezes