utils.table
Methods47
function Table.remove<V>(list: {integer, V} | V[], pos: nil | integer) -> Vfunction Table.sort<V>(list: V[], comp: fun(a: V, b: V) -> boolean | nil)function Table.pack<T>(...: ...T) -> (...T) & { n: integer }function Table.unpack<T, Start, End>(list: T, i: Start | nil, j: End | nil) -> unpack<T,Start,End>function Table.insert(list: table, pos: integer, value: any)function Table.insert(list: table, value: any) -> nilfunction Table.concat(list: table, sep: nil | string, i: nil | integer, j: nil | integer) -> stringfunction Table.map(tbl: table, func: function, ...: any) -> tableGiven a mapping function, creates a transformed copy of the table by calling the function for each element and using the result as the new value for the key. Passes the index as the second argument to the function.
@usage local a = {1, 2, 3, 4, 5} table.map(a, function(v) return v * 10 end) -- {10, 20, 30, 40, 50} @usage local a = {1, 2, 3, 4, 5} table.map(a, function(v, k, x) return v * k + x end, 100) -- {101, 104, 109, 116, 125}
function Table.filter(tbl: table, func: function, ...: any) -> tableGiven a filter function, creates a filtered copy of the table by calling the function for each element and removing entries for which it returns false. Passes the index as the second argument to the function.
@usage local a = {1, 2, 3, 4, 5} table.filter(a, function(v) return v % 2 == 0 end) -- {2, 4} @usage local a = {1, 2, 3, 4, 5} table.filter(a, function(v, k) return k % 2 == 1 end) -- {1, 3, 5}
function Table.find(tbl: table, func: function, ...: any) -> (value any, key any)Searches a table and returns the first value for which the search function returns true. Passes the index as the second argument to the function.
tbltablefuncfunction...any
valueanyThe first matching value.
keyanyThe key of the first matching value.
@usage local a = {1, 2, 3, 4, 5} table.find(a, function(v) return v % 2 == 0 end) -- 2, 2 @usage local a = {1, 2, 3, 4, 5} table.find(a, function(v, k) return k % 2 == 1 end) -- 1, 1
function Table.any(tbl: table, func: function, ...: any) -> booleanReturns true if the search function returns true for any element in the table. Passes the index as the second argument to the function.
StdLib.Utils.Table.find
@usage local a = {1, 2, 3, 4, 5} table.any(a, function(v) return v % 2 == 0 end) -- true @usage local a = {1, 2, 3, 4, 5} table.any(a, function(v, k) return k % 2 == 1 end) -- true
function Table.all(tbl: table, func: function, ...: any) -> booleanReturns true if the search function returns true for every element in the table. Passes the index as the second argument to the function.
function Table.each(tbl: table, func: function, ...: any) -> tbl tableApplies a function to each element in the table. Passes the index as the second argument to the function. Iteration stops if the function returns true for any element.
tbltablefuncfunction...any
tbltableThe original table.
@usage local a = {10, 20, 30, 40} table.each(a, function(v) game.print(v) end) -- prints 10, 20, 30, 40
function Table.contains(tbl: any[], value: any) -> booleanReturns true if the unkeyed array contains the given value.
tblany[]The array to search.
valueanyThe value to find.
- boolean
function Table.flatten(tbl: any[], level: uint | nil) -> flattened any[]Returns a recursively flattened copy of an array. Nested arrays are expanded into the resulting one-dimensional array. If level is supplied, recursion is limited to that many levels. Only integer-indexed arrays are flattened; associative tables are preserved.
tblany[]The array to flatten.
leveluint | nilMaximum recursion depth.
flattenedany[]
function Table.first(tbl: any[]) -> value anyReturns the first element of an array, or nil if the array is empty.
function Table.last(tbl: any[]) -> value anyReturns the last element of an array, or nil if the array is empty.
function Table.min(tbl: number[]) -> minimum nil | numberReturns the smallest numeric value in an array, or nil if the array is empty.
function Table.max(tbl: number[]) -> maximum nil | numberReturns the largest numeric value in an array, or nil if the array is empty.
function Table.sum(tbl: number[]) -> sum numberReturns the sum of all numeric values in an array. Returns 0 for an empty array.
function Table.avg(tbl: number[]) -> average nil | numberReturns the average of all numeric values in an array, or nil if the array is empty.
function Table.slice(tbl: any[], start: nil | integer, stop: nil | integer) -> slice any[]Returns a new array containing a slice of the given array.
tblany[]The array to slice.
startnil | integerStarting index. Defaults to 1.
stopnil | integerEnding index. Negative values count backwards from the end.
sliceany[]
@usage local a = {10, 20, 30, 40, 50} table.slice(a, 2, -2) -- {20, 30, 40}
function Table.merge(tblA: table, tblB: nil | table, array_merge: nil | boolean, raw: nil | boolean) -> tblA tableMerges two tables, with values from the second table overwriting values from the first. When array_merge is true, values from the second table are appended instead.
tblAtableThe destination table.
tblBnil | tableThe table to merge into
tblA.array_mergenil | booleanAppend values instead of merging by key.
rawnil | booleanUse
rawsetwhen merging associative tables.
tblAtableThe merged destination table.
@usage local args = table.merge({option1 = false}, {option1 = true})
function Table.array_combine(...: table) -> combined any[]Combines the values from multiple arrays into a new array.
...tableArrays to combine.
combinedany[]
function Table.dictionary_combine(...: table) -> combined tableCombines multiple dictionaries into a new table. Later tables overwrite values from earlier tables with the same key.
...tableDictionaries to combine.
combinedtable
function Table.dictionary_merge(tbl_a: table, tbl_b: table) -> merged tableCreates a merged dictionary without overwriting values already present in the first table.
@usage local a = {one = "A"} local b = {one = "Z", two = "B"} local merged = table.dictionary_merge(a, b) -- {one = "A", two = "B"}
function Table.deep_compare(t1: any, t2: any, ignore_mt: nil | boolean) -> booleanRecursively compares two values for equality. Table contents are compared recursively. Based on Factorio's util.lua implementation and work by Sparr, Nexela, and luacode.org.
t1anyt2anyignore_mtnil | booleanIgnore the
__eqmetamethod.
- boolean
function Table.compare(t1: any, t2: any, ignore_mt: nil | boolean) -> booleant1anyt2anyignore_mtnil | booleanIgnore the
__eqmetamethod.
- boolean
function Table.deep_copy<T>(object: T) -> copy TCreates a deep copy of a value without copying Factorio objects.
objectTThe value to copy.
copyT
@usage local copy = table.deep_copy(data.raw["stone-furnace"]["stone-furnace"])
function Table.deepcopy<T>(object: T) -> copy TobjectTThe value to copy.
copyT
function Table.full_copy<T>(object: T) -> copy TCreates a deep copy without preserving shared internal table references. Repeated references to the same nested table are copied independently.
objectTThe value to copy.
copyT
@usage local copy = table.full_copy(data.raw["stone-furnace"]["stone-furnace"])
function Table.fullcopy<T>(object: T) -> copy TobjectTThe value to copy.
copyT
function Table.flex_copy<T>(object: T) -> copy TCreates a flexible deep copy of a value. Tables implementing _copy_with may provide their own copy behavior.
objectTThe value to copy.
copyT
@usage local copy = table.flex_copy(data.raw["stone-furnace"]["stone-furnace"])
function Table.flexcopy<T>(object: T) -> copy TobjectTThe value to copy.
copyT
function Table.values(tbl: nil | table, sorted: nil | boolean, as_string: nil | boolean) -> values any[]Returns an array containing all values from a table.
tblnil | tableThe table whose values will be copied.
sortednil | booleanSort the resulting array.
as_stringnil | booleanConvert values to strings.
valuesany[]
function Table.keys(tbl: nil | table, sorted: nil | boolean, as_string: nil | boolean) -> keys any[]Returns an array containing all keys from a table.
tblnil | tableThe table whose keys will be copied.
sortednil | booleanSort the resulting array.
as_stringnil | booleanConvert keys to strings.
keysany[]
function Table.remove_keys(tbl: table, keys: any[]) -> tbl tableRemoves the specified keys from a table.
tbltableThe table to modify.
keysany[]Keys to remove.
tbltableThe modified table.
@usage local a = {1, 2, 3, 4} table.remove_keys(a, {1, 3}) -- {nil, 2, nil, 4} @usage local b = {k1 = 1, k2 = "foo", old_key = "bar"} table.removekeys(b, {"oldkey"}) -- {k1 = 1, k2 = "foo"}
function Table.count_keys(tbl: table, func: nil | function, ...: any) -> (count integer, total integer)Counts the keys in a table. If a filter function is supplied, also returns the number of entries for which it returns true.
tbltablefuncnil | functionOptional filter function.
...anyAdditional arguments passed to
func.
countintegerNumber of matching keys.
totalintegerTotal number of keys.
@usage local a = {1, 2, 3, 4, 5} table.count_keys(a) -- 5, 5 @usage local a = {1, 2, 3, 4, 5} table.count_keys(a, function(v, k) return k % 2 == 1 end) -- 3, 5
function Table.invert(tbl: table) -> inverted tableReturns a table with its keys and values exchanged. If the original values are not unique, which key is retained depends on iteration order.
@usage local a = {k1 = "foo", k2 = "bar"} table.invert(a) -- {foo = "k1", bar = "k2"}
function Table.size(tbl: table) -> integerReturns the number of entries in a table, using Factorio's table_size when available.
function Table.array_to_dictionary(tbl: table, as_bool: nil | boolean) -> tableConverts an array into a dictionary. String and numeric array values become keys whose values are either the original value or true. If the input is already a dictionary, it is returned unchanged.
tbltableas_boolnil | booleanMap each key to
trueinstead of its original value.
- table
@usage local a = {"v1", "v2"} table.arraytodictionary(a) -- {v1 = "v1", v2 = "v2"} @usage local a = {"v1", "v2"} table.arraytodictionary(a, true) -- {v1 = true, v2 = true}
function Table.unique_values(tbl: table) -> values any[]Returns an array containing the unique values from a table.
function Table.is_empty(tbl: table) -> booleanReturns true if the table contains no entries.
function Table.clear(tbl: table) -> tbl tableRemoves all entries from a table.
tbltableThe table to clear.
tbltableThe cleared table.
function Table.insert_string(tbl: string[], before: string, value: string) -> tbl string[]Inserts a string before the first occurrence of another string. If before is not found, the new value is appended to the array.
tblstring[]The array to modify.
beforestringThe value before which the new string will be inserted.
valuestringThe string to insert.
tblstring[]The modified array.
function Table.remove_string(tbl: string[], target: string) -> tbl string[]Removes the first occurrence of a string from an array. If the string is not found, the array is returned unchanged.
tblstring[]The array to modify.
targetstringThe string to remove.
tblstring[]The modified array.
function Table.scale(object: table | number, scale: number) -> scaled table | numberScales a number or all numeric values contained in a table. Tables are deep-copied before their numeric values are scaled recursively.
objecttable | numberThe number or table to scale.
scalenumberThe scale factor.
scaledtable | number
function Table.is_array(tbl: any) -> booleanReturns true if the value is a simple array with sequential integer keys starting at 1. For example, {"a", "b", "c"} is valid, while {value1 = "a"} or {[1] = "a", [3] = "b"} are not.