Module Array

Numerically indexed table manipulation.

Optimized for speed.

Note: Some methods of this module apply their result directly to the input table to be faster. If you want the input table to be unaffected you can supply an (empty) table as the target to which the result should be written instead. This allows both in-place and copy-on-write operations to be handled by the same method at the same cpu-cost.

Note: This module inherits all Table module methods. Same-named Array methods override inherited Table methods.

Module Status: Stable.

Usage:

    local Array = require('__eradicators-library__/erlib/lua/Array')()

Module

Array(arr) Attaches this Array module as metatable to a table.

Basic Methods

size(arr) The size of this array.
keys(arr[, i=1[, j=#arr]]) Produces an array of only the keys with NotNil values of this array.
values(arr[, i=1[, j=#arr]]) Produces an array of only the NotNil values of this array.

Search Methods

first_gap(arr[, i=1[, j=infinity]]) Finds the first nil value in an array.
find(arr, value[, i=1[, j=#arr]]) Finds the first occurance of a value in an array.
find_all(arr, value[, i=1[, j=#arr]]) Finds all occurances of a value in an array.

In-Place Methods

compress(arr[, target=nil[, i=1[, j=Array.size(arr)]]]) In-place. Compresses a SparseArray into a DenseArray.
map(arr, f[, target=nil[, i=1[, j=#arr]]]) In-place. Applies a function to all elements of an array.
filter(arr, f[, target=nil[, i=1[, j=#arr]]]) In-place. Removes elements from an array based on a filter function.
reverse(arr[, target=nil[, i=1[, j=#arr]]]) In-place. Reverses the order of an array.
deduplicate(arr[, f_ident[, target=nil[, i=1[, j=#arr]]]]) In-place. Removes redundant and nil values.
insert_once(arr, value[, i=1]) In-place. Appends a value at the end of an array only if no other key in the array has an == equal value.
insert_array(arr, arr2, i[, target=nil]) In-place. Puts one array into the middle of another.
unsorted_remove_value(arr, value[, i=1]) In-place. Replaces all instances of value with the then-last value of the array.
unsorted_remove_key() Deprecated.
shuffle_pop(arr, i) In-place. Moves the value at index #arr to index i.
clear(arr[, i=1[, j=#arr]]) In-place. Sets all values to nil.
extend(arr, arr2[, i=1[, j=#arr2]]) In-place. Inserts the content of arr2 at the end of arr.
sort(arr, comparator) In-place. Applies a sorting function to an array.
fisher_yates_shuffle(arr[, seed]) In-place. Randomized the order of the arrays values.

Copy Methods

scopy(arr[, i=1[, j=#arr]]) Shallow Copy. Copies (parts of) an array to a new table.

Other Methods

splice(arr[, ...]) Takes elements from multiple input tables and puts them into a flat array.
fray(arr, count[, i=1[, j=#arr]]) Reverse of Array.splice().
flatten(arr) In-place. Removes subtables, keeps value order.

Conversion

from_iterator(f_iter) Experimental. Collects the output of a parameterless iterator function into an array.

Metamethods

__concat() Concatenation with .. is Array.extend().


Module

Array(arr)
Attaches this Array module as metatable to a table.
Alias for setmetatable(arr, {__index = Array}).

Parameters:

Returns:

    DenseArray, SparseArray or MixedTable The unchanged input table, now with metatable attached.

Basic Methods

size(arr)
The size of this array.
For DenseArrays the length operator # is much faster.
For MixedTables you have to use Table.array_size instead.

Parameters:

Returns:

    NaturalNumber
keys(arr[, i=1[, j=#arr]])
Produces an array of only the keys with NotNil values of this array. Values are not preserved.

Parameters:

Returns:

    DenseArray
values(arr[, i=1[, j=#arr]])
Produces an array of only the NotNil values of this array. Keys are not preserved.

Parameters:

Returns:

    DenseArray

Search Methods

first_gap(arr[, i=1[, j=infinity]])
Finds the first nil value in an array. For DenseArrays this is equivalent to #arr+1.

Parameters:

Returns:

    NaturalNumber or nil The first index >= i, that has the value nil. Or nil if a fixed range i,j was given and there were no nil values in that range. Or nil if array size exeeds IEEE754 double-precision floating-point range (2^53).
find(arr, value[, i=1[, j=#arr]])
Finds the first occurance of a value in an array.

Parameters:

Returns:

    NaturalNumber or nil The index of the first occurance of the value in the range i,j, or nil if value wasn't found.
find_all(arr, value[, i=1[, j=#arr]])
Finds all occurances of a value in an array.

Parameters:

Returns:

    DenseArray A list of keys in arr that have the value. Can be empty.

In-Place Methods

compress(arr[, target=nil[, i=1[, j=Array.size(arr)]]])
In-place. Compresses a SparseArray into a DenseArray. The order of the elements is preserved. Can also compress partial ranges of the input, for example to split the compression into multiple steps.

Note: If you know the size of the array then giving it as j significantly improves performance.

Note: To compress MixedTables you can give Table.array_size(arr) as j.

Parameters:

  • arr SparseArray
  • target table Copy Mode. This table will be changed and arr remains unchanged. (default nil)
  • i NaturalNumber First index to process. Mandatory for sparse input. (default 1)
  • j NaturalNumber Last index to process. Mandatory for sparse input. (default Array.size(arr))

Returns:

    DenseArray
map(arr, f[, target=nil[, i=1[, j=#arr]]])
In-place. Applies a function to all elements of an array. This function does not change the (key → value) relationship. Thus if the input array or partial range includes nil values, or f() returns nil values then the output will be sparse.

Note: Due to the inherit overhead of one extra function call per element performance impact should be carefully considered before using this to replace normal for-ipairs loops.

Experts only: Copy mode supports key reassignment like Table.map.

Parameters:

  • arr DenseArray or SparseArray
  • f function The function f(value,index,arr) that is applied to every key→value mapping in the array.
  • target table Copy Mode. This table will be changed and arr remains unchanged. (default nil)
  • i NaturalNumber First index to process. Mandatory for sparse input. (default 1)
  • j NaturalNumber Last index to process. Mandatory for sparse input. (default #arr)

Returns:

    DenseArray or SparseArray
filter(arr, f[, target=nil[, i=1[, j=#arr]]])
In-place. Removes elements from an array based on a filter function.

Note: Due to the inherit extra overhead of one function call per element this will always be slower than a simple for-pairs loop.

Parameters:

  • arr DenseArray or SparseArray
  • f function Any elements for which the filter function f(value,index,arr) does not return truthy are removed from the array. And any following indexes are shifted down.
  • target table Copy Mode. This table will be changed and arr remains unchanged. (default nil)
  • i NaturalNumber First index to process. Mandatory for sparse input. (default 1)
  • j NaturalNumber Last index to process. Mandatory for sparse input. (default #arr)

Returns:

    DenseArray Indexes will be shifted down if values have been deleted.
reverse(arr[, target=nil[, i=1[, j=#arr]]])
In-place. Reverses the order of an array.

Parameters:

  • arr DenseArray or SparseArray
  • target table Copy Mode. This table will be changed and arr remains unchanged. (default nil)
  • i NaturalNumber First index to process. Mandatory for sparse input. (default 1)
  • j NaturalNumber Last index to process. Mandatory for sparse input. (default #arr)

Returns:

    DenseArray or SparseArray
deduplicate(arr[, f_ident[, target=nil[, i=1[, j=#arr]]]])
In-place. Removes redundant and nil values. Order of elements is unaffected.

Parameters:

  • arr DenseArray or SparseArray
  • f_ident function A function f(v) that must take each value in the array and produce a unique NotNil identifier value for comparision. Defaults to Filter.PASS. (optional)
  • target table Copy Mode. This table will be changed and arr remains unchanged. (default nil)
  • i NaturalNumber First index to process. Mandatory for sparse input. (default 1)
  • j NaturalNumber Last index to process. Mandatory for sparse input. (default #arr)

Returns:

    DenseArray or SparseArray Can only become sparse if j was given and was smaller than the largest array key. In copy mode if i was given all indexes will be shifted down by i-1 so that the array always starts at 1.
insert_once(arr, value[, i=1])
In-place. Appends a value at the end of an array only if no other key in the array has an == equal value.

Parameters:

Returns:

  1. DenseArray The input array.
  2. boolean false: element was already in array, true: element was inserted at the end.
insert_array(arr, arr2, i[, target=nil])
In-place. Puts one array into the middle of another.

Parameters:

  • arr DenseArray The array to insert into.
  • arr2 DenseArray The array to be inserted.
  • i NaturalNumber The index at which to start inserting arr2. All values after i (inclusive) will be shifted backwards by the length of arr2.
  • target table Copy Mode. This table will be changed and arr remains unchanged. (default nil)

Returns:

    DenseArray The array containing the merged result.
unsorted_remove_value(arr, value[, i=1])
In-place. Replaces all instances of value with the then-last value of the array. For large arrays this is much faster than table.remove but does not preserver element order.

Parameters:

Returns:

  1. DenseArray The input array.
  2. NaturalNumber How often the value was removed.
unsorted_remove_key()
Deprecated.
shuffle_pop(arr, i)
In-place. Moves the value at index #arr to index i. For large arrays this is much faster than table.remove but does not preserve value order.

Note: When i is out-of-bounds then the array remains unchanged. Unlike table.remove no error is raised. This is to allow easy key existance checking.

Parameters:

Returns:

    NotNil or nil The value that was at arr[i]
clear(arr[, i=1[, j=#arr]])
In-place. Sets all values to nil. Useful if you need to keep the table reference intact.

Parameters:

Returns:

    EmptyArray, DenseArray or SparseArray The input array.
extend(arr, arr2[, i=1[, j=#arr2]])
In-place. Inserts the content of arr2 at the end of arr.

Parameters:

Returns:

    DenseArray or SparseArray The input array.
sort(arr, comparator)
In-place. Applies a sorting function to an array. See the Compare module for built-in comparing functions.

See also: table.sort

Parameters:

  • arr DenseArray
  • comparator function A function f(a,b)→boolean which determines the final order.

Returns:

    DenseArray
fisher_yates_shuffle(arr[, seed])
In-place. Randomized the order of the arrays values.

Parameters:

Returns:

    DenseArray The now shuffled array.

Copy Methods

scopy(arr[, i=1[, j=#arr]])
Shallow Copy. Copies (parts of) an array to a new table. Sub-tables will reference the original tables.

Note: This is a speed optimized array-only variant of Table.scopy.

Parameters:

Returns:

    DenseArray or SparseArray Indexes will be exactly as in the input. Even for partial copies.

Other Methods

splice(arr[, ...])
Takes elements from multiple input tables and puts them into a flat array.

Parameters:

  • arr DenseArray
  • ... AnyValue Not giving any extra inputs is equivalent to Array.scopy(arr). If a table is given its values will be taken from the same key as the preceeding value of arr. If a non-table is given it will simply be repeated. (optional)

Returns:

    DenseArray or SparseArray

Usage:

    local spliced_array = Array.splice({1,2,3},42,{'a','b','c'},nil,'end')
print(spliced_array:to_string())
> {1, 42, "a", nil, "end", 2, 42, "b", nil, "end", 3, 42, "c", nil, "end"}
fray(arr, count[, i=1[, j=#arr]])
Reverse of Array.splice(). Splits a large array into sub-arrays.

Parameters:

  • arr DenseArray or SparseArray
  • count NaturalNumber How many sub-tables should be constructed from the input array. When giving a i,j range it must be divisable by count without rest.
  • i NaturalNumber First index to process. Mandatory for sparse input. (default 1)
  • j NaturalNumber Last index to process. Mandatory for sparse input. (default #arr)

Returns:

    DenseArray Array of arrays. If the input was made using Array.splice() with non-table inputs then those inputs will not be reconstructed. They will instead return a table with repetitions of the value.

Usage:

    -- Using the same array as above...
local spliced_array = Array.splice({1,2,3},42,{'a','b','c'},nil,'end')
-- Which was made of 5 inputs, but one of them was nil, so the
-- output is a SparseArray and thus range specification is mandatory.
print(spliced_array:fray(5,1,15):to_string())
> {{1,2,3}, {42,42,42}, {"a","b","c"}, {nil,nil,nil}, {"end","end","end"}}
-- partial ranges will return partial results.
print(spliced_array:fray(5,6,10):to_string())
> {{2}, {42}, {"b"}, {nil}, {"end"}}
flatten(arr)
In-place. Removes subtables, keeps value order.

Note: Recursive tables and factorio objects are not supported and will produce garbage results.

Parameters:

Returns:

    DenseArray

Usage:

    -- a chaotically nested array
local arr = {{{{}}},1,2,{3,4,{5,6},{7}},8,{{{{9,{{10}}}}}}}
print(Array.flatten(arr):to_string())
> {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}

Conversion

from_iterator(f_iter)
Experimental. Collects the output of a parameterless iterator function into an array. All return values of each call of f_iter() are packed into a sub-array of the output array.

Parameters:

  • f_iter function The iterator function.

Returns:

  1. DenseArray An array of return value arrays.
  2. NaturalNumber The length of the returned array.

Metamethods

__concat()
Concatenation with .. is Array.extend().
generated by LDoc 1.4.6 Last updated 2021-09-10 19:51:19