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.

Arrays can be concatenated using the + operator:

var array1 = ["One", 2]
var array2 = [3, "Four"]
print(array1 + array2) # ["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

Array ( Array base, int type, StringName class_name, Variant script )

Array

Array ( Array from )

Array

Array ( PackedByteArray from )

Array

Array ( PackedColorArray from )

Array

Array ( PackedFloat32Array from )

Array

Array ( PackedFloat64Array from )

Array

Array ( PackedInt32Array from )

Array

Array ( PackedInt64Array from )

Array

Array ( PackedStringArray from )

Array

Array ( PackedVector2Array from )

Array

Array ( PackedVector3Array from )

Methods

bool

all ( Callable method ) const

bool

any ( Callable method ) const

void

append ( Variant value )

void

append_array ( Array array )

void

assign ( Array array )

Variant

back ( ) const

int

bsearch ( Variant value, bool before=true ) const

int

bsearch_custom ( Variant value, Callable func, bool before=true ) const

void

clear ( )

int

count ( Variant value ) const

Array

duplicate ( bool deep=false ) const

void

erase ( Variant value )

void

fill ( Variant value )

Array

filter ( Callable method ) const

int

find ( Variant what, int from=0 ) const

Variant

front ( ) const

int

get_typed_builtin ( ) const

StringName

get_typed_class_name ( ) const

Variant

get_typed_script ( ) const

bool

has ( Variant value ) const

int

hash ( ) const

int

insert ( int position, Variant value )

bool

is_empty ( ) const

bool

is_read_only ( ) const

bool

is_same_typed ( Array array ) const

bool

is_typed ( ) const

void

make_read_only ( )

Array

map ( Callable method ) const

Variant

max ( ) const

Variant

min ( ) const

Variant

pick_random ( ) const

Variant

pop_at ( int position )

Variant

pop_back ( )

Variant

pop_front ( )

void

push_back ( Variant value )

void

push_front ( Variant value )

Variant

reduce ( Callable method, Variant accum=null ) const

void

remove_at ( int position )

int

resize ( int size )

void

reverse ( )

int

rfind ( Variant what, int from=-1 ) const

void

shuffle ( )

int

size ( ) const

Array

slice ( int begin, int end=2147483647, int step=1, bool deep=false ) const

void

sort ( )

void

sort_custom ( Callable func )

Operators

bool

operator != ( Array right )

Array

operator + ( Array right )

bool

operator < ( Array right )

bool

operator <= ( Array right )

bool

operator == ( Array right )

bool

operator > ( Array right )

bool

operator >= ( Array right )

Variant

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.


Array Array ( Array from )

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.


int bsearch ( Variant value, bool before=true ) const

Finds the index of an e