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.

string table.concat ( array t, string sep = "", int i = 1, int j = #t )
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.

void table.foreach ( array t, function f )
Iterates over the provided table, passing the key and value of each iteration over to the provided function.

void table.foreachi ( array t, function f )
This is similar to table.foreach() except that index-value pairs are passed, not key-value pairs.

number table.getn ( array t )
Returns the number of elements in the table passed.

void table.insert ( array t, number pos = #t+1, Variant value )
Appends the provided value to the end of array t. The optional pos value defaults to #t+1, meaning that value is inserted at the end of array t unless otherwise specified.

Variant table.remove ( array t, number pos = #t )
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]. The index pos can also be 0 when #t is 0 or #t+1; in those cases, the function erases the element t[pos].

void table.sort ( array t, function comp = nil )
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 (so that not comp(t[i+1],t[i]) will be true after the sort). If comp is not given, then the standard Lua operator `<` is used instead.

Variant table.pack ( Variant 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 This function was backported to Roblox’s version of Lua (5.1).

Tuple table.unpack ( table list, number i = 1, number j = #list )
Returns the elements from the given list. This function is equivalent to: return list[i], list[i+1], ..., list[j] By default, `i` is 1 and `j` is the length of `list`. local t = {1, 2, 3} local one, two, three = table.unpack(t) print(one, two, three) -- 1 2 3 This function was backported to Roblox’s version of Lua (5.1). The same functionality is also provided by the built-in `unpack` function.

table table.move ( table a1, number f, number e, number t, table a2 = a1 )
Moves elements from table `a1` to table `a2`, performing the equivalent to the following multiple assignment: `a2[t], ... = a1[f], ..., a1[e]`. The default for `a2` is `a1`. The destination range can overlap with the source range. The number of elements to be moved must fit in a Lua integer. Returns the destination table `a2`. src = {"a", "b", "c", "d", "e"} dst = {"v", "w", "x", "y", "z"} table.move(src, 2, 4, 1, dst) -- Move index 2 through 4 in src to index 1 in dst print(table.concat(dst)) --> bcdyz This function was backported to Roblox’s version of Lua (5.1).

table table.create ( number count, Variant 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.

table.clear ( table table )
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.

Variant table.find ( table haystack, Variant needle, number 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