TableClass

TableClass

table.add

Adds a second associative table to a first associative table, merging the second table into the first.

Parameters

• table1 (table) - The table to add the value to.
• table2 (table) - The table to add to the first table.

Returns

table - The first table with the second table added.

Examples

table.add({ a = 1 }, { b = 2 })
-- { a = 1, b = 2 }

table.add({ a = 1, b = 2 }, { b = 3, c = 4 })
-- { a = 1, b = 3, c = 4 }

table.allocate

Allocates a new table with given an initial indexed table and a specification for the new table.

The specification can be:

• another indexed table, in which case the new table will be created with the same values as the source table, but with the values in the spec table applied to each corresponding value in the source table. The second table must have the same number of elements as the source table.
• a function, in which case the function will be applied to each value in the source table to produce the values in the new table.
• a single type, in which case all values in the new table will be of that type

Parameters

• source (table) - The table to copy.
• spec (table) - The specification for the new table.

Returns

table - The new table.

Examples

table.allocate({"a", "b", "c"}, "x")
-- {a = "x", b = "x", c = "x"}

table.allocate({"a","b","c"}, {1, 2, 3})
-- {a = 1, b = 2, c = 3}

table.allocate({ "a", "b", "c" }, function(k, v)
 return string.byte(v)
end)
-- {a = 97, b = 98, c = 99}

table.associative

Returns true if the table is associative, false otherwise.

Parameters

• t (table) - The table to check.

Returns

boolean - True if the table is associative, false otherwise.

Examples

table.associative({ a = 1, b = 2 })
-- true

table.associative({ 1, 2, 3 })
-- false

table.chunk

Returns a table of tables, each containing a slice of the original table of specified size. If there are not enough elements to fill the last chunk, the last chunk will contain the remaining elements.

Parameters

• t (table) - The table to chunk.
• size (number) - The size of each chunk.

Returns

table - A table of tables, each containing a slice of the original table.

Examples

table.chunk({1, 2, 3, 4, 5}, 2)
-- {{1, 2}, {3, 4}, {5}}

table.concat

Creates a new table by concatenating the original table with any additional arrays and/or values. If the arguments contains tables, they will be concatenated with the original table. Otherwise, the values will be added to the end of the original table.

Parameters

• tbl (table) - The first table to concatenate.
• ... (any) - Additional tables and/or values to concatenate.

Returns

table - A new table containing the concatenated tables.

Examples

table.concat({1}, 2, {3}, {{4}})
-- {1, 2, 3, {4}}

table.drop

Drops the first n elements from an indexed table.

Parameters

• tbl (table) - The table to drop elements from.
• n (number) - The number of elements to drop.

Returns

table - A new table with the first n elements removed.

table.drop_right

Drops the last n elements from an indexed table.

Parameters

• tbl (table) - The table to drop elements from.
• n (number) - The number of elements to drop.

Returns

table - A new table with the last n elements removed.

table.element_of

Returns a random element from an indexed table.

Parameters

• list (table) - The table to choose an element from.

Returns

any - A random element from the table.

Examples

table.element_of({1, 2, 3})
-- 2

table.element_of_weighted

Returns a random element from the keys of a table, with each value representing a weight.

Parameters

• list (table) - The table to choose an element from.

Returns

any - A random element from the table.

Examples

table.element_of_weighted({ [1] = 10, [2] = 20, [3] = 70 })
-- 3

table.fill

Fills an indexed table with a value.

If the start index is not provided, it will fill from the beginning of the table. If the stop index is not provided, it will fill to the end of the table.

Parameters

• tbl (table) - The table to fill.
• value (any) - The value to fill the table with.
• start (number?) - The start index to fill.
• stop (number?) - The stop index to fill.

Returns

table - The filled table.

Examples

table.fill({1, 2, 3, 4, 5}, "x")
-- {"x", "x", "x", "x", "x"}

table.fill({1, 2, 3, 4, 5}, "x", 2)
-- {1, "x", "x", 4, 5}

table.fill({1, 2, 3, 4, 5}, "x", 2, 4)
-- {1, "x", "x", "x", 5}

table.find

Returns the index of the first element in a table that satisfies a predicate function.

Parameters

• tbl (table) - The table to find the index of the first element in.
• fn (function) - The predicate function to satisfy.

Returns

number|nil - The index of the first element that satisfies the predicate function, or nil if no element satisfies the predicate.

Examples

table.find({1, 2, 3, 4, 5}, function(v) return v > 3 end)
-- 4

table.find_last

Returns the index of the last element in a table that satisfies a predicate function.

Parameters

• tbl (table) - The table to find the index of the last element in.
• fn (function) - The predicate function to satisfy.

Returns

number? - The index of the last element that satisfies the predicate function, or nil if no element satisfies the predicate.

Examples

table.find_last({1, 2, 3, 4, 5}, function(v) return v > 3 end)
-- 4

table.flatten

Flattens a table of tables into a single table.

Parameters

• tbl (table) - The table to flatten.

Returns

table - A new table containing the flattened table.

Examples

table.flatten({1, {2, {3, {4}}, 5}})
-- {1, 2, 3, 4, 5}

table.flatten_deeply

Flattens a table of tables into a single table recursively.

Parameters

• tbl (table) - The table to flatten recursively.

Returns

table - A new table containing the flattened table.

Examples

table.flatten_deeply({1, {2, {3, {4}}, 5}})
-- {1, 2, 3, 4, 5}

table.functions

Returns a table of the functions in a table.

Parameters

• tbl (table) - The table to get the functions from.
• inherited (boolean?) - Whether to include inherited functions.

Returns

table - A table of the functions in the table.

Examples

table.functions({a = 1, b = 2, c = end})
-- {c = function()}

table.includes

Returns true if an indexed table includes a value, false otherwise.

Parameters

• tbl (table) - The table to check.
• value (any) - The value to check for.

Returns

boolean - True if the table includes the value, false otherwise.

Examples

table.includes({1, 2, 3}, 2)
-- true

table.indexed

Returns true if a table is indexed, false otherwise.

Parameters

• t (table) - The table to check.

Returns

boolean - True if the table is indexed, false otherwise.

Examples

table.indexed({1, 2, 3})
-- true

table.indexed({ a = 1, b = 2 })
-- false

table.initial

Returns an indexed table with the last element removed from the original indexed table.

Parameters

• tbl (table) - The table to remove the last element from.

Returns

table - A new table with the last element removed.

Examples

table.initial({1, 2, 3, 4, 5})
-- {1, 2, 3, 4}

table.map

Returns a new table with a function applied to each element of the original table, transforming each element into a new value.

Parameters

• t (table) - The table to map over.
• fn (function) - The function to map over the table.
• ... (any) - Additional arguments to pass to the function.

Returns

table - A new table with the function applied to each element.

Examples

table.map({1, 2, 3}, function(v) return v * 2 end)
-- {2, 4, 6}

table.n_add

Appends or inserts a second indexed table into a first indexed table at a specified index.

If the index is not provided, the second table is appended to the end of the first table. If the index is provided, the second table is inserted into the first table at the specified index.

Parameters

• tbl1 (table) - The first table to add the value to.
• tbl2 (table) - The second table to add to the first table.
• index (number?) - The index to add the second table to.

Returns

table - The first table with the second table added.

Examples

table.n_add({1, 2, 3}, {4, 5, 6})
-- {1, 2, 3, 4, 5, 6}

table.n_add({1, 2, 3}, {4, 5, 6}, 2)
-- { 1, 4, 5, 6, 2, 3 }

table.n_cast

Casts a value to an indexed table if it is not already one.

Parameters

• ... (any) - The value to cast.

Returns

table - A new indexed table with the value or the value itself if it is already indexed.

Examples

table.n_cast(1)
-- {1}

table.n_cast({1, 2, 3})
-- {1, 2, 3}

table.n_distinct

Returns a new table with the distinct elements of an indexed table.

Parameters

• t (table) - The table to get the distinct elements from.

Returns

table - A new table with the distinct elements.

Examples

table.n_distinct({1, 2, 3, 2, 1})
-- {1, 2, 3}

table.n_uniform

Returns true or false if all elements in an indexed table are of the same type. If a type is not provided, it will check if all elements are of the same type as the first element in the table.

Parameters

• t (table) - The table to check.
• typ (string?) - The type to check for.

Returns

boolean - True if all elements are of the same type, false otherwise.

Examples

table.n_uniform({1, 2, 3}, "number")
-- true

table.new_weak

Creates a new table with weak references. Valid options are "v" for weak values, "k" for weak keys, and "kv" or "vk" for weak keys and values.

Parameters

• opt (string?) - The reference type.

Returns

table - A new table with weak references.

Examples

table.new_weak("v")
-- A table with weak value references

table.object

Returns true if a table is an object, false otherwise.

Parameters

• tbl (table) - The table to check.

Returns

boolean - True if the table is an object, false otherwise.

Examples

local object1 = {1,2,3}
local object2 = {}
setmetatable(object2, { __index = object1 })

table.object(object1)
-- false
table.object(object2)
-- true

table.pop

Removes and returns the last element of an indexed table.

Parameters

• t (table) - The table to remove the last element from.

Returns

any - The last element of the table.

Examples

local sample = {1, 2, 3}
table.pop(sample)
-- 3
-- sample = {1, 2}

table.properties

Returns a table of the properties of a table. This function only returns the properties of the table itself, not the properties of any metatables, and no functions.

If the inherited parameter is true, it will include the properties of any metatables.

Parameters

• tbl (table) - The table to get the properties from.
• inherited (boolean?) - Whether to include inherited properties.

Returns

table - A table of the properties of the table.

Examples

table.properties({a = 1, b = 2})
-- {a = 1, b = 2}

table.push

Adds a value to the end of an indexed table, returning the new length of the table.

Parameters

• t (table) - The table to append the value to.
• v (any) - The value to append to the table.

Returns

number - The new length of the table.

Examples

table.push({1, 2, 3}, 4)
-- 4

table.reduce

Reduces an indexed table to a single value using a reducer function.

Parameters

• t (table) - The table to reduce.
• fn (function) - The reducer function.
• initial (any?) - The initial value.

Returns

any - The reduced value.

Examples

table.reduce({1, 2, 3}, function(acc, v) return acc + v end, 0)
-- 6

table.remove

Removes and returns a slice of a table from the start index to the stop index. If the stop index is not provided, it will only remove the element at the start index. A second return value is also provided containing the removed slice.

Parameters

• t (table) - The table to remove the slice from.
• start (number) - The start index of the slice.
• stop (number?) - The stop index of the slice.

Returns

table - A new table containing the removed slice.

Examples

table.remove({1, 2, 3, 4, 5}, 2, 4)
-- {1, 5}
-- {2, 3, 4}

table.remove({1, 2, 3, 4, 5}, 2)
-- {1, 3, 4, 5}
-- {2}

table.reverse

Reverses an indexed table.

Parameters

• tbl (table) - The table to reverse.

Returns

table - A new reversed table.

Examples

table.reverse({1, 2, 3})
-- {3, 2, 1}

table.shift

Removes and returns the first element of an indexed table.

Parameters

• t (table) - The table to remove the first element from.

Returns

any - The first element of the table.

Examples

table.shift({1, 2, 3})
-- 1

table.slice

Returns a slice of an indexed table.

Parameters

• t (table) - The table to slice.
• start (number?) - The start index.
• stop (number?) - The stop index.

Returns

table - A new table with the slice.

Examples

table.slice({1, 2, 3, 4, 5}, 2, 4)
-- {2, 3, 4}

table.uniq

Returns a new table with the unique elements of an indexed table.

Parameters

• tbl (table) - The table to get the unique elements from.

Returns

table - A new table with the unique elements.

Examples

table.uniq({1, 2, 3, 2, 1})
-- {1, 2, 3}

table.unshift

Adds a value to the beginning of an indexed table.

Parameters

• t (table) - The table to add the value to.
• v (any) - The value to add to the table.

Returns

number - The new length of the table.

Examples

table.unshift({1, 2, 3}, 4)
-- 4

table.unzip

Unzips a table of tables into a table of tables. The index of the new sub-tables will be the same as the index of the sub-tables in the original table.

Parameters

• tbl (table) - The table to unzip.

Returns

table - A table of tables.

Examples

local combined = {{"John", 25}, {"Jane", 30}, {"Jim", 35}}
local names, ages = unpack(table.unzip(combined))
-- names = {"John", "Jane", "Jim"}
-- ages = {25, 30, 35}

table.values

Returns an indexed table with the values of an associative table.

Parameters

• t (table) - The table to get the values from.

Returns

table - An indexed table with the values.

Examples

table.values({a = 1, b = 2})
-- {1, 2}

table.walk

Returns an iterator function that can be used to walk over an indexed table.

Parameters

• tbl (table) - The table to walk over.

Returns

function - An iterator function.

Examples

table.walk({1, 2, 3}, function(v) print(v) end)
-- 1
-- 2
-- 3

table.weak

Returns a new table with weak references. Valid options are "v" for weak values, "k" for weak keys, and "kv" or "vk" for weak keys and values.

Parameters

• opt (string?) - The reference type.

Returns

table - A new table with weak references.

Examples

table.weak("v")
-- A table with weak value references

table.zip

Zips multiple tables together. The tables must all be of the same length.

--- @example

local names = {"John", "Jane", "Jim"}
local ages = {25, 30, 35}

table.zip(names, ages)
-- {{"John", 25}, {"Jane", 30}, {"Jim", 35}}

Parameters

• ... (table) - The tables to zip together.

Returns

table - A new table containing the zipped tables.