Class Array

Array metatype, wrapper for godot_array.

Construct using the idiom Array(...), which calls __new.

Methods

Array:append (...) Alias of push_back.
Array:back () Returns the last element of the Array.
Array:bsearch (value[, before=true]) Finds the index of an existing value (or the insertion index that maintains sorting order, if the value is not yet present in the Array) using binary search.
Array:bsearch_custom (value, object, func[, before=true]) Finds the index of an existing value (or the insertion index that maintains sorting order, if the value is not yet present in the Array) using binary search and a custom comparison method declared in the object.
Array:clear () Clears the Array.
Array:count (value) Returns the number of times an element is in the Array.
Array:duplicate ([deep=false]) Returns a copy of the Array.
Array:empty () Returns true if the Array is empty.
Array:erase (value) Removes the first occurrence of a value from the array.
Array:extend (iterable) Append all values of iterable at the end of Array.
Array:find (value[, from=0]) Searches the Array for a value and returns its index or -1 if not found.
Array:find_last (value) Searches the Array in reverse order for a value and returns its index or -1 if not found.
Array:front () Returns the first element of the Array.
Array:get (index) Returns the value at index.
Array:has (value) Returns true if the Array contains the given value.
Array:hash () Returns a hashed integer value representing the Array and its contents.
Array:insert (self, pos, value) Inserts a new element at a given position in the Array.
Array:invert () Reverses the order of the elements in the Array.
Array:join ([delimiter=""]) Returns a String with each element of the array joined with the given delimiter.
Array:max () Returns the maximum value contained in the Array if all elements are of comparable types.
Array:min () Returns the minimum value contained in the Array if all elements are of comparable types.
Array:pop_back () Removes and returns the last element of the Array, if there is any.
Array:pop_front () Removes and returns the first element of the Array, if there is any.
Array:push_back (...) Append elements at the end of the Array.
Array:push_front (...) Add elements at the beginning of the Array.
Array:remove (index) Removes an element from the Array by index.
Array:resize (size) Resizes the Array to contain a different number of elements.
Array:rfind (value[, from=-1]) Searches the Array in reverse order.
Array:safe_get (index) Returns the value at index.
Array:safe_set (index, value) Set a new value for index.
Array:set (index, value) Set a new value for index.
Array:shuffle () Shuffles the array such that the items will have a random order.
Array:size () Returns the number of elements in the Array.
Array:slice (begin, end[, step=1[, deep=false]]) Duplicates the subset described in the function and returns it in an Array, deeply copying the values if deep is true.
Array:sort () Sorts the Array.
Array:sort_custom (object, func) Sorts the Array using a custom method.

Static Functions

Array:from (iterable) Create a new Array with the elements from iterable by calling extend.

Metamethods

Array:__concat (a, b) Concatenates values.
Array:__eq (a, b) Equality operation
Array:__index (index) Returns method named index or the result of safe_get(index - 1).
Array:__ipairs () Returns an iterator for Array's elements, called by the idiom ipairs(array).
Array:__len () Alias for size.
Array:__new (...) Array constructor, called by the idiom Array(...).
Array:__newindex (index, value) Alias for safe_set(index - 1, value).
Array:__pairs () Alias for __ipairs, called by the idiom pairs(array).
Array:__tostring () Returns a Lua string representation of this Array.


Methods

Array:append (...)
Alias of push_back.

Parameters:

  • ...

See also:

Array:back ()
Returns the last element of the Array. Prints an error and returns nil if the Array is empty.

Returns:

    Last element
Array:bsearch (value[, before=true])
Finds the index of an existing value (or the insertion index that maintains sorting order, if the value is not yet present in the Array) using binary search.

Parameters:

  • value
  • before If false, the returned index comes after all existing entries of the value in the Array. (default true)

Returns:

    int
Array:bsearch_custom (value, object, func[, before=true])
Finds the index of an existing value (or the insertion index that maintains sorting order, if the value is not yet present in the Array) using binary search and a custom comparison method declared in the object. The custom method receives two arguments (an element from the array and the value searched for) and must return true if the first argument is less than the second, and return false otherwise.

Parameters:

  • value
  • object Object
  • func Method name
  • before If false, the returned index comes after all existing entries of the value in the Array. (default true)

Returns:

    int
Array:clear ()
Clears the Array. This is equivalent to using resize with a size of 0.

See also:

Array:count (value)
Returns the number of times an element is in the Array.

Parameters:

  • value

Returns:

    int
Array:duplicate ([deep=false])
Returns a copy of the Array.

Parameters:

  • deep If true, a deep copy is performed: all nested arrays and dictionaries are duplicated and will not be shared with the original Array. If false, a shallow copy is made and references to the original nested arrays and dictionaries are kept, so that modifying a sub-array or dictionary in the copy will also impact those referenced in the source array. (default false)

Returns:

    Array
Array:empty ()
Returns true if the Array is empty.
Array:erase (value)
Removes the first occurrence of a value from the array. To remove an element by index, use remove instead.

Parameters:

  • value

See also:

Array:extend (iterable)
Append all values of iterable at the end of Array.

Parameters:

  • iterable Any object iterable by ipairs, including Lua tables, Arrays and Pool*Arrays.
Array:find (value[, from=0])
Searches the Array for a value and returns its index or -1 if not found.

Parameters:

  • value
  • from int Index to start the search from (default 0)

Returns:

    int Index where value was found

Or

    int -1 if value was not found
Array:find_last (value)
Searches the Array in reverse order for a value and returns its index or -1 if not found.

Parameters:

  • value

Returns:

    int Index where value was found

Or

    int -1 if value was not found
Array:front ()
Returns the first element of the Array. Prints an error and returns nil if the Array is empty.

Returns:

    First element
Array:get (index)
Returns the value at index. Unlike Lua tables, indices start at 0 instead of 1. For 1-based indexing, use the idiom array[index] instead.

If index is invalid (index < 0 or index >= size()), the application will crash. For a safe version that returns nil if index is invalid, use safe_get or the idiom array[index] instead.

Parameters:

  • index int

Returns:

    Value

See also:

Array:has (value)
Returns true if the Array contains the given value.

Parameters:

  • value

Returns:

    bool
Array:hash ()
Returns a hashed integer value representing the Array and its contents.
Array:insert (self, pos, value)
Inserts a new element at a given position in the Array. The position must be valid, or at the end of the Array (pos == size()).

Parameters:

  • self
  • pos
  • value
Array:invert ()
Reverses the order of the elements in the Array.
Array:join ([delimiter=""])
Returns a String with each element of the array joined with the given delimiter.

Parameters:

  • delimiter (default "")

Returns:

    String
Array:max ()
Returns the maximum value contained in the Array if all elements are of comparable types.

Returns:

    Maximum value

Or

    nil If the elements can't be compared
Array:min ()
Returns the minimum value contained in the Array if all elements are of comparable types.

Returns:

    Minimum value

Or

    nil If the elements can't be compared
Array:pop_back ()
Removes and returns the last element of the Array, if there is any.

Returns:

    Last element

Or

    nil If array is empty.
Array:pop_front ()
Removes and returns the first element of the Array, if there is any.

Returns:

    First element

Or

    nil If array is empty.
Array:push_back (...)
Append elements at the end of the Array.

Parameters:

  • ...

See also:

Array:push_front (...)
Add elements at the beginning of the Array.

Parameters:

  • ...

See also:

Array:remove (index)
Removes an element from the Array by index. If the index does not exist in the Array, nothing happens. To remove an element by searching for its value, use erase instead.

Parameters:

  • index int

See also:

Array:resize (size)
Resizes the Array to contain a different number of elements. If the Array size is smaller, elements are cleared, if bigger, new elements are null.

Parameters:

  • size int
Array:rfind (value[, from=-1])
Searches the Array in reverse order.

Parameters:

  • value
  • from int Starting search index. If negative, the start index is considered relative to the end of the Array. (default -1)

Returns:

    int Index where value was found

Or

    int -1 if value was not found
Array:safe_get (index)
Returns the value at index. Unlike Lua tables, indices start at 0 instead of 1. For 1-based indexing, use the idiom array[index] instead.

The idiom array[index] also calls this method.

Parameters:

  • index int

Returns:

    Value

Or

    nil If index is invalid (index < 0 or index >= size())

See also:

Array:safe_set (index, value)
Set a new value for index. Unlike Lua tables, indices start at 0 instead of 1. For 1-based indexing, use the idiom array[index] instead.

If index >= size(), the Array is resized first. The idiom array[index] = value also calls this method.

Parameters:

  • index int
  • value

Raises:

If index < 0

See also:

Array:set (index, value)
Set a new value for index. Unlike Lua tables, indices start at 0 instead of 1. For 1-based indexing, use the idiom array[index] = value instead.

If index is invalid (index < 0 or index >= size()), the application will crash. For a safe approach that resizes if index >= size(), use safe_set or the idiom array[index] = value instead.

Parameters:

  • index int
  • value

See also:

Array:shuffle ()
Shuffles the array such that the items will have a random order.
Array:size ()
Returns the number of elements in the Array.

Returns:

    int
Array:slice (begin, end[, step=1[, deep=false]])
Duplicates the subset described in the function and returns it in an Array, deeply copying the values if deep is true. Lower and upper index are inclusive, with the step describing the change between indices while slicing.

Parameters:

  • begin int Lower index
  • end int Upper index
  • step int (default 1)
  • deep (default false)

Returns:

    Array
Array:sort ()
Sorts the Array. Note: Strings are sorted in alphabetical order (as opposed to natural order).
Array:sort_custom (object, func)
Sorts the Array using a custom method. The arguments are an object that holds the method and the name of such method. The custom method receives two arguments (a pair of elements from the Array) and must return either true or false.

Parameters:

  • object Object
  • func Method name

Static Functions

These don't receive self and should be called directly as Array.static_function(...)
Array:from (iterable)
Create a new Array with the elements from iterable by calling extend.

Parameters:

  • iterable Any object iterable by ipairs, including Lua tables, Arrays and Pool*Arrays.

Returns:

    Array

See also:

Usage:

    local array = Array.from(some_table_or_other_iterable)

Metamethods

Array:__concat (a, b)
Concatenates values.

Parameters:

  • a First value, stringified with GD.str
  • b First value, stringified with GD.str

Returns:

    String
Array:__eq (a, b)
Equality operation

Parameters:

Returns:

    bool
Array:__index (index)
Returns method named index or the result of safe_get(index - 1).

Like Lua tables, indices start at 1. For 0-based indexing, call get or safe_get directly.

Parameters:

  • index

Returns:

    Method or element or nil

See also:

Array:__ipairs ()
Returns an iterator for Array's elements, called by the idiom ipairs(array).

Returns:

  1. function
  2. Array self
  3. int 0

Usage:

    for i, v in ipairs(array) do
    -- do something
end
Array:__len ()
Alias for size.

Returns:

    int

See also:

Array:__new (...)
Array constructor, called by the idiom Array(...).

Parameters:

Array:__newindex (index, value)
Alias for safe_set(index - 1, value).

Like Lua tables, indices start at 1. For 0-based indexing, call set or safe_set directly.

Parameters:

  • index int
  • value

See also:

Array:__pairs ()
Alias for __ipairs, called by the idiom pairs(array).

Returns:

  1. function
  2. Array self
  3. int 0

See also:

Array:__tostring ()
Returns a Lua string representation of this Array.

Returns:

    string
generated by LDoc 1.4.6 Last updated 2023-01-04 08:52:34