Up to date
This page is up to date for Godot 4.1
.
If you still find outdated information, please open an issue.
Array¶
A built-in data structure that holds a sequence of elements.
Description¶
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:
var array = ["One", 2, 3, "Four"]
print(array[0]) # One.
print(array[2]) # 3.
print(array[-1]) # Four.
array[2] = "Three"
print(array[-2]) # Three.
var array = new Godot.Collections.Array{"One", 2, 3, "Four"};
GD.Print(array[0]); // One.
GD.Print(array[2]); // 3.
GD.Print(array[array.Count - 1]); // Four.
array[2] = "Three";
GD.Print(array[array.Count - 2]); // Three.
Arrays can be concatenated using the +
operator:
var array1 = ["One", 2]
var array2 = [3, "Four"]
print(array1 + array2) # ["One", 2, 3, "Four"]
// Array concatenation is not possible with C# arrays, but is with Godot.Collections.Array.
var array1 = new Godot.Collections.Array{"One", 2};
var array2 = new Godot.Collections.Array{3, "Four"};
GD.Print(array1 + array2); // Prints [One, 2, 3, Four]
Note: Arrays are always passed by reference. To get a copy of an array that can be modified independently of the original array, use duplicate.
Note: Erasing elements while iterating over arrays is not supported and will result in unpredictable behavior.
Constructors¶
Array ( ) |
|
Array ( Array base, int type, StringName class_name, Variant script ) |
|
Array ( PackedByteArray from ) |
|
Array ( PackedColorArray from ) |
|
Array ( PackedFloat32Array from ) |
|
Array ( PackedFloat64Array from ) |
|
Array ( PackedInt32Array from ) |
|
Array ( PackedInt64Array from ) |
|
Array ( PackedStringArray from ) |
|
Array ( PackedVector2Array from ) |
|
Array ( PackedVector3Array from ) |
Methods¶
void |
|
void |
append_array ( Array array ) |
void |
|
back ( ) const |
|
bsearch_custom ( Variant value, Callable func, bool before=true ) const |
|
void |
clear ( ) |
void |
|
void |
|
front ( ) const |
|
get_typed_builtin ( ) const |
|
get_typed_class_name ( ) const |
|
get_typed_script ( ) const |
|
hash ( ) const |
|
is_empty ( ) const |
|
is_read_only ( ) const |
|
is_same_typed ( Array array ) const |
|
is_typed ( ) const |
|
void |
make_read_only ( ) |
max ( ) const |
|
min ( ) const |
|
pick_random ( ) const |
|
pop_back ( ) |
|
pop_front ( ) |
|
void |
|
void |
push_front ( Variant value ) |
void |
|
void |
reverse ( ) |
void |
shuffle ( ) |
size ( ) const |
|
slice ( int begin, int end=2147483647, int step=1, bool deep=false ) const |
|
void |
sort ( ) |
void |
sort_custom ( Callable func ) |
Operators¶
operator != ( Array right ) |
|
operator + ( Array right ) |
|
operator < ( Array right ) |
|
operator <= ( Array right ) |
|
operator == ( Array right ) |
|
operator > ( Array right ) |
|
operator >= ( Array right ) |
|
operator [] ( int index ) |
Constructor Descriptions¶
Array Array ( )
Constructs an empty Array.
Array Array ( Array base, int type, StringName class_name, Variant script )
Creates a typed array from the base
array.
Returns the same array as from
. If you need a copy of the array, use duplicate.
Array Array ( PackedByteArray from )
Constructs an array from a PackedByteArray.
Array Array ( PackedColorArray from )
Constructs an array from a PackedColorArray.
Array Array ( PackedFloat32Array from )
Constructs an array from a PackedFloat32Array.
Array Array ( PackedFloat64Array from )
Constructs an array from a PackedFloat64Array.
Array Array ( PackedInt32Array from )
Constructs an array from a PackedInt32Array.
Array Array ( PackedInt64Array from )
Constructs an array from a PackedInt64Array.
Array Array ( PackedStringArray from )
Constructs an array from a PackedStringArray.
Array Array ( PackedVector2Array from )
Constructs an array from a PackedVector2Array.
Array Array ( PackedVector3Array from )
Constructs an array from a PackedVector3Array.
Method Descriptions¶
bool all ( Callable method ) const
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.
func _ready():
print([6, 10, 6].all(greater_than_5)) # Prints True (3/3 elements evaluate to `true`).
print([4, 10, 4].all(greater_than_5)) # Prints False (1/3 elements evaluate to `true`).
print([4, 4, 4].all(greater_than_5)) # Prints False (0/3 elements evaluate to `true`).
print([].all(greater_than_5)) # Prints True (0/0 elements evaluate to `true`).
print([6, 10, 6].all(func(number): return number > 5)) # Prints True. Same as the first line above, but using lambda function.
func greater_than_5(number):
return number > 5
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
.
bool any ( Callable method ) const
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.
func _ready():
print([6, 10, 6].any(greater_than_5)) # Prints True (3 elements evaluate to `true`).
print([4, 10, 4].any(greater_than_5)) # Prints True (1 elements evaluate to `true`).
print([4, 4, 4].any(greater_than_5)) # Prints False (0 elements evaluate to `true`).
print([].any(greater_than_5)) # Prints False (0 elements evaluate to `true`).
print([6, 10, 6].any(func(number): return number > 5)) # Prints True. Same as the first line above, but using lambda function.
func greater_than_5(number):
return number > 5
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
.
void append ( Variant value )
Appends an element at the end of the array (alias of push_back).
void append_array ( Array array )
Appends another array at the end of this array.
var array1 = [1, 2, 3]
var array2 = [4, 5, 6]
array1.append_array(array2)
print(array1) # Prints [1, 2, 3, 4, 5, 6].
void assign ( Array array )
Assigns elements of another array
into the array. Resizes the array to match array
. Performs type conversions if the array is typed.
Variant back ( ) const
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.