table module

Extends Lua 5.2 table.

See also

Functions

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.
arr_to_bool (tbl) For all string or number values in an array map them to a key = true table
avg (tbl) Given an array of only numeric values, returns the average or nil if no element exists.
count_keys (tbl[, func[, ...]]) Returns the number of keys in a table, if func is passed only count keys when the function is true.
deepcopy (object) Creates a deep copy of table without copying Factorio objects.
each (tbl, func[, ...]) Given a function, apply it to each element in the table.
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.
first (tbl) Given an array, returns the first element or nil if no element exists.
flatten (tbl[, level]) Returns a new array that is a one-dimensional recursive flattening of the given array.
invert (tbl) Returns an inverted ({[value] = key,...}) copy of the given table.
keys (tbl[, sorted][, as_string]) Returns a copy of all of the keys in the table.
last (tbl) Given an array, returns the last element or nil if no elements exist.
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.
max (tbl) Given an array of only numeric values, returns the maximum or nil if no element exists.
merge (tblA, tblB[, array_merge=false]) Merges two tables — values from first get overwritten by the second.
min (tbl) Given an array of only numeric values, returns the minimum or nil if no element exists.
remove_keys (tbl, keys) Removes keys from a table by setting the values associated with the keys to nil.
size (table) Return the size of a table using built in table_size function
sum (tbl) Given an array of only numeric values, return the sum of all values, or 0 for empty arrays.
values (tbl[, sorted][, as_string]) Returns a copy of all of the values in the table.

Functions

# 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
See also: 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
# 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}
# avg (tbl)

Given an array of only numeric values, returns the average or nil if no element exists.

Parameters: Returns:
# 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
# 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
# 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
# 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
# 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
# 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
# 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' = ?}
# 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
# 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
# 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}
# max (tbl)

Given an array of only numeric values, returns the maximum or nil if no element exists.

Parameters: Returns:
# 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
# min (tbl)

Given an array of only numeric values, returns the minimum or nil if no element exists.

Parameters: Returns:
# 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'}
# size (table)

Return the size of a table using built in table_size function

Parameters: Returns:
  • (int) size of the table
# sum (tbl)

Given an array of only numeric values, return the sum of all values, or 0 for empty arrays.

Parameters: Returns:
  • (number) the sum of the numbers or zero if the given array was empty
# 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
generated by LDoc 1.4.6
Last updated 2017-08-19 05:47:06 UTC