Utils.table module

Extends Lua 5.2 table.

See also

• table

Usage

local table = require('__stdlib__/stdlib/utils/table')

Functions

Table.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.
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.
Table.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.
Table.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.
Table.all(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 for all items in the table.
Table.each(tbl, func[, ...])	Given a function, apply it to each element in the table.
Table.flatten(tbl[, level])	Returns a new array that is a one-dimensional recursive flattening of the given array.
Table.first(tbl)	Given an array, returns the first element or nil if no element exists.
Table.last(tbl)	Given an array, returns the last element or nil if no elements exist.
Table.min(tbl)	Given an array of only numeric values, returns the minimum or nil if no element exists.
Table.max(tbl)	Given an array of only numeric values, returns the maximum or nil if no element exists.
Table.sum(tbl)	Given an array of only numeric values, return the sum of all values, or 0 for empty arrays.
Table.avg(tbl)	Given an array of only numeric values, returns the average or nil if no element exists.
Table.slice(tbl[, start=1][, stop=#tbl])	Return a new array slice.
Table.merge(tblA, tblB[, array_merge=false][, raw=false])	Merges two tables, values from first get overwritten by the second.
Table.dictionary_merge(tbl_a, tbl_b)	Creates a new merged dictionary, if the values in tbl_b are in tbl_a they are not overwritten.
Table.deep_compare(t1, t2[, ignore_mt=false])	Compares 2 tables for inner equality.
Table.deep_copy(object)	Creates a deep copy of table without copying Factorio objects.
Table.full_copy(object)	Creates a deep copy of a table without copying factorio objects internal table refs are also deepcopy.
Table.flex_copy(object)	Creates a flexible deep copy of an object, recursively copying sub-objects
Table.values(tbl[, sorted][, as_string])	Returns a copy of all of the values in the table.
Table.keys(tbl[, sorted][, as_string])	Returns a copy of all of the keys in the table.
Table.remove_keys(tbl, keys)	Removes keys from a table by setting the values associated with the keys to nil.
Table.count_keys(tbl[, func[, ...]])	Returns the number of keys in a table, if func is passed only count keys when the function is true.
Table.invert(tbl)	Returns an inverted ({[value] = key,…}) copy of the given table.
size(table)	Return the size of a table using the factorio built in table_size function
Table.array_to_dictionary(tbl[, as_bool=false])	For all string or number values in an array map them to a value = value table
Table.is_empty(tbl)	Does the table contain any elements
Table.clear(tbl)	Clear all elements in a table

Functions

# Table.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}

# 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.

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 }

# Table.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

# Table.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:

• table.find

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

# Table.all(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 for all items in the table.

Passes the index as second argument to the function.

Parameters:

• tbl : (table) the table to be searched
• func : (function) the function to used to search
• ... : additional arguments passed to the search function (optional)

Returns:

• (boolean) true if all elements in the table return truthy

# Table.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

# Table.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

# Table.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

# 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

# Table.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

# Table.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

# Table.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

# Table.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

# Table.slice(tbl[, start=1][, stop=#tbl])

Return a new array slice.

Parameters:

• tbl : (array) the table to slice
• start : (number) (default: 1)
• stop : (number) stop at this index, use negative to stop from end. (default: #tbl)

Usage:

local tab = { 10, 20, 30, 40, 50}
 slice(tab, 2, -2) --returns { 20, 30, 40 }

# Table.merge(tblA, tblB[, array_merge=false][, raw=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)
• raw : (boolean) use rawset for associated 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

# Table.dictionary_merge(tbl_a, tbl_b)

Creates a new merged dictionary, if the values in tbl_b are in tbl_a they are not overwritten.

Parameters:

• tbl_a : (table)
• tbl_b : (table)

Returns:

• (table) with a and b merged together

Usage:

local a = {one = A}
local b = {one = Z, two = B}
local merged = table.dictionary_merge(tbl_a, tbl_b)
--merged = {one = A, two = B}

# Table.deep_compare(t1, t2[, ignore_mt=false])

Compares 2 tables for inner equality.

Modified from factorio/data/core/lualib/util.lua

Parameters:

• t1 : (table)
• t2 : (table)
• ignore_mt : (boolean) ignore eq metamethod (default: false)

Returns:

• (boolean) if the tables are the same

# Table.deep_copy(object)

Creates a deep copy of table without copying Factorio objects.

copied from factorio/data/core/lualib/util.lua

Parameters:

• object : (table) the table to copy

Returns:

• (table) a copy of the table

Usage:

local copy = table.deep_copy[data.raw.["stone-furnace"]["stone-furnace"]]
 -- returns a copy of the stone furnace entity

# Table.full_copy(object)

Creates a deep copy of a table without copying factorio objects internal table refs are also deepcopy.

The resulting table should

Parameters:

• object : (table) the table to copy

Returns:

• (table) a copy of the table

Usage:

local copy = table.fullcopy[data.raw.["stone-furnace"]["stone-furnace"]]
 -- returns a deepcopy of the stone furnace entity with no internal table references.

# Table.flex_copy(object)

Creates a flexible deep copy of an object, recursively copying sub-objects

Parameters:

• object : (table) the table to copy

Returns:

• (table) a copy of the table

Usage:

local copy = table.flexcopy(data.raw.["stone-furnace"]["stone-furnace"])
 -- returns a copy of the stone furnace entity

# Table.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

# 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

# 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'}

# Table.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 increment 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

# Table.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 the factorio built in table_size function

Parameters:

• table : (table) to use

Returns:

• (int) size of the table

# Table.array_to_dictionary(tbl[, as_bool=false])

For all string or number values in an array map them to a value = value table

Parameters:

• tbl : (table) the table to convert
• as_bool : (boolean) map to true instead of value (default: false)

Returns:

• (table) the converted table

Usage:

local a = {"v1", "v2"}
 table.array_to_bool(a) -- return {["v1"] = "v1", ["v2"]= "v2"}

# Table.is_empty(tbl)

Does the table contain any elements

Parameters:

• tbl : (table)

Returns:

• (boolean)

# Table.clear(tbl)

Clear all elements in a table

Parameters:

• tbl : (table) the table to clear

Returns:

• (table) the cleared table