Module StdLib.Table
Extends Lua 5.2 table.
Functions
map (tbl, func[, ...]) | Given a mapping function, creates a transformed copy of the table by calling the function for each element in the table, and using the result as the new value for the key. |
filter (tbl, func[, ...]) | Given a filter function, creates a filtered copy of the table by calling the function for each element in the table, and filtering out any key-value pairs for non-true results. |
find (tbl, func[, ...]) | Given a candidate search function, iterates over the table, calling the function for each element in the table, and returns the first element the search function returned true. |
any (tbl, func[, ...]) | Given a candidate search function, iterates over the table, calling the function for each element in the table, and returns true if search function returned true. |
each (tbl, func[, ...]) | Given a function, apply it to each element in the table. |
flatten (tbl[, level]) | Returns a new array that is a one-dimensional recursive flattening of the given array. |
first (tbl) | Given an array, returns the first element or nil if no element exists. |
last (tbl) | Given an array, returns the last element or nil if no elements exist. |
min (tbl) | Given an array of only numeric values, returns the minimum or nil if no element exists. |
max (tbl) | Given an array of only numeric values, returns the maximum or nil if no element exists. |
sum (tbl) | Given an array of only numeric values, return the sum of all values, or 0 for empty arrays. |
avg (tbl) | Given an array of only numeric values, returns the average or nil if no element exists. |
merge (tblA, tblB[, array_merge=false]) | Merges two tables — values from first get overwritten by the second. |
deepcopy (object) | Creates a deep copy of table without copying Factorio objects. |
values (tbl[, sorted[, as_string]]) | Returns a copy of all of the values in the table. |
keys (tbl[, sorted[, as_string]]) | Returns a copy of all of the keys in the table. |
remove_keys (tbl, keys) | Removes keys from a table by setting the values associated with the keys to nil. |
count_keys (tbl[, func[, ...]]) | Returns the number of keys in a table, if func is passed only count keys when the function is true. |
invert (tbl) | Returns an inverted (***{[value] = key,...}***) copy of the given table. |
size (table) | Return the size of a table using built in table_size function |
arr_to_bool (tbl) | For all string or number values in an array map them to a key = true table |
Functions
- map (tbl, func[, ...])
-
Given a mapping function, creates a transformed copy of the table
by calling the function for each element in the table, and using
the result as the new value for the key. Passes the index as second argument to the function.
Parameters:
- tbl table the table to be mapped to the transform
- func function the function to transform values
- ... additional arguments passed to the function (optional)
Returns:
-
table
a new table containing the keys and mapped values
Usage:
a= { 1, 2, 3, 4, 5} table.map(a, function(v) return v * 10 end) --produces: { 10, 20, 30, 40, 50 }
a = {1, 2, 3, 4, 5} table.map(a, function(v, k, x) return v * k + x end, 100) --produces { 101, 104, 109, 116, 125}
- filter (tbl, func[, ...])
-
Given a filter function, creates a filtered copy of the table
by calling the function for each element in the table, and
filtering out any key-value pairs for non-true results. Passes the index as second argument to the function.
Parameters:
- tbl table the table to be filtered
- func function the function to filter values
- ... additional arguments passed to the function (optional)
Returns:
-
table
a new table containing the filtered key-value pairs
Usage:
a= { 1, 2, 3, 4, 5} table.filter(a, function(v) return v % 2 == 0 end) --produces: { 2, 4 }
a = {1, 2, 3, 4, 5} table.filter(a, function(v, k, x) return k % 2 == 1 end) --produces: { 1, 3, 5 }
- find (tbl, func[, ...])
-
Given a candidate search function, iterates over the table, calling the function
for each element in the table, and returns the first element the search function returned true.
Passes the index as second argument to the function.
Parameters:
- tbl table the table to be searched
- func function the function to use to search for any matching element
- ... additional arguments passed to the function (optional)
Returns:
-
nil or Mixed
the first found value, or nil if none was found
Usage:
a= { 1, 2, 3, 4, 5} table.find(a, function(v) return v % 2 == 0 end) --produces: 2
a = {1, 2, 3, 4, 5} table.find(a, function(v, k, x) return k % 2 == 1 end) --produces: 1
- any (tbl, func[, ...])
-
Given a candidate search function, iterates over the table, calling the function
for each element in the table, and returns true if search function returned true.
Passes the index as second argument to the function.
Parameters:
- tbl table the table to be searched
- func function the function to use to search for any matching element
- ... additional arguments passed to the function (optional)
Returns:
-
boolean
true if an element was found, false if none was found
Usage:
a= { 1, 2, 3, 4, 5} table.any(a, function(v) return v % 2 == 0 end) --produces: true
a = {1, 2, 3, 4, 5} table.any(a, function(v, k, x) return k % 2 == 1 end) --produces: true
- each (tbl, func[, ...])
-
Given a function, apply it to each element in the table.
Passes the index as the second argument to the function.
Iteration is aborted if the applied function returns true for any element during iteration.
Parameters:
- tbl table the table to be iterated
- func function the function to apply to elements
- ... additional arguments passed to the function (optional)
Returns:
-
table
the table where the given function has been applied to its elements
Usage:
a = {10, 20, 30, 40} table.each(a, function(v) game.print(v) end) --prints 10, 20, 30, 40, 50
- flatten (tbl[, level])
-
Returns a new array that is a one-dimensional recursive flattening of the given array.
For every element that is an array, extract its elements into the new array.
The optional level argument determines the level of recursion to flatten. > This function flattens an integer-indexed array, but not an associative array.
Parameters:
- tbl array the array to be flattened
- level uint recursive levels, or no limit to recursion if not supplied (optional)
Returns:
-
array
a new array that represents the flattened contents of the given array
- first (tbl)
-
Given an array, returns the first element or nil if no element exists.
Parameters:
- tbl array the array
Returns:
-
nil or Mixed
the first element
- last (tbl)
-
Given an array, returns the last element or nil if no elements exist.
Parameters:
- tbl array the array
Returns:
-
nil or Mixed
the last element or nil
- min (tbl)
-
Given an array of only numeric values, returns the minimum or nil if no element exists.
Parameters:
- tbl {number,...} the array with only numeric values
Returns:
-
nil or number
the minimum value
- max (tbl)
-
Given an array of only numeric values, returns the maximum or nil if no element exists.
Parameters:
- tbl {number,...} the array with only numeric values
Returns:
-
nil or number
the maximum value
- sum (tbl)
-
Given an array of only numeric values, return the sum of all values, or 0 for empty arrays.
Parameters:
- tbl {number,...} the array with only numeric values
Returns:
-
number
the sum of the numbers or zero if the given array was empty
- avg (tbl)
-
Given an array of only numeric values, returns the average or nil if no element exists.
Parameters:
- tbl {number,...} the array with only numeric values
Returns:
-
nil or number
the average value
- merge (tblA, tblB[, array_merge=false])
-
Merges two tables — values from first get overwritten by the second.
Parameters:
- tblA table first table
- tblB table second table
- array_merge boolean set to true to merge the tables as an array or false for an associative array (default false)
Returns:
-
array or table
an array or an associated array where tblA and tblB have been merged
Usage:
function some_func(x, y, args) args = table.merge({option1=false}, args) if opts.option1 == true then return x else return y end end some_func(1,2) -- returns 2 some_func(1,2,{option1=true}) -- returns 1
- deepcopy (object)
-
Creates a deep copy of table without copying Factorio objects.
Parameters:
- object table the table to copy
Returns:
-
table
a copy of the table
Usage:
local copy = table.deepcopy[data.raw.["stone-furnace"]["stone-furnace"]] -- returns a copy of the stone furnace entity
- values (tbl[, sorted[, as_string]])
-
Returns a copy of all of the values in the table.
Parameters:
- tbl table the table to copy the keys from, or an empty table if tbl is nil
- sorted boolean whether to sort the keys (slower) or keep the random order from pairs() (optional)
- as_string boolean whether to try and parse the values as strings, or leave them as their existing type (optional)
Returns:
-
array
an array with a copy of all the values in the table
- keys (tbl[, sorted[, as_string]])
-
Returns a copy of all of the keys in the table.
Parameters:
- tbl table the table to copy the keys from, or an empty table if tbl is nil
- sorted boolean whether to sort the keys (slower) or keep the random order from pairs() (optional)
- as_string boolean whether to try and parse the keys as strings, or leave them as their existing type (optional)
Returns:
-
array
an array with a copy of all the keys in the table
- remove_keys (tbl, keys)
-
Removes keys from a table by setting the values associated with the keys to nil.
Parameters:
- tbl table the table to remove the keys from
- keys {Mixed,...} an array of keys that exist in the given table
Returns:
-
table
tbl without the specified keys
Usage:
local a = {1, 2, 3, 4} table.remove_keys(a, {1,3}) --returns {nil, 2, nil, 4}
local b = {k1 = 1, k2 = 'foo', old_key = 'bar'} table.remove_keys(b, {'old_key'}) --returns {k1 = 1, k2 = 'foo'}
- count_keys (tbl[, func[, ...]])
-
Returns the number of keys in a table, if func is passed only count keys when the function is true.
Parameters:
- tbl table to count keys
- func function to incremement counter (optional)
- ... additional arguments passed to the function (optional)
Returns:
- number The number of keys matching the function or the number of all keys if func isn't passed
- number The total number of keys
Usage:
local a = { 1, 2, 3, 4, 5} table.count_keys(a) -- produces: 5, 5
local a = {1, 2, 3, 4, 5} table.count_keys(a, function(v, k) return k % 2 == 1 end) -- produces: 3, 5
- invert (tbl)
-
Returns an inverted (***{[value] = key,...}***) copy of the given table. If the values are not unique, the assigned key depends on the order of pairs().
Parameters:
- tbl table the table to invert
Returns:
-
table
a new table with inverted mapping
Usage:
local a = {k1 = 'foo', k2 = 'bar'} table.invert(a) --returns {'foo' = k1, 'bar' = k2}
local b = {k1 = 'foo', k2 = 'bar', k3 = 'bar'} table.invert(b) --returns {'foo' = k1, 'bar' = ?}
- size (table)
-
Return the size of a table using built in table_size function
Parameters:
- table table to use
Returns:
-
int
size of the table
- arr_to_bool (tbl)
-
For all string or number values in an array map them to a key = true table
Parameters:
- tbl table the table to convert
Returns:
-
table
the converted table
Usage:
local a = {"v1", "v2"} table.array_to_dict_bool(a) -- return {["v1"] = true, ["v2"]= true}