Table

The Table module provides a wide variety of helpful utility functions to streamline common operations performed on Lua tables in a performant manner.

API

class Lua.Table: LibTSMModule

staticmethod GetKeys(tbl: table<<K>, any>, keys: <K>[])

Gets the keys from a table and inserts them into another.

Parameters:

• tbl (table<<K>, any>) – The table to get the keys of

• keys (<K>[]) – The table to insert the keys into

staticmethod KeyIterator(tbl: table<<K>, any>): fun(): <K>, table

Creates an iterator from the keys of a table.

Parameters:

tbl (table<<K>, any>) – The table to iterate over the keys of

Returns:

_1 (fun(): <K>) – Iterator with fields: key

staticmethod Filter(
    tbl: table,
    func: fun(key: any, value: any, ...any): boolean,
    ...: any
)

Uses a function to filter the entries in a table.

Parameters:

• tbl (table) – The table to be filtered

• func (fun(key: any, value: any, ...any): boolean) – The filter function which gets passed key, value, … and returns true if that entry should be removed from the table

• ... (any) – Optional arguments to be passed to the filter function

staticmethod FilterKeyNotInTable(tbl: table<<K>, any>, checkTbl: table<<K>, any>)

Filters entries in a table by checking if keys exist as keys in another table.

Parameters:

• tbl (table<<K>, any>) – The table to be filtered

• checkTbl (table<<K>, any>) – The table to check against

staticmethod FilterValueNotInTable(tbl: table<any, <V>>, checkTbl: table<<V>, any>)

Filters entries in a table by checking if values exist as keys in another table.

Parameters:

• tbl (table<any, <V>>) – The table to be filtered

• checkTbl (table<<V>, any>) – The table to check against

staticmethod RemoveByValue(tbl: table, value: any): number

Removes all occurences of the value in the table and returns the number removed.

Only the numerically-indexed entries are checked.

Parameters:

• tbl (table) – The table to remove the value from

• value (any) – The value to remove

staticmethod KeyByValue(tbl: table, value: any): any

Gets the table key by value.

Parameters:

• tbl (table) – The table to look through

• value (any) – The value to get the key of

staticmethod Count(tbl: table): number

Gets the number of entries in the table. This can be used when the count of a non-numerically-indexed table is desired (i.e. #tbl wouldn’t work).

Parameters:

tbl (table) – The table to get the number of entries in

staticmethod GetDistinctKey(tbl: table, value: any): any

Gets the distinct table key by value. This function will assert if the value is not found in the table or if more than one key is found.

Parameters:

• tbl (table) – The table to look through

• value (any) – The value to get the key of

staticmethod Equal(tbl1: table, tbl2: table): boolean

Checks if two tables have the same entries (non-recursively).

Parameters:

• tbl1 (table) – The first table to check

• tbl2 (table) – The second table to check

staticmethod CopyFrom(tbl: table<<K>, <V>>, srcTbl: table<<K>, <V>>)

Copies all entries into one table from another.

Parameters:

• tbl (table<<K>, <V>>) – The table to copy entries in to

• srcTbl (table<<K>, <V>>) – The table to copy entries from

staticmethod IsSorted(
    tbl: table,
    sortFunc?: fun(a: any, b: any): boolean,
    firstIndex?: number,
    lastIndex?: number
): boolean

Returns whether or not the table is currently sorted.

Parameters:

• tbl (table) – The table to check

• sortFunc? (fun(a: any, b: any): boolean) – The helper function to use to determine sort order

• firstIndex? (number) – The first index to check (defaults to 1)

• lastIndex? (number) – The last index to check (defaults to #tbl)

staticmethod Sort(tbl: table, sortFunc?: fun(a: any, b: any): boolean)

Sorts a table if it’s not already sorted.

Parameters:

• tbl (table) – The table to sort

• sortFunc? (fun(a: any, b: any): boolean) – The helper function to use to determine sort order

staticmethod IsSortedWithValueLookup(
    tbl: table,
    valueLookup: table<any, string | number>,
    firstIndex?: number,
    lastIndex?: number
): boolean

Checks whether or not the table is currently sorted with a value lookup table.

Parameters:

• tbl (table) – tbl The table to sort

• valueLookup (table<any, string | number>) – valueLookup The sort value lookup table

• firstIndex? (number) – The first index to check (defaults to 1)

• lastIndex? (number) – The last index to check (defaults to #tbl)

staticmethod MergeSortedWithValueLookup(
    tbl1: table,
    tbl2: table,
    result: table,
    valueLookup: table
)

Merges two sorted tables with a value lookup table.

Parameters:

• tbl1 (table) – The first table to merge

• tbl2 (table) – The second table to merge

• result (table) – The result table

• valueLookup (table) – The sort value lookup table

staticmethod SortWithValueLookup(
    tbl: table,
    valueLookup: table,
    reverse?: boolean,
    secondarySortFunc?: fun(a: any, b: any): boolean
)

Does a table sort with an extra value lookup step.

Parameters:

• tbl (table) – The table to sort

• valueLookup (table) – The sort value lookup table

• reverse? (boolean) – Reverse the sort order

• secondarySortFunc? (fun(a: any, b: any): boolean) – A secondary sort function for when the sort values are equal

staticmethod SetReadOnly(tbl: table)

Sets a table as read-only (modifications aren’t checked).

Parameters:

tbl (table) – The table to make read-only

staticmethod GetCommonValuesSorted(tbls: <V>[][], result: <V>[])

Gets the common values from two or more sorted tables.

Parameters:

• tbls (<V>[][]) – The tables to compare

• result (<V>[]) – The result table

staticmethod RotateRight(
    tbl: table,
    amount: number,
    startIndex?: number,
    endIndex?: number
): boolean

Rotates the values in a table to the right and returns whether or not the table was changed.

Parameters:

• tbl (table) – The table to rotate

• amount (number) – The number of positions to rotate right by (can be negative to rotate left)

• startIndex? (number) – Used with endIndex to specify a sub-range of the table to rotate

• endIndex? (number) – Used with startIndex to specify a sub-range of the table to rotate

staticmethod InsertFill(
    tbl: table,
    startIndex: number,
    numValues: number,
    fillValue: any
)

Inserts fill values into the table.

Parameters:

• tbl (table) – The table to insert into

• startIndex (number) – The index to insert at

• numValues (number) – The number of fill values to insert

• fillValue (any) – The fill value to insert

staticmethod Move(tbl: table, fromIndex: number, toIndex: number)

Moves a value in the table from one index to another in an efficient way.

Parameters:

• tbl (table) – The table

• fromIndex (number) – The index of the value to move

• toIndex (number) – The index to move the value to

staticmethod Reverse(tbl: table)

Reverses a table in place.

Parameters:

tbl (table) – The table to reverse

staticmethod GetDiffOrdered(
    old: table,
    new: table,
    inserted: number[],
    removed: number[]
): boolean

Gets the diff between two lists with order taken into account and returns whether or not we were successful.

Parameters:

• old (table) – The old list of items

• new (table) – The new list of items

• inserted (number[]) – A result table to store the indexes which were added to the new table

• removed (number[]) – A result table to store the indexes which were removed from the old table

staticmethod GetChangedKeys(
    old: table<string, any>,
    new: table<string, any>,
    result: table<string, true>
)

Gets the keys which were changed between two tables.

Parameters:

• old (table<string, any>) – The old table

• new (table<string, any>) – The new table

• result (table<string, true>) – A result table to store the keys which were changed (with a value of true)

staticmethod StrideIterator(tbl: table, numFields: number): fun(): number, ...unknown, table, number

Iterates over a table with a stride.

NOTE: This iterator must be run to completion and not be interrupted (i.e. with a break or return).

Parameters:

• tbl (table) – The table to iterate over.

• numFields (number) – The number of fields to unpack with each iteration

Returns:

_1 (fun(): number, ...unknown) – Iterator with fields: index, {numFields…}

staticmethod InsertMultiple(tbl: table, ...: any)

Inserts multiple values into the table.

Parameters:

• tbl (table) – The table to insert into

• ... (any) – Values to insert

staticmethod InsertMultipleAt(tbl: table, index: number, ...: any)

Inserts multiple values into the table at a specified index.

Parameters:

• tbl (table) – The table to insert into

• index (number) – The index to insert at

• ... (any) – Values to insert

staticmethod InsertFrom(
    tbl: table,
    srcTbl: table,
    srcStartIndex?: number,
    srcEndIndex?: number
)

Inserts values at the end of a table from a subrange of another table.

Parameters:

• tbl (table) – The table to insert into

• srcTbl (table) – The table to insert values from

• srcStartIndex? (number) – The index of the first value in the source table to insert

• srcEndIndex? (number) – The index of the last value in the source table to insert

staticmethod InsertFromIterator(
    tbl: <T>[],
    iterFunc: IteratorObject | fun(): number, <T>,
    iterObj: any,
    iterIndex: any
)

Inserts values from an iterator into the table.

Parameters:

• tbl (<T>[]) – The table to insert into

• iterFunc (IteratorObject | fun(): number, <T>) – The iterator function

• iterObj (any) – The iterator object

• iterIndex (any) – The iterator index

staticmethod RemoveRange(tbl: table, startIndex: number, endIndex: number)

Removes a range of indexes from the table.

Parameters:

• tbl (table) – The table

• startIndex (number) – The first index to remove

• endIndex (number) – The last index to remove

staticmethod UnpackAndWipe(tbl: table): (...: unknown)

Returns the result of calling unpack() on the table and wipes it.

Parameters:

tbl (table) – The table

staticmethod ReverseIPairs(tbl: <V>[]): fun(): number, <V>, <V>[], number

Iterates over the table in a similar fasion to ipairs() but in reverse.

Returns:

_1 (fun(): number, <V>) – Iterator with fields: index, value

staticmethod WipeAndDeallocate(tbl: table)

Wipes a table and deallocates the extra memory used by its keys.