table

Supported Library

A library of table functions.

Nova note: Includes table.find, table.clear, and table.clone.

Description

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

clear Supported Sets all keys in the given table to nil.

Sets all keys in the given table to nil.

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.

clone Supported Returns a shallow copy of the provided table.

Returns a shallow copy of the provided table.

Returns an unfrozen shallow copy of the provided table.

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

local clone = table.clone(original)

concat Supported Returns the given range of table elements as a string where each element is separated by the given separator.

Returns the given range of table elements as a string where each element is separated by the given separator.

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.

create Supported Returns a new table populated with many instances of the specified value.

Returns a new table populated with many instances of the specified value.

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.

find Supported Returns the index of the first occurrence of needle within haystack starting from init.

Returns the index of the first occurrence of needle within haystack starting from init.

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

foreach Supported Iterates over the provided table, passing the key and value of each iteration over to the provided function.

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.

foreachi Supported Similar to table.foreach() except index-value pairs are passed instead of key-value pairs.

Similar to table.foreach() except index-value pairs are passed instead of key-value pairs.

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.

freeze Supported Makes the given table read-only.

Makes the given table read-only.

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.

getn Supported Returns the number of elements in the table passed.

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.

insert Supported Inserts the provided value to the target position of the array.

Inserts the provided value to the target position of the array.

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

insert Supported Appends the provided value to the end of the array.

Appends the provided value to the end of the array.

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

isfrozen Supported Returns true if the given table is frozen and false if it isn't frozen.

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

maxn Supported Returns the maximum numeric key of the provided table, or zero if the table has no numeric keys.

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

move Supported Copies the specified range of elements from one table to another.

Copies the specified range of elements from one table to another.

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}

pack Supported Returns a new table containing the provided values.

Returns a new table containing the provided values.

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

remove Supported Removes the specified element from the array, shifting later elements down to fill in the empty space if possible.

Removes the specified element from the array, shifting later elements down to fill in the empty space if possible.

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.

sort Supported Sorts table elements using the provided comparison function or the < operator.

Sorts table elements using the provided comparison function or the < operator.

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.

unpack Supported Returns all elements from the given list as a tuple.

Returns all elements from the given list as a tuple.

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 Global.LuaGlobals.unpack() function.

Roblox reference: table