Module Array

A set of tools to extend Lua's quite simple arrays with more intuitive, traditional methods.

The library is implemented as a metatable for array objects and can therefore be applied to arrays without a copy operation.

Technically Lua has no arrays but tables only. However, a table whose keys are 1,2,...,n only can be seen as an array. The extended functionality added by this module allows you to change size of the array. You can therefore also use it as a list interface.

Note that nil is not an allowed value in an array since it confuses the # (length-)operator.

Creating a new "array" with extended functionality is quite easy. After the creation you can call the methods mentioned below on it.

Usage:

  • local arr = Array()  --Creates an empty array
  • local arr = Array{1, 2, 3}  --Creates an array with content
  • local arr = {1, 2, 3}
Array(arr)  --Here the functionality of an existing array is extended
print(arr[1])  --Prints 1
print(arr[#arr])  --Prints 3
print(arr[-1])  --Prints 3
print(tostring(arr))  --Prints {1, 2, 3}

Class Array

Array:add (element[, index]) Adds an object to the array.
Array:addAll (arr[, index]) Adds an object to the array.
Array:clear () Clears the array by removing all elements.
Array:contains (element) Returns true iff the given object is part of the array.
Array:copy () Returns a copy of the array.
Array:count (predicate) Counts how many elements fulfill a given predicate.
Array:exists (predicate) Returns true iff at least one element matches the given predicate.
Array:filter (filterFunction) Creates a copy that only contains filtered elements.
Array:find (element) Returns the index of an object in the array.
Array:first ([predicate=nil]) Returns the first object that meets the given condition function or just the first element if no predicate function was given.
Array:forEach (callbackFunction) Iterates over all elements of the array and applieds a function on them.
Array:isEmpty () Returns true iff the array is empty.
Array:join ([separator]) Joins the contents of the array into a string using the specified separator.
Array:last ([predicate=nil]) Returns the last object that meets the given condition function or just the last element if no predicate function was given.
Array:map (mapFunction) Maps all elements to a new array using a given function.
Array:pick () Returns a random element of the array.
Array:remove (element) Removes the first appearance of an object from the array.
Array:removeAt (i) Removes the object at a specific index.
Array:removeIf (predicate) Removes the first object that meets the given condition function.
Array:removeWhere (predicate) Removes all objects that met the given condition function.
Array:shuffle () Shuffles the elements of the array into a random order.
Array:sort ([compFunc]) Uses natural order of the elements in the array to sort them.
Array:sub (startIndex[, length]) Creates a sub-array for the specified range.
Array:sum (eval) Sums up the result of the given function called on all elements.


Class Array

Array:add (element[, index])
Adds an object to the array. An index can be provided to specify a position for insertion.

Parameters:

  • element Object to add. May not be nil.
  • index number Index of where the object should be inserted. If no index was provided the object will be appended to the array. (optional)

Returns:

    int Index of the inserted object.

Usage:

    local a = Array()
a:add(1)
a:add(2)
a:add(3, 1)
print(tostring(a))  --Prints {3, 1, 2}
Array:addAll (arr[, index])
Adds an object to the array. An index can be provided to specify a position for insertion.

Parameters:

  • arr Array whose elements should be added.
  • index int Index of where the elements should be inserted. If no index was provided the elements will be appended to the array. (optional)

Returns:

    int Starting index of the inserted elements.

Usage:

    local a = Array{1, 2, 3}
local b = Array{4, 5, 6}
a:addAll(b, 2)
print(tostring(a))  --Prints {1, 4, 5, 6, 2, 3}
Array:clear ()
Clears the array by removing all elements. The resulting size of the array will be 0.
Array:contains (element)
Returns true iff the given object is part of the array.

Parameters:

  • element The object to search for.

Returns:

    bool True iff the object is in the array.

Usage:

    local a = Array{'a', 'b', 'c'}
print(a:contains('b'))  --Prints true
print(a:contains('d'))  --Prints false
Array:copy ()
Returns a copy of the array.

Returns:

    array The copy of the array.

Usage:

    local a = Array{1, 2, 3}
local b = a:copy()
b[1] = 42
print(tostring(a))  --Prints {1, 2, 3}
print(tostring(b))  --Prints {42, 2, 3}
Array:count (predicate)
Counts how many elements fulfill a given predicate.

Parameters:

  • predicate function A function that returns true or false for an element of the array.

Returns:

    int
Array:exists (predicate)
Returns true iff at least one element matches the given predicate.

Parameters:

  • predicate function A function that returns true or false for an element of the array.

Returns:

    bool
Array:filter (filterFunction)
Creates a copy that only contains filtered elements.

Parameters:

  • filterFunction function

Returns:

    array The filtered array.

Usage:

    local a = Array{1, 2, 3}
local b = a:filter(function(x) return x % 2 == 1 end) --Keep uneven numbers
print(tostring(b))  --Prints {1, 3}
Array:find (element)
Returns the index of an object in the array. If the array doesn't contain it the function returns -1.

Parameters:

  • element The object to search for.

Returns:

    int The index of element or -1 if it's not in the array.

Usage:

    local a = Array{'a', 'b', 'c'}
print(a:find('b'))  --Prints 2
Array:first ([predicate=nil])
Returns the first object that meets the given condition function or just the first element if no predicate function was given.

Parameters:

  • predicate function A predicate function that returns true for the element that should be returned. (default nil)

Returns:

    The first element that met the condition / the first element / nil.
Array:forEach (callbackFunction)
Iterates over all elements of the array and applieds a function on them. This is especially useful to avoid explicit use of a for loop. However, this functional style comes at an allocation and performance cost because of the function. Use it when it suits your needs.

Parameters:

  • callbackFunction function

Usage:

    local a = Array{1, 2, 3}
for i = 1, #a do --Typical approach
  print(a[i])
end
a:forEach(function(x) print(x) end) --Functional style
Array:isEmpty ()
Returns true iff the array is empty. This is equivalent to checking the size size of the array being 0 manually.

Returns:

    bool True iff the array is empty.

Usage:

    local a = Array()
print(a:isEmpty())
a:add(1)
print(a:isEmpty())
Array:join ([separator])
Joins the contents of the array into a string using the specified separator.

Parameters:

Returns:

    string
Array:last ([predicate=nil])
Returns the last object that meets the given condition function or just the last element if no predicate function was given.

Parameters:

  • predicate function A predicate function that returns true for the element that should be returned. (default nil)

Returns:

    The last element that met the condition / the first element / nil.
Array:map (mapFunction)
Maps all elements to a new array using a given function.

Parameters:

  • mapFunction function

Returns:

    array The mapped array.

Usage:

    local a = Array{1, 2, 3}
local b = a:map(function(x) return 2 * x end)
print(tostring(b))  --Prints {2, 4, 6}
Array:pick ()
Returns a random element of the array. Returns nil if the array is empty.

Returns:

    Randomly selected element.

Usage:

    local a = Array{1, 2, 3}
print(a:pick())
Array:remove (element)
Removes the first appearance of an object from the array.

Parameters:

  • element Object that should be found and removed.

Returns:

    bool True iff the object was found and removed.
Array:removeAt (i)
Removes the object at a specific index.

Parameters:

  • i number Index of the object that should be removed.

Returns:

    The removed object, or nil if no object has been removed.
Array:removeIf (predicate)
Removes the first object that meets the given condition function.

Parameters:

  • predicate A predicate function that returns true for the element that should be removed.

Returns:

    bool True iff an element met the condition and was removed.
Array:removeWhere (predicate)
Removes all objects that met the given condition function.

Parameters:

  • predicate A predicate function that returns true for elements that should be removed.

Returns:

    int The number of occurences that were found and removed.
Array:shuffle ()
Shuffles the elements of the array into a random order. The function uses math.random internally so that the result is dependent on the current random seed value. To get different results for different runs you might call

math.randomseed(os.time())

at the start of your program.

Usage:

    local a = Array{0, 1, 2, 3, 4, 5, 6}
a:shuffle()
print(tostring(a))  --Prints {5, 3, 4, 1, 6, 2, 0}
Array:sort ([compFunc])
Uses natural order of the elements in the array to sort them. You can optionally provide your own function for comparing two elements.

Parameters:

  • compFunc function The comparison function must return a boolean value specifying whether the first argument should be before the second argument in the array. The default behaviour is ascending order. (optional)

Usage:

    local arr = Array{1, 5, 0, 6, 1, 3, 2, 4}
arr:sort()
print(tostring(arr))  --Prints {0, 1, 1, 2, 3, 4, 5, 6}
arr:sort(function(a,b) return a > b end)
print(tostring(arr))  --Prints {6, 5, 4, 3, 2, 1, 1, 0}
Array:sub (startIndex[, length])
Creates a sub-array for the specified range.

Parameters:

  • startIndex number The index from where to copy.
  • length int The length of the new array. By default the array will be copied to the end. (optional)

Returns:

    array The created sub-array.

Usage:

    local a = Array{1, 2, 3, 4, 5, 6}
print(tostring(a))  --Prints {1, 2, 3, 4, 5, 6}
local b = a:sub(2, 4)
print(tostring(b))  --Prints {2, 3, 4, 5}
Array:sum (eval)
Sums up the result of the given function called on all elements.

New feature:

    This is a new feature that was added in version 1.11.37

Parameters:

  • eval function A function that associates each element with a number.

Returns:

    number
generated by LDoc 1.4.3 Last updated 2024-11-25 14:07:58