table⚓︎

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

Functions⚓︎

`table.bininsert`⚓︎

Inserts a given value through BinaryInsert into an array-style table t, assuming t was sorted by comp.

If 'comp' is given, then it must be a function that receives two values in t and returns true when the first is less than the second. i.e., comp(a,b) == true would mean a is less than b.

If you want to sort in reverse order, you may set comp = function(a, b) return a > b end.

This function will return the index where value was inserted into t.

local result = table.bininsert(t, value, comp)

Parameters:

t (table)
value (unknown)
comp (fun(a, b): boolean): Optional.

Returns:

result (number)

`table.binsearch`⚓︎

Performs a binary search for a given value inside a specified array-style table tbl.

If the value is in tbl, then its corresponding index will be returned. Otherwise, this function will return nil. If findAll == true, then this binsearch will return the lowest and highest indices that store value. (These indices will be equal if there is only one copy of value in tbl.)

You can optionally provide a comp function. If provided, binsearch will treat tbl as if it had been sorted by table.sort(tbl, comp).

local index, highestMatch = table.binsearch(tbl, value, comp, findAll)

Parameters:

tbl (table)
value (unknown): The value to search for.
comp (fun(a, b): boolean): Optional. The function used to sort tbl. If not provided, then the standard < operator will be used.
findAll (boolean): Default: false. If true,

Returns:

index (integer, nil): An index such that tbl[index] == value, if such an index exists. nil otherwise. If findAll == true, this will be the smallest index such that tbl[index] == value.
highestMatch (integer, nil): If a match was found, and if findAll == true, then this will be the largest index such that tbl[index] == vale. nil otherwise.

`table.choice`⚓︎

Returns a random element from the given table.

local value, key = table.choice(t)

Parameters:

t (table)

Returns:

value (unknown): The randomly chosen value.
key (unknown): The table key of the chosen value.

`table.clear`⚓︎

This clears all keys and values from a table, but preserves the allocated array/hash sizes. This is useful when a table, which is linked from multiple places, needs to be cleared and/or when recycling a table for use by the same context. This avoids managing backlinks, saves an allocation and the overhead of incremental array/hash part growth.

Please note this function is meant for very specific situations. In most cases it's better to replace the (usually single) link with a new table and let the garbage collection do its work.

table.clear(table)

Parameters:

table (table): The table to clear.

`table.copy`⚓︎

Shallowly copies a table's contents to a destination table. If no destination table is provided, a new table will be created. Note that sub tables will not be copied, and will still refer to the same data.

local result = table.copy(from, to)

Parameters:

from (table)
to (table): Optional.

Returns:

result (table)

`table.copymissing`⚓︎

Copies a table's contents from one table to another, including subtitles. If a non-table key is already defined, it will not be overwritten. Metatables are not copied.

table.copymissing(to, from)

Parameters:

to (table)
from (table)

`table.deepcopy`⚓︎

Copies a table's contents. All subtables will also be copied, as will any metatable.

local result = table.deepcopy(t)

Parameters:

t (table)

Returns:

result (table)

`table.empty`⚓︎

Checks if a table is empty.

If deepCheck == true, then tables are allowed to have nested subtables, so long as those subtables are empty. e.g., table.empty({ {}, {} }, true) == true, while table.empty({ {}, {} }) == false.

local result = table.empty(t, deepCheck)

Parameters:

t (table)
deepCheck (boolean): Default: false. If true, subtables will also be checked to see if they are empty.

Returns:

result (boolean)

`table.filter`⚓︎

Creates a new table that results from using f to filter out elements of t. i.e., table.filter(t,f) will consist of only the pairs k, v of t for which f(k, v) was not false or nil. Any additional arguments will be passed to f. For example, table.filter(t, f, 10) would call f(k, v, 10) on each pair k, v of t.

Warning

Do not use this function on array-style tables, as it will not shift indices down after filtering out elements. Instead, you should use table.filterarray on array-style tables.

local result = table.filter(t, f, ...)

Parameters:

t (table)
f (fun(k: unknown, v: unknown, ...): boolean)
... (any): Additional parameters to pass to f.

Returns:

result (table): The result of using f to filter out elements of t.

`table.filterarray`⚓︎

Creates a new array-style table that results from using f to filter out elements of an array-style table arr. i.e., table.filterarray(arr, f) will consist of only the pairs i, v of arr for which f(i, v) was not false or nil. Any additional arguments will be passed to f. For example, table.filterarray(arr, f, 10) would call f(i, v, 10) on each value pair i, v of arr.

When an element gets filtered out, the index of subsequent items will be shifted down, so that the resulting table plays nicely with the # operator and the ipairs function.

local result = table.filterarray(arr, f, ...)

Parameters:

arr (table)
f (fun(i: integer, v: unknown, ...): boolean)
... (any): Additional parameters to pass to f.

Returns:

result (table): The result of using f to filter out elements of t.

`table.find`⚓︎

Returns the key for a given value, or nil if the table does not contain the value.

local result = table.find(t, value)

Parameters:

t (table)
value (unknown)

Returns:

result (unknown)

`table.get`⚓︎

Gets a value in a table. If the key doesn't exist in the table, a specified default value will be returned instead.

local result = table.get(t, key, defaultValue)

Parameters:

t (table)
key (any): The key to use to access the table.
defaultValue (any): The default value if the key didn't exist in the table.

Returns:

result (any)

`table.getset`⚓︎

Gets a value in a table. If the key doesn't exist in the table, a specified default value will be set in the table and returned instead.

local result = table.getset(t, key, defaultValue)

Parameters:

t (table)
key (any): The key to use to access the table.
defaultValue (any): The default value to set and return if the key didn't exist in the table.

Returns:

result (any)

`table.invert`⚓︎

Returns a copy of t with the keys and values flipped.

local result = table.invert(t)

Parameters:

t (table)

Returns:

result (table)

`table.keys`⚓︎

Returns an array-style table of all keys in the given table, t. Optionally, it will sort the returned table.

local keys = table.keys(t, sort)

Parameters:

t (table): The table to get keys for.
sort (boolean, function, nil): Optional. If true, the returned table will be sorted. If a function is passed, the table will be sorted using the given function.

Returns:

keys (table): An array of all table keys.

`table.map`⚓︎

Creates a new table consisting of key value pairs k, f(k, v), where k, v is a pair in t. Any additional arguments will be passed to f. For example, table.map(t, f, 10) would call f(k, v, 10) on each value v of t.

local result = table.map(t, f, ...)

Parameters:

t (table)
f (fun(k: unknown, v: unknown, ...): unknown)
... (any): Additional parameters to pass to f.

Returns:

result (table): The result of applying f to each value in t.

`table.new`⚓︎

This creates a pre-sized table. This is useful for big tables if the final table size is known and automatic table resizing is too expensive.

local newTable = table.new(narray, nhash)

Parameters:

narray (number): A hint for how many elements the array part of the table will have. Allocates fields for [0, narray].
nhash (number): A hint for how many elements the hash part of the table will have.

Returns:

newTable (table): The pre-sized table that was created.

`table.removevalue`⚓︎

Removes a value from a given table. Returns true if the value was successfully removed.

local result = table.removevalue(t, value)

Parameters:

t (table)
value (unknown)

Returns:

result (boolean)

`table.shuffle`⚓︎

Shuffles the table in place using the Fisher-Yates algorithm. Passing in table size as the second argument saves the function from having to get it itself.

table.shuffle(t, n)

Parameters:

t (table)
n (integer): Default: #t. The length of the array.

`table.size`⚓︎

Returns the number of elements inside the table. Unlike the length operator (#) this will work with any table.

local result = table.size(t)

Parameters:

t (table)

Returns:

result (number)

`table.traverse`⚓︎

This function is used to iterate over a graph-like table. You can specify the key of the subtable that contains the child nodes.

Each "node" is an object with a children table of other "nodes", each of which might have their own children. For example, a sceneNode is made up of niNodes, and each niNodes can have a list of niNode children. This is best used for recursive data structures like UI elements and sceneNodes etc.

local iterator = table.traverse(t, k)

Parameters:

t (table): A table to transverse.
k (string): Default: children. The subtable key.

Returns:

iterator (fun(): any)

Example: Iterate over all scene nodes attached to player.

In the example below, function onLoaded() will be called when the game has been successfully loaded.

For each scene nodes attached to the player, its type (node.RTTI.name) and name (node.name), will be printed to MWSE.log.

local function onLoaded()
    mwse.log("Player's scene graph:")
    for node in table.traverse({tes3.player.sceneNode}) do
        mwse.log("%s : %s", node.RTTI.name, node.name)
    end
end

event.register(tes3.event.loaded, onLoaded)

`table.values`⚓︎

Returns an array-style table of all values in the given table, t. Optionally, it will sort the returned table.

local values = table.values(t, sort)

Parameters:

t (table): The table to get values for.
sort (boolean, function, nil): Optional. If true, the returned table will be sorted. If a function is passed, the table will be sorted using the given function.

Returns:

values (table): An array of all table values.

`table.wrapindex`⚓︎

This function is used for calculating relative access into an array, such that accessing an element one past the array's size will instead return the position of the first element. Providing an index one before the start (note that this is 0, not -1) will instead give the index to the last element in the array.

local index = table.wrapindex(t, index)

Parameters:

t (table): The table whose size will determine the new wrapped index.
index (number): The initial provided index. If this is before or after the array, it will be cycled around.

Returns:

index (number)

table⚓︎

Functions⚓︎

table.bininsert⚓︎

table.binsearch⚓︎

table.choice⚓︎

table.clear⚓︎

table.copy⚓︎

table.copymissing⚓︎

table.deepcopy⚓︎

table.empty⚓︎

table.filter⚓︎

table.filterarray⚓︎

table.find⚓︎

table.get⚓︎

table.getset⚓︎

table.invert⚓︎

table.keys⚓︎

table.map⚓︎

table.new⚓︎

table.removevalue⚓︎

table.shuffle⚓︎

table.size⚓︎

table.traverse⚓︎

table.values⚓︎

table.wrapindex⚓︎

`table.bininsert`⚓︎

`table.binsearch`⚓︎

`table.choice`⚓︎

`table.clear`⚓︎

`table.copy`⚓︎

`table.copymissing`⚓︎

`table.deepcopy`⚓︎

`table.empty`⚓︎

`table.filter`⚓︎

`table.filterarray`⚓︎

`table.find`⚓︎

`table.get`⚓︎

`table.getset`⚓︎

`table.invert`⚓︎

`table.keys`⚓︎

`table.map`⚓︎

`table.new`⚓︎

`table.removevalue`⚓︎

`table.shuffle`⚓︎

`table.size`⚓︎

`table.traverse`⚓︎

`table.values`⚓︎

`table.wrapindex`⚓︎