table

This library provides generic functions for table manipulation. It provides all its functions inside the table table.

🧑‍💻API Source

---

🎒 Examples

local fruits = { "banana", "apple" }

-- Inserts at the end, then at the first position
table.insert(fruits, "orange")        -- { "banana", "apple", "orange" }
table.insert(fruits, 1, "grape")      -- { "grape", "banana", "apple", "orange" }

-- Removes the second element and returns it
local removed = table.remove(fruits, 2) -- "banana"

-- Sorts alphabetically
table.sort(fruits)                    -- { "apple", "grape", "orange" }

-- Joins all elements into a string
Console.Log(table.concat(fruits, ", ")) -- "apple, grape, orange"

🗿 Static Functions

	Returns	Name	Description
		insert	Inserts element value at position in tbl
		sort	Sorts the tbl elements in a given order, in-place, from tbl[1] to tbl[#tbl]
	table	move	Moves elements from the source_table to the dest_table
	any	remove	Removes from tbl the element at position index, returning the value of the removed element
	string	concat	Given a tbl where all elements are strings or numbers, returns the string with elements concatenated.

---

insert

Inserts element value at position in tbl, shifting up the elements tbl[position], tbl[position + 1], ···, tbl[#tbl]

table.insert(tbl, position?, value?)

Parameters

Type	Parameter	Default	Description
table	tbl	Required parameter	The table to insert the variable into.
number	position?	#tbl + 1	The position in the table to insert the variable. If the third argument is nil this argument becomes the value to insert at the end of given table.
any	value?		The variable to insert into the table.

---

sort

Sorts the tbl elements in a given order, in-place, from tbl[1] to tbl[#tbl]. If sorter is given, then it must be a function that receives two tbl elements and returns true when the first element must come before the second in the final order, so that, after the sort, i <= j implies not sorter(tbl[j], tbl[i]). If sorter is not given, then the standard Lua operator < is used instead.

The sorter function must define a consistent order; more formally, the function must define a strict weak order. (A weak order is similar to a total order, but it can equate different elements for comparison purposes).

The sort algorithm is not stable: Different elements considered equal by the given order may have their relative positions changed by the sort.

table.sort(tbl, sorter)

Parameters

Type	Parameter	Default	Description
table	tbl	Required parameter	The table to sort.
function	sorter	Required parameter	If specified, the function will be called with 2 parameters each. Return true in this function if you want the first parameter to come first in the sorted array.

---

move

Moves elements from the source_table to the dest_table, performing the equivalent to the following multiple assignment: dest_table[dest], ··· = a1[from], ···, source_table[to].

The destination range can overlap with the source range. The number of elements to be moved must fit in a Lua integer.

local ret = table.move(source_table, from, to, dest, dest_table?)

Parameters

Type	Parameter	Default	Description
table	source_table	Required parameter	The source table from which the elements are to be moved.
number	from	Required parameter	The start index of the source range from which the elements are to be moved.
number	to	Required parameter	The end index of the source range until which the elements are to be moved.
number	dest	Required parameter	The index within the destination table where the moved elements should be inserted. If this is not specified, the moved elements will be inserted at the end of the table.
table	dest_table?	source_table	The destination table to which the elements are to be moved. By default, this is the same as the source table.

Returns

Type	Description
table	The destination table

---

remove

Removes from tbl the element at position index, returning the value of the removed element.

When index is an integer between 1 and #tbl, it shifts down the elements tbl[index + 1], tbl[index + 2], ···, tbl[#tbl] and erases element tbl[#tbl].

The index can also be 0 when #tbl is 0, or #tbl + 1.

local ret = table.remove(tbl, index)

Parameters

Type	Parameter	Default	Description
table	tbl	Required parameter	The table to remove the value from.
number	index	Required parameter	The index of the value to remove.

Returns

Type	Description
any	The removed value

---

concat

Given a tbl where all elements are strings or numbers, returns the string tbl[start_pos] .. separator .. tbl[start_pos + 1] ... separator .. tbl[end_pos].

If start_pos is greater than end_pos, returns the empty string

local ret = table.concat(tbl, separator?, start_pos?, end_pos?)

Parameters

Type	Parameter	Default	Description
table	tbl	Required parameter	The table to concatenate.
string	separator?	""	A separator to insert between strings
number	start_pos?	1	The index to start at
number	end_pos?	#tbl	The index to end at

Returns

Type	Description
string	The concatenated string