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:forEach (callbackFunction) Iterates over all elements of the array and applieds a function on them.
Array:map (mapFunction) Maps all elements to a new array using a given function.
Array:filter (filterFunction) Creates a copy that only contains filtered elements.
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:add (element[, index]) Adds an object to the array.
Array:addAll (arr[, index]) Adds an object to the array.
Array:find (element) Returns the index of an object in the array.
Array:contains (element) Returns true iff the given object is part of the array.
Array:isEmpty () Returns true iff the array is empty.
Array:removeAt (i) Removes the object at a specific index.
Array:remove (element) Removes the first appearance of an object from the array.
Array:clear () Clears the array by removing all elements.
Array:sort ([compFunc]) Uses natural order of the elements in the array to sort them.
Array:shuffle () Shuffles the elements of the array into a random order.
Array:pick () Returns a random element of the array.
Array:sub (startIndex[, length]) Creates a sub-array for the specified range.
Array:copy () Returns a copy of the array.
Array:join ([separator]) Joins the contents of the array into a string using the specified separator.


Class Array

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

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

    numbers 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 number Index of where the elements should be inserted. If no index was provided the elements will be appended to the array. (optional)

Returns:

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

    number 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: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: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: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: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:clear ()
Clears the array by removing all elements. The resulting size of the array will be 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: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: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:sub (startIndex[, length])
Creates a sub-array for the specified range.

Parameters:

  • startIndex number The index from where to copy.
  • length number 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: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:join ([separator])
Joins the contents of the array into a string using the specified separator.

Parameters:

Returns:

    string
generated by LDoc 1.4.3 Last updated 2019-07-03 15:00:59