libraryDocs / table

table

librarysharedsource

The table library is a standard Lua library which provides functions to manipulate tables.

Classes & types

Functions

`table.clearIndexes`	Empties the indexes of the given table.
`table.clearKeys`	Empties the keys of the given table.
`table.copy`	Creates a shallow copy of the given table.
`table.count`	Returns the count of keys in the given table.
`table.create`	Creates a new table, filled with the given value and size.
`table.eject`	Ejects selected range of values from the given table.
`table.extract`	Extracts selected range of values from the table.
`table.flip`	Flips the keys with values in the given list (table).
`table.flipped`	Creates a flipped version of the given table.
`table.foreach`	Executes a provided function once for each table value.
`table.get`	Returns the value of the given key path.
`table.getIndex`	Returns the index of the value in the given table.
`table.getKey`	Returns the key of the value in the given table.
`table.inject`	Injects values from one table to another.
`table.insert`	Inserts a value into a table at the specified index.
`table.isEmpty`	Returns true if the given table is empty.
`table.isSequential`	Returns true if the given table is sequential.
`table.keys`	Returns list (table) of keys and length of this list.
`table.map`	Applies a function to each value of the table.
`table.move`	Moves elements from one table to another.
`table.pack`
`table.pairs`	Returns the list (table) of key/value pairs and length of this list.
`table.randomVI`	Returns a random index and its value from the given sequential table.
`table.randomVK`	Returns a random key and its value from the given table.
`table.range`	Returns a range of elements from the given table.
`table.removeByRange`	Removes a range of values from the given table.
`table.removeByValue`	Removes a value from the given table by its value.
`table.reverse`	Reverses all indexes in the given table.
`table.reversed`	Creates a reversed by indexes copy of the given table.
`table.set`	Sets the value of the given key path.
`table.shallowCopy`	Returns a shallow copy of the given table.
`table.shuffle`	Shuffles the given table.
`table.slice`	Returns a slice of the given table.
`table.transform`	Applies a function to each key/value pair of the table.
`table.truncate`	Truncates the given table.
`table.truncated`	Creates a truncated copy of the given table.
`table.values`	Returns list (table) of values and length of this list.

#table.clearIndexes

sharedsource

function table.clearIndexes(tbl: V[], tbl_length?: integer)

Empties the indexes of the given table.

Parameters

Name	Type	Description
`tbl`	`V[]`	The table to empty.
`tbl_length`optional	`integer`	The length of the table. Optionally, it should be used to speed up calculations.

#table.clearKeys

sharedsource

function table.clearKeys(tbl: table<K, V>)

Empties the keys of the given table.

Parameters

Name	Type	Description
`tbl`	`table<K, V>`	The table to empty.

#table.copy

sharednodiscardsource

function table.copy(tbl: T): T

Creates a shallow copy of the given table.

The original table is not modified.

The returned table is a shallow copy of the original table.

Parameters

Name	Type	Description
`tbl`	`T`	The table to copy.

Returns

Type	Name	Description
`T`	`copy`	The copied table.

#table.count

sharednodiscardsource

function table.count(tbl: table<K, V>): integer

Returns the count of keys in the given table.

Parameters

Name	Type	Description
`tbl`	`table<K, V>`	The table.

Returns

Type	Name	Description
`integer`	`key_count`	The count of keys.

#table.create

sharednodiscardsource

function table.create(value: V, ...: integer): V[]

Creates a new table, filled with the given value and size.

Parameters

Name	Type	Description
`value`	`V`	The value to fill the table with.
`...`	`integer`	The sizes of the table.

Returns

Type	Name	Description
`V[]`	`tbl`	The created table.

#table.eject

sharedsource

function table.eject(tbl: V[], start_position?: integer, end_position?: integer, tbl_length?: integer): V[], integer

Ejects selected range of values from the given table.

Parameters

Name	Type	Description
`tbl`	`V[]`	The table to remove values from.
`start_position`optional	`integer`	The start position.
`end_position`optional	`integer`	The end position.
`tbl_length`optional	`integer`	The length of the table. Optionally, it should be used to speed up calculations.

Returns

Type	Name	Description
`V[]`	`values`	The removed values.
`integer`	`values_length`	The count of removed values.

#table.extract

sharednodiscardsource

function table.extract(tbl: V[], start_position?: integer, end_position?: integer, step_size?: integer, tbl_length?: integer): V[], integer

Extracts selected range of values from the table.

Parameters

Name	Type	Description
`tbl`	`V[]`	The table to extract values from.
`start_position`optional	`integer`	The start position.
`end_position`optional	`integer`	The end position.
`step_size`optional	`integer`	The step size.
`tbl_length`optional	`integer`	The length of the table. Optionally, it should be used to speed up calculations.

Returns

Type	Name	Description
`V[]`	`values`	The extracted values.
`integer`	`length`	The length of the extracted values.

#table.flip

sharedsource

function table.flip(tbl: table<K, V>)

Flips the keys with values in the given list (table).

The original table is modified.

The keys are now the values and the values are now the keys.

{ key = value } -> { value = key }

Parameters

Name	Type	Description
`tbl`	`table<K, V>`	The table to flip.

#table.flipped

sharednodiscardsource

function table.flipped(tbl: table<K, V>): table<V, K>

Creates a flipped version of the given table.

The original table is not modified.

The flipped table has the values as keys and the keys as values.

{ key = value } -> { value = key }

Parameters

Name	Type	Description
`tbl`	`table<K, V>`	The table to flip.

Returns

Type	Name	Description
`table<V, K>`	`result`	The flipped table.

#table.foreach

sharedsource

function table.foreach(tbl: V[], fn: fun( index: integer, value: V ), tbl_length?: integer)

Executes a provided function once for each table value.

Parameters

Name	Type	Description
`tbl`	`V[]`	The table to execute the function on.
`fn`	`fun( index: integer, value: V )`	The function to execute.
`tbl_length`optional	`integer`	The length of the table. Optionally, it should be used to speed up execution.

#table.get

sharednodiscardsource

function table.get(tbl: table, path: string, separator?: integer): any

Returns the value of the given key path.

If the key path does not exist, or passes through a non-table value, returns nil.

Every separator splits the path, empty segments are "" keys, so "" is t[ "" ], ".a" is t[ "" ].a, "a." is t.a[ "" ] and "a..b" is t.a[ "" ].b.

Example:

lua

    local t = { a = { b = { c = { d = { e = "e value!" } } } } }
    print( table.get( t, "a.b.c.d.e" ) ) -- e value!

Parameters

Name	Type	Description
`tbl`	`table`	The table to get the value from.
`path`	`string`	The key path to get.
`separator`optional	`integer`	The separator of the key path, default is `0x2E`.

Returns

Type	Name	Description
`any`	`value`	The value of the key path.

#table.getIndex

sharednodiscardsource

function table.getIndex(tbl: V[], searchable: V, tbl_length?: integer): integer | nil

Returns the index of the value in the given table.

Returns nil if the value is not found in the table.

Parameters

Name	Type	Description
`tbl`	`V[]`	The table to search.
`searchable`	`V`	The value to search for.
`tbl_length`optional	`integer`	The length of the table. Optionally, it should be used to speed up calculations.

Returns

Type	Name	Description
`integer \| nil`	`index`	The index of the value.

#table.getKey

sharednodiscardsource

function table.getKey(tbl: table<K, V>, searchable: V): K | nil

Returns the key of the value in the given table.

Returns nil if the value is not found in the table.

Parameters

Name	Type	Description
`tbl`	`table<K, V>`	The table to search.
`searchable`	`V`	The value to search for.

Returns

Type	Name	Description
`K \| nil`	`key`	The key of the value.

#table.inject

sharedsource

function table.inject(destination: V[], source: V[], offset?: integer, start_position?: integer, end_position?: integer, destination_length?: integer, source_length?: integer)

Injects values from one table to another.

Parameters

Name	Type	Description
`destination`	`V[]`	The destination table.
`source`	`V[]`	The source table.
`offset`optional	`integer`	The position to inject.
`start_position`optional	`integer`	The start position.
`end_position`optional	`integer`	The end position.
`destination_length`optional	`integer`	The length of the destination table. Optionally, it should be used to speed up calculations.
`source_length`optional	`integer`	The length of the source table. Optionally, it should be used to speed up calculations.

#table.insert

sharedsource

function table.insert(tbl: V[], index: integer, value: V, tbl_length?: integer): integer

Inserts a value into a table at the specified index.

Parameters

Name	Type	Description
`tbl`	`V[]`	The table to insert the value into.
`index`	`integer`	The index to insert the value at.
`value`	`V`	The value to insert.
`tbl_length`optional	`integer`	The length of the table. Optionally, it should be used to speed up calculations.

Returns

Type	Name	Description
`integer`	`index`	The index of the inserted value.

Overloads

function table.insert(tbl: V[], value: V): integer

#table.isEmpty

sharednodiscardsource

function table.isEmpty(tbl: table): boolean

Returns true if the given table is empty.

Parameters

Name	Type	Description
`tbl`	`table`	The table to check.

Returns

Type	Name	Description
`boolean`	`result`	`true` if the table is empty, `false` otherwise.

#table.isSequential

sharednodiscardsource

function table.isSequential(tbl: table): boolean

Returns true if the given table is sequential.

Parameters

Name	Type	Description
`tbl`	`table`	The table to check.

Returns

Type	Name	Description
`boolean`	`is_sequential`	`true` if the table is sequential, `false` otherwise.

#table.keys

sharednodiscardsource

function table.keys(tbl: table<K, V>): K[], integer

Returns list (table) of keys and length of this list.

Parameters

Name	Type	Description
`tbl`	`table<K, V>`	The table.

Returns

Type	Name	Description
`K[]`	`key_lst`	The list of keys.
`integer`	`key_count`	The length of the list.

#table.map

sharednodiscardsource

function table.map(tbl: V[], fn: fun( index: integer, value: V ): V | nil, tbl_length?: integer): V[], integer

Applies a function to each value of the table.

The original table remains unchanged.

The returned table is a shallow copy of the original table.

Parameters

Name	Type	Description
`tbl`	`V[]`	The table to map.
`fn`	`fun( index: integer, value: V ): V \| nil`	The function to apply.
`tbl_length`optional	`integer`	The length of the table. Optionally, it should be used to speed up execution.

Returns

Type	Name	Description
`V[]`	`mapped`	The new mapped sequential table.
`integer`	`mapped_length`	The length of the new mapped sequential table.

#table.move

sharedsource

function table.move(source: V[], start_position?: integer, end_position?: integer, offset?: integer, destination?: V[], source_length?: integer): V[]

Moves elements from one table to another.

Parameters

Name	Type	Description
`source`	`V[]`	The source table.
`start_position`optional	`integer`	The start position of the source table, defaults to 1.
`end_position`optional	`integer`	The end position of the source table, defaults to the length of the source table.
`offset`optional	`integer`	The start position of the destination table, defaults to 1.
`destination`optional	`V[]`	The destination table, defaults to the source table.
`source_length`optional	`integer`	The length of the source table. Optionally, it should be used to speed up calculations.

Returns

Type	Name	Description
`V[]`	`destination`	Selected destination table.

#table.pack

nodiscardsource

function table.pack(...: V): V[]

Parameters

Name	Type	Description
`...`	`V`

Returns

Type	Name	Description
`V[]`

#table.pairs

sharednodiscardsource

function table.pairs(tbl: table<K, V>): table.Pair<K, V>[], integer

Returns the list (table) of key/value pairs and length of this list.

Parameters

Name	Type	Description
`tbl`	`table<K, V>`	The table.

Returns

Type	Name	Description
`table.Pair<K, V>[]`	`result`	The list of key/value pairs ( sequential table ).
`integer`	`result_length`	The length of the list.

#table.randomVI

sharednodiscardsource

function table.randomVI(tbl: V[], tbl_length?: integer): V, integer | nil

Returns a random index and its value from the given sequential table.

Parameters

Name	Type	Description
`tbl`	`V[]`	The sequential table.
`tbl_length`optional	`integer`	The length of the table. Optionally, it should be used to speed up calculations.

Returns

Type	Name	Description
`V`	`value`	The random value.
`integer \| nil`	`index`	The index of the value.

#table.randomVK

sharednodiscardsource

function table.randomVK(tbl: table<K, V>): V, K

Returns a random key and its value from the given table.

Parameters

Name	Type	Description
`tbl`	`table<K, V>`	The key-value table.

Returns

Type	Name	Description
`V`	`value`	The random value.
`K`	`key`	The key of the value.

#table.range

sharednodiscardsource

function table.range(tbl: V[], start_position?: integer, end_position?: integer, tbl_length?: integer): V[], integer

Returns a range of elements from the given table.

Parameters

Name	Type	Description
`tbl`	`V[]`	The table to get the range from.
`start_position`optional	`integer`	The start position of the range.
`end_position`optional	`integer`	The end position of the range.
`tbl_length`optional	`integer`	The length of the table. Optionally, it should be used to speed up calculations.

Returns

Type	Name	Description
`V[]`	`range_values`	The values of the range.
`integer`	`range_length`	The length of the range.

#table.removeByRange

sharedsource

function table.removeByRange(tbl: V[], start_position?: integer, end_position?: integer, tbl_length?: integer)

Removes a range of values from the given table.

Parameters

Name	Type	Description
`tbl`	`V[]`	The table to remove from.
`start_position`optional	`integer`	The start position.
`end_position`optional	`integer`	The end position.
`tbl_length`optional	`integer`	The length of the table. Optionally, it should be used to speed up calculations.

#table.removeByValue

sharedsource

function table.removeByValue(tbl: V[], value: V, tbl_length?: integer): integer | nil

Removes a value from the given table by its value.

Parameters

Name	Type	Description
`tbl`	`V[]`	The table to remove from.
`value`	`V`	The value that will be removed.
`tbl_length`optional	`integer`	The length of the table. Optionally, it should be used to speed up calculations.

Returns

Type	Name	Description
`integer \| nil`	`index`	The index of the value.

#table.reverse

sharedsource

function table.reverse(tbl: V[], tbl_length?: integer): V[], integer

Reverses all indexes in the given table.

The original table will be modified.

Example of a reversed table:

Old	New
`[ 1 ]`	`[ 5 ]`
`[ 2 ]`	`[ 4 ]`
`[ 3 ]`	`[ 3 ]`
`[ 4 ]`	`[ 2 ]`
`[ 5 ]`	`[ 1 ]`

Parameters

Name	Type	Description
`tbl`	`V[]`	The sequential table.
`tbl_length`optional	`integer`	The length of the table. Optionally, it should be used to speed up calculations.

Returns

Type	Name	Description
`V[]`	`tbl`	The reversed sequential table.
`integer`	`length`	The length of the reversed table.

#table.reversed

sharednodiscardsource

function table.reversed(tbl: V[], tbl_length?: integer): V[], integer

Creates a reversed by indexes copy of the given table.

The original table remains unchanged.

Example of a reversed table:

Old	New
`[ 1 ]`	`[ 5 ]`
`[ 2 ]`	`[ 4 ]`
`[ 3 ]`	`[ 3 ]`
`[ 4 ]`	`[ 2 ]`
`[ 5 ]`	`[ 1 ]`

Parameters

Name	Type	Description
`tbl`	`V[]`	The table to reverse.
`tbl_length`optional	`integer`	The length of the table. Optionally, it should be used to speed up calculations.

Returns

Type	Name	Description
`V[]`	`reversed`	The reversed table.
`integer`	`length`	The length of the reversed table.

#table.set

sharedsource

function table.set(tbl: table, path: string, value: any, separator?: integer)

Sets the value of the given key path.

Tables are created if they do not exist, non-table values on the path are replaced.

Every separator splits the path, empty segments are "" keys, so "" is t[ "" ], ".a" is t[ "" ].a, "a." is t.a[ "" ] and "a..b" is t.a[ "" ].b.

Example:

lua

    local t = {}
    table.set( t, "a.b.c.d.e", "e value!" )
    print( t.a.b.c.d.e ) -- e value!

Parameters

Name	Type	Description
`tbl`	`table`	The table to set the value in.
`path`	`string`	The key path.
`value`	`any`	The value to set.
`separator`optional	`integer`	The separator of the key path, default is `0x2E`.

#table.shallowCopy

sharednodiscardsource

function table.shallowCopy(tbl: V[]): V[]

Returns a shallow copy of the given table.

NOTE: This function is much faster that any other copy function and method, but works and efficient enough only for small tables (up to 1000 elements).

Parameters

Name	Type	Description
`tbl`	`V[]`	The table to copy.

Returns

Type	Name	Description
`V[]`		The copied table.

#table.shuffle

sharedsource

function table.shuffle(tbl: V[], tbl_length?: integer)

Shuffles the given table.

Parameters

Name	Type	Description
`tbl`	`V[]`	The table.
`tbl_length`optional	`integer`	The length of the table. Optionally, it should be used to speed up calculations.

#table.slice

sharednodiscardsource

function table.slice(tbl: V[], start_position?: integer, end_position?: integer, step?: integer, tbl_length?: integer): V[], integer

Returns a slice of the given table.

Parameters

Name	Type	Description
`tbl`	`V[]`	The table to slice.
`start_position`optional	`integer`	The start position of the slice.
`end_position`optional	`integer`	The end position of the slice.
`step`optional	`integer`	The step of the slice.
`tbl_length`optional	`integer`	The length of the table. Optionally, it should be used to speed up calculations.

Returns

Type	Name	Description
`V[]`	`slice`	The slice of the table.
`integer`	`length`	The length of the sliced table.

#table.transform

sharednodiscardsource

function table.transform(tbl: table<K, V>, fn: fun( key: K, value: V ): V | nil): table<K, V>

Applies a function to each key/value pair of the table.

The original table remains unchanged.

The returned table is a shallow copy of the original table.

Parameters

Name	Type	Description
`tbl`	`table<K, V>`	The key/value table.
`fn`	`fun( key: K, value: V ): V \| nil`	The function to apply.

Returns

Type	Name	Description
`table<K, V>`	`transformed`	The new transformed key/value table.

#table.truncate

sharedsource

function table.truncate(tbl: V[], new_length?: integer, tbl_length?: integer)

Truncates the given table.

The original table is modified.

The truncated table is a shallow copy of the original table.

Parameters

Name	Type	Description
`tbl`	`V[]`	The table to truncate.
`new_length`optional	`integer`	The length of the truncated table.
`tbl_length`optional	`integer`	The length of the original table. Optionally, it should be used to speed up calculations.

#table.truncated

sharednodiscardsource

function table.truncated(tbl: V[], tbl_length?: integer): V[]

Creates a truncated copy of the given table.

The original table is not modified.

The returned table is a shallow copy of the original table.

Parameters

Name	Type	Description
`tbl`	`V[]`	The table to truncate.
`tbl_length`optional	`integer`	The length of the truncated table. Optionally, it should be used to speed up calculations.

Returns

Type	Name	Description
`V[]`	`truncated`	The truncated table.

#table.values

sharednodiscardsource

function table.values(tbl: table<K, V>): V[], integer

Returns list (table) of values and length of this list.

Parameters

Name	Type	Description
`tbl`	`table<K, V>`	The table.

Returns

Type	Name	Description
`V[]`	`value_lst`	The list of values.
`integer`	`value_count`	The length of the list.