An array data structure that can contain a sequence of elements of any type. Elements are accessed by a numerical index starting at 0. Negative indices are used to count from the back (-1 is the last element, -2 is the second to last, etc.).
Example:
Arrays can be concatenated using the +
operator:
Constructs an empty Array.
Creates a typed array from the base
array.
Returns the same array as from
. If you need a copy of the array, use duplicate.
Constructs an array from a PackedByteArray.
Constructs an array from a PackedColorArray.
Constructs an array from a PackedFloat32Array.
Constructs an array from a PackedFloat64Array.
Constructs an array from a PackedInt32Array.
Constructs an array from a PackedInt64Array.
Constructs an array from a PackedStringArray.
Constructs an array from a PackedVector2Array.
Constructs an array from a PackedVector3Array.
Compares the left operand Array against the right
Array. Returns true
if the sizes or contents of the arrays are not equal, false
otherwise.
Concatenates two Arrays together, with the right
Array being added to the end of the Array specified in the left operand. For example, [1, 2] + [3, 4]
results in [1, 2, 3, 4]
.
Performs a comparison for each index between the left operand Array and the right
Array, considering the highest common index of both arrays for this comparison: Returns true
on the first occurrence of an element that is less, or false
if the element is greater. Note that depending on the type of data stored, this function may be recursive. If all elements are equal, it compares the length of both arrays and returns false
if the left operand Array has fewer elements, otherwise it returns true
.
Performs a comparison for each index between the left operand Array and the right
Array, considering the highest common index of both arrays for this comparison: Returns true
on the first occurrence of an element that is less, or false
if the element is greater. Note that depending on the type of data stored, this function may be recursive. If all elements are equal, it compares the length of both arrays and returns true
if the left operand Array has the same number of elements or fewer, otherwise it returns false
.
Compares the left operand Array against the right
Array. Returns true
if the sizes and contents of the arrays are equal, false
otherwise.
Performs a comparison for each index between the left operand Array and the right
Array, considering the highest common index of both arrays for this comparison: Returns true
on the first occurrence of an element that is greater, or false
if the element is less. Note that depending on the type of data stored, this function may be recursive. If all elements are equal, it compares the length of both arrays and returns true
if the right
Array has more elements, otherwise it returns false
.
Performs a comparison for each index between the left operand Array and the right
Array, considering the highest common index of both arrays for this comparison: Returns true
on the first occurrence of an element that is greater, or false
if the element is less. Note that depending on the type of data stored, this function may be recursive. If all elements are equal, it compares the length of both arrays and returns true
if the right
Array has more or the same number of elements, otherwise it returns false
.
Returns a reference to the element of type Variant at the specified location. Arrays start at index 0. index
can be a zero or positive value to start from the beginning, or a negative value to start from the end. Out-of-bounds array access causes a run-time error, which will result in an error being printed and the project execution pausing if run from the editor.
Calls the provided Callable on each element in the array and returns true
if the Callable returns true
for all elements in the array. If the Callable returns false
for one array element or more, this method returns false
.
The callable's method should take one Variant parameter (the current array element) and return a boolean value.
See also any, filter, map and reduce.
Note: Unlike relying on the size of an array returned by filter, this method will return as early as possible to improve performance (especially with large arrays).
Note: For an empty array, this method always returns true
.
Calls the provided Callable on each element in the array and returns true
if the Callable returns true
for one or more elements in the array. If the Callable returns false
for all elements in the array, this method returns false
.
The callable's method should take one Variant parameter (the current array element) and return a boolean value.
See also all, filter, map and reduce.
Note: Unlike relying on the size of an array returned by filter, this method will return as early as possible to improve performance (especially with large arrays).
Note: For an empty array, this method always returns false
.
Appends an element at the end of the array (alias of push_back).
Appends another array at the end of this array.
Assigns elements of another array
into the array. Resizes the array to match array
. Performs type conversions if the array is typed.
Returns the last element of the array. Prints an error and returns null
if the array is empty.
Note: Calling this function is not the same as writing array[-1]
. If the array is empty, accessing by index will pause project execution when running from the editor.
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. Optionally, a before
specifier can be passed. If false
, the returned index comes after all existing entries of the value in the array.
Note: Calling bsearch on an unsorted array results in unexpected behavior.
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. Optionally, a before
specifier can be passed. If false
, the returned index comes after all existing entries of the value in the array. 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.
Note: Calling bsearch_custom on an unsorted array results in unexpected behavior.
Clears the array. This is equivalent to using resize with a size of 0
.
Returns the number of times an element is in the array.
Returns a copy of the array.
If deep
is 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. Note that any Object-derived elements will be shallow copied regardless of the deep
setting.
Removes the first occurrence of a value from the array. If the value does not exist in the array, nothing happens. To remove an element by index, use remove_at instead.
Note: This method acts in-place and doesn't return a modified array.
Note: On large arrays, this method will be slower if the removed element is close to the beginning of the array (index 0). This is because all elements placed after the removed element have to be reindexed.
Note: Do not erase entries while iterating over the array.
Assigns the given value to all elements in the array. This can typically be used together with resize to create an array with a given size and initialized elements:
Note: If value
is of a reference type (Object-derived, Array, Dictionary, etc.) then the array is filled with the references to the same object, i.e. no duplicates are created.
Calls the provided Callable on each element in the array and returns a new array with the elements for which the method returned true
.
The callable's method should take one Variant parameter (the current array element) and return a boolean value.
Searches the array for a value and returns its index or -1
if not found. Optionally, the initial search index can be passed.
Returns the first element of the array. Prints an error and returns null
if the array is empty.
Note: Calling this function is not the same as writing array[0]
. If the array is empty, accessing by index will pause project execution when running from the editor.
Returns the Variant.Type constant for a typed array. If the Array is not typed, returns @GlobalScope.TYPE_NIL.
Returns a class name of a typed Array of type @GlobalScope.TYPE_OBJECT.
Returns the script associated with a typed array tied to a class name.
Returns true
if the array contains the given value.
Note: This is equivalent to using the in
operator as follows:
Returns a hashed 32-bit integer value representing the array and its contents.
Note: Arrays with equal content will always produce identical hash values. However, the reverse is not true. Returning identical hash values does not imply the arrays are equal, because different arrays can have identical hash values due to hash collisions.
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()
). Returns @GlobalScope.OK on success, or one of the other Error values if the operation failed.
Note: This method acts in-place and doesn't return a modified array.
Note: On large arrays, this method will be slower if the inserted element is close to the beginning of the array (index 0). This is because all elements placed after the newly inserted element have to be reindexed.
Returns true
if the array is empty.
Returns true
if the array is read-only. See make_read_only. Arrays are automatically read-only if declared with const
keyword.
Returns true
if the array is typed the same as array
.
Returns true
if the array is typed. Typed arrays can only store elements of their associated type and provide type safety for the []
operator. Methods of typed array still return Variant.
Makes the array read-only, i.e. disabled modifying of the array's elements. Does not apply to nested content, e.g. content of nested arrays.
Calls the provided Callable for each element in the array and returns a new array filled with values returned by the method.
The callable's method should take one Variant parameter (the current array element) and can return any Variant.
Returns the maximum value contained in the array if all elements are of comparable types. If the elements can't be compared, null
is returned.
To find the maximum value using a custom comparator, you can use reduce. In this example every array element is checked and the first maximum value is returned:
Returns the minimum value contained in the array if all elements are of comparable types. If the elements can't be compared, null
is returned.
See also max for an example of using a custom comparator.
Returns a random value from the target array. Prints an error and returns null
if the array is empty.
Removes and returns the element of the array at index position
. If negative, position
is considered relative to the end of the array. Leaves the array unchanged and returns null
if the array is empty or if it's accessed out of bounds. An error message is printed when the array is accessed out of bounds, but not when the array is empty.
Note: On large arrays, this method can be slower than pop_back as it will reindex the array's elements that are located after the removed element. The larger the array and the lower the index of the removed element, the slower pop_at will be.
Removes and returns the last element of the array. Returns null
if the array is empty, without printing an error message. See also pop_front.
Removes and returns the first element of the array. Returns null
if the array is empty, without printing an error message. See also pop_back.
Note: On large arrays, this method is much slower than pop_back as it will reindex all the array's elements every time it's called. The larger the array, the slower pop_front will be.
Appends an element at the end of the array. See also push_front.
Adds an element at the beginning of the array. See also push_back.
Note: On large arrays, this method is much slower than push_back as it will reindex all the array's elements every time it's called. The larger the array, the slower push_front will be.
Calls the provided Callable for each element in array and accumulates the result in accum
.
The callable's method takes two arguments: the current value of accum
and the current array element. If accum
is null
(default value), the iteration will start from the second element, with the first one used as initial value of accum
.
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.
Note: This method acts in-place and doesn't return a modified array.
Note: On large arrays, this method will be slower if the removed element is close to the beginning of the array (index 0). This is because all elements placed after the removed element have to be reindexed.
Note: position
cannot be negative. To remove an element relative to the end of the array, use arr.remove_at(arr.size() - (i + 1))
. To remove the last element from the array without returning the value, use arr.resize(arr.size() - 1)
.
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
. Returns @GlobalScope.OK on success, or one of the other Error values if the operation failed.
Calling resize once and assigning the new values is faster than adding new elements one by one.
Note: This method acts in-place and doesn't return a modified array.
Reverses the order of the elements in the array.
Searches the array in reverse order. Optionally, a start search index can be passed. If negative, the start index is considered relative to the end of the array.
Shuffles the array such that the items will have a random order. This method uses the global random number generator common to methods such as @GlobalScope.randi. Call @GlobalScope.randomize to ensure that a new seed will be used each time if you want non-reproducible shuffling.
Returns the number of elements in the array.
Returns the slice of the Array, from begin
(inclusive) to end
(exclusive), as a new Array.
The absolute value of begin
and end
will be clamped to the array size, so the default value for end
makes it slice to the size of the array by default (i.e. arr.slice(1)
is a shorthand for arr.slice(1, arr.size())
).
If either begin
or end
are negative, they will be relative to the end of the array (i.e. arr.slice(0, -2)
is a shorthand for arr.slice(0, arr.size() - 2)
).
If specified, step
is the relative index between source elements. It can be negative, then begin
must be higher than end
. For example, [0, 1, 2, 3, 4, 5].slice(5, 1, -2)
returns [5, 3]
.
If deep
is true, each element will be copied by value rather than by reference.
Note: To include the first element when step
is negative, use arr.slice(begin, -arr.size() - 1, step)
(i.e. [0, 1, 2].slice(1, -4, -1)
returns [1, 0]
).
Sorts the array.
Note: The sorting algorithm used is not stable. This means that values considered equal may have their order changed when using sort.
Note: Strings are sorted in alphabetical order (as opposed to natural order). This may lead to unexpected behavior when sorting an array of strings ending with a sequence of numbers. Consider the following example:
To perform natural order sorting, you can use sort_custom with String.naturalnocasecmp_to as follows:
Sorts the array using a custom method. The custom method receives two arguments (a pair of elements from the array) and must return either true
or false
. For two elements a
and b
, if the given method returns true
, element b
will be after element a
in the array.
Note: The sorting algorithm used is not stable. This means that values considered equal may have their order changed when using sort_custom.
Note: You cannot randomize the return value as the heapsort algorithm expects a deterministic result. Randomizing the return value will result in unexpected behavior.