11 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

table

This library provides generic functions for table/array manipulation, providing all its functions inside the global table variable. Most functions in the table library assume that the table represents an array or a list. For these functions, the "length" of a table means the result of the length operator.

Functions

table.clear

Sets the value for all keys within the given table to nil. This causes the # operator to return 0 for the given table. The allocated capacity of the table's array portion is maintained, which allows for efficient re-use of the space.

local grades = {95, 82, 71, 92, 100, 60}
print(grades[4], #grades) --> 92, 6
table.clear(grades)
print(grades[4], #grades) --> nil, 0
-- If grades is filled again with the same number of entries,
-- no potentially expensive array resizing will occur
-- because the capacity was maintained by table.clear.

This function does not delete/destroy the table provided to it. This function is meant to be used specifically for tables that are to be re-used.

Parameters

Returns

table.clone

Returns an unfrozen shallow copy of the provided table.

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

local clone = table.clone(original)

Parameters

Returns

table.concat

Given an array where all elements are strings or numbers, returns the string t[i] ... sep ... t[i+1] ... sep ... t[j]. The default value for sep is an empty string, the default for i is 1, and the default for j is #t. If i is greater than j, returns the empty string.

Parameters

Returns

table.create

Creates a table with the array portion allocated to the given number of elements, optionally filled with the given value.

local t = table.create(3, "Roblox")
print(table.concat(t)) --> RobloxRobloxRoblox

If you are inserting into large array-like tables and are certain of a reasonable upper limit to the number of elements, it's recommended to use this function to initialize the table. This ensures the table's array portion of its memory is sufficiently sized, as resizing it can be expensive. For small quantities this is typically not noticeable.

Parameters

Returns

table.find

Within the given array-like table haystack, find the first occurrence of value needle, starting from index init or the beginning if not provided. If the value is not found, nil is returned.

A linear search algorithm is performed.

local t = {"a", "b", "c", "d", "e"}
print(table.find(t, "d")) --> 4
print(table.find(t, "z")) --> nil, because z is not in the table
print(table.find(t, "b", 3)) --> nil, because b appears before index 3

Parameters

Returns

table.foreach

Deprecated.

Iterates over the provided table, passing the key and value of each iteration over to the provided function. This function has been deprecated and is not recommended for use in new code; use a for loop instead.

Parameters

Returns

table.foreachi

Deprecated.

This is similar to table.foreach() except that index-value pairs are passed, not key-value pairs. This function has been deprecated and is not recommended for use in new code; use a for loop instead.

Parameters

Returns

table.freeze

This function makes the given table read-only, effectively "freezing" it in its current state. Attempting to modify a frozen table throws an error.

This freezing effect is shallow, which means that you can write to a table within a frozen table. To deep freeze a table, call this function recursively on all of the descending tables.

Parameters

Returns

table.getn

Deprecated.

Returns the number of elements in the table passed. This function has been deprecated and is not recommended for use in new code; use #t instead.

Parameters

Returns

table.insert

Inserts value into array t at position pos, shifting up the elements t[pos], t[pos+1], ..., t[#t] by one position. The position must be between 1 and #t (inclusive) for the shift to occur; the value is then written at t[pos].

local t = {"a", "b", "c"}
table.insert(t, 2, "new")
print(table.concat(t, ", ")) --> a, new, b, c

Parameters

Returns

table.insert

Appends value to the end of array t at position #t + 1. Unlike the positional overload, no existing elements are shifted, making this the most efficient way to grow an array by one element.

local t = {"a", "b", "c"}
table.insert(t, "d")
print(table.concat(t, ", ")) --> a, b, c, d

Parameters

Returns

table.isfrozen

This function returns true if the given table is frozen and false if it isn't frozen. You can freeze tables using table.freeze().

Parameters

Returns

table.maxn

Returns the maximum numeric key of the provided table, or zero if the table has no numeric keys. Gaps in the table are ignored.

Parameters

Returns

table.move

Copies elements in table src from src[a] up to src[b] into table dst starting at index t. Equivalent to the assignment statement dst[t], ..., dst[t + (b - a)] = src[a], ..., src[b].

The default for dst is src. The destination range may overlap with the source range. Returns dst for convenience.

local sourceTable = {4, 5} -- Table of data to copy from
local destTable = {1, 2, 3} -- Table to add copied data to

table.move(
	sourceTable, -- Source table
	1, -- Index to start from in source table
	#sourceTable, -- Index up to (and including) from source table
	#destTable + 1, -- Index within destination table to move data into
	destTable -- Destination table
)
print(destTable) --> {1, 2, 3, 4, 5}

Parameters

Returns

table.pack

Returns a new table with all arguments stored into keys 1, 2, etc. and with a field "n" with the total number of arguments. Note that the resulting table may not be a sequence.

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

Parameters

Returns

table.remove

Removes from array t the element at position pos, returning the value of the removed element. When pos is an integer between 1 and #t, it shifts down the elements t[pos+1], t[pos+2], ..., t[#t] and erases element t[#t]. If the pos parameter is not provided, pos defaults to the length of the table removing the last element.

Parameters

Returns

table.sort

Sorts elements of array t in a given order, from t[1] to t[#t]. If comp is given, then it must be a function that receives two elements and returns true when the first element must come before the second in the final order.

The error invalid order function for sorting is thrown if both comp(a, b) and comp(b, a) return true.

If comp is not given, then the standard Luau operator < is used instead.

Parameters

Returns

table.unpack

Returns the elements from the given list. By default, i is 1 and j is the length of list.

Note that this same functionality is also provided by the global LuaGlobals.unpack() function.

Parameters

Returns