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

  1. number The number of keys matching the function or the number of all keys if func isn't passed
  2. 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}

generated by LDoc 1.4.6 Last updated 2018-06-07 12:58:23