godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2025-12-31 17:49:03 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
master
godot-docs/classes/class_array.rst
Godot Organization d45f83bf92 classref: Sync with current master branch (4b6c88d)
2025-12-15 22:19:00 +00:00

1572 lines
85 KiB
ReStructuredText
Raw Permalink Blame History

:github_url: hide
.. DO NOT EDIT THIS FILE!!!
.. Generated automatically from Godot engine sources.
.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py.
.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/Array.xml.
.. _class_Array:
Array
=====
A built-in data structure that holds a sequence of elements.
.. rst-class:: classref-introduction-group
Description
-----------
An array data structure that can contain a sequence of elements of any :ref:`Variant<class_Variant>` type by default. Values can optionally be constrained to a specific type by creating a *typed array*. 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.).
.. tabs::
.. code-tab:: gdscript
var array = ["First", 2, 3, "Last"]
print(array[0]) # Prints "First"
print(array[2]) # Prints 3
print(array[-1]) # Prints "Last"
array[1] = "Second"
print(array[1]) # Prints "Second"
print(array[-3]) # Prints "Second"
# This typed array can only contain integers.
# Attempting to add any other type will result in an error.
var typed_array: Array[int] = [1, 2, 3]
.. code-tab:: csharp
Godot.Collections.Array array = ["First", 2, 3, "Last"];
GD.Print(array[0]); // Prints "First"
GD.Print(array[2]); // Prints 3
GD.Print(array[^1]); // Prints "Last"
array[1] = "Second";
GD.Print(array[1]); // Prints "Second"
GD.Print(array[^3]); // Prints "Second"
// This typed array can only contain integers.
// Attempting to add any other type will result in an error.
Godot.Collections.Array<int> typedArray = [1, 2, 3];
\ **Note:** Arrays are always passed by **reference**. To get a copy of an array that can be modified independently of the original array, use :ref:`duplicate()<class_Array_method_duplicate>`.
\ **Note:** Erasing elements while iterating over arrays is **not** supported and will result in unpredictable behavior.
\ **Differences between packed arrays, typed arrays, and untyped arrays:** Packed arrays are generally faster to iterate on and modify compared to a typed array of the same type (e.g. :ref:`PackedInt64Array<class_PackedInt64Array>` versus ``Array[int]``). Also, packed arrays consume less memory. As a downside, packed arrays are less flexible as they don't offer as many convenience methods such as :ref:`map()<class_Array_method_map>`. Typed arrays are in turn faster to iterate on and modify than untyped arrays.
.. note::
There are notable differences when using this API with C#. See :ref:`doc_c_sharp_differences` for more information.
.. rst-class:: classref-reftable-group
Constructors
------------
.. table::
:widths: auto
+---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Array<class_Array>` | :ref:`Array<class_Array_constructor_Array>`\ (\ ) |
+---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Array<class_Array>` | :ref:`Array<class_Array_constructor_Array>`\ (\ base\: :ref:`Array<class_Array>`, type\: :ref:`int<class_int>`, class_name\: :ref:`StringName<class_StringName>`, script\: :ref:`Variant<class_Variant>`\ ) |
+---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Array<class_Array>` | :ref:`Array<class_Array_constructor_Array>`\ (\ from\: :ref:`Array<class_Array>`\ ) |
+---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Array<class_Array>` | :ref:`Array<class_Array_constructor_Array>`\ (\ from\: :ref:`PackedByteArray<class_PackedByteArray>`\ ) |
+---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Array<class_Array>` | :ref:`Array<class_Array_constructor_Array>`\ (\ from\: :ref:`PackedColorArray<class_PackedColorArray>`\ ) |
+---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Array<class_Array>` | :ref:`Array<class_Array_constructor_Array>`\ (\ from\: :ref:`PackedFloat32Array<class_PackedFloat32Array>`\ ) |
+---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Array<class_Array>` | :ref:`Array<class_Array_constructor_Array>`\ (\ from\: :ref:`PackedFloat64Array<class_PackedFloat64Array>`\ ) |
+---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Array<class_Array>` | :ref:`Array<class_Array_constructor_Array>`\ (\ from\: :ref:`PackedInt32Array<class_PackedInt32Array>`\ ) |
+---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Array<class_Array>` | :ref:`Array<class_Array_constructor_Array>`\ (\ from\: :ref:`PackedInt64Array<class_PackedInt64Array>`\ ) |
+---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Array<class_Array>` | :ref:`Array<class_Array_constructor_Array>`\ (\ from\: :ref:`PackedStringArray<class_PackedStringArray>`\ ) |
+---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Array<class_Array>` | :ref:`Array<class_Array_constructor_Array>`\ (\ from\: :ref:`PackedVector2Array<class_PackedVector2Array>`\ ) |
+---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Array<class_Array>` | :ref:`Array<class_Array_constructor_Array>`\ (\ from\: :ref:`PackedVector3Array<class_PackedVector3Array>`\ ) |
+---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Array<class_Array>` | :ref:`Array<class_Array_constructor_Array>`\ (\ from\: :ref:`PackedVector4Array<class_PackedVector4Array>`\ ) |
+---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. rst-class:: classref-reftable-group
Methods
-------
.. table::
:widths: auto
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`all<class_Array_method_all>`\ (\ method\: :ref:`Callable<class_Callable>`\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`any<class_Array_method_any>`\ (\ method\: :ref:`Callable<class_Callable>`\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`append<class_Array_method_append>`\ (\ value\: :ref:`Variant<class_Variant>`\ ) |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`append_array<class_Array_method_append_array>`\ (\ array\: :ref:`Array<class_Array>`\ ) |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`assign<class_Array_method_assign>`\ (\ array\: :ref:`Array<class_Array>`\ ) |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Variant<class_Variant>` | :ref:`back<class_Array_method_back>`\ (\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`bsearch<class_Array_method_bsearch>`\ (\ value\: :ref:`Variant<class_Variant>`, before\: :ref:`bool<class_bool>` = true\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`bsearch_custom<class_Array_method_bsearch_custom>`\ (\ value\: :ref:`Variant<class_Variant>`, func\: :ref:`Callable<class_Callable>`, before\: :ref:`bool<class_bool>` = true\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`clear<class_Array_method_clear>`\ (\ ) |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`count<class_Array_method_count>`\ (\ value\: :ref:`Variant<class_Variant>`\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Array<class_Array>` | :ref:`duplicate<class_Array_method_duplicate>`\ (\ deep\: :ref:`bool<class_bool>` = false\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Array<class_Array>` | :ref:`duplicate_deep<class_Array_method_duplicate_deep>`\ (\ deep_subresources_mode\: :ref:`int<class_int>` = 1\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`erase<class_Array_method_erase>`\ (\ value\: :ref:`Variant<class_Variant>`\ ) |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`fill<class_Array_method_fill>`\ (\ value\: :ref:`Variant<class_Variant>`\ ) |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Array<class_Array>` | :ref:`filter<class_Array_method_filter>`\ (\ method\: :ref:`Callable<class_Callable>`\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`find<class_Array_method_find>`\ (\ what\: :ref:`Variant<class_Variant>`, from\: :ref:`int<class_int>` = 0\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`find_custom<class_Array_method_find_custom>`\ (\ method\: :ref:`Callable<class_Callable>`, from\: :ref:`int<class_int>` = 0\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Variant<class_Variant>` | :ref:`front<class_Array_method_front>`\ (\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Variant<class_Variant>` | :ref:`get<class_Array_method_get>`\ (\ index\: :ref:`int<class_int>`\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`get_typed_builtin<class_Array_method_get_typed_builtin>`\ (\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`StringName<class_StringName>` | :ref:`get_typed_class_name<class_Array_method_get_typed_class_name>`\ (\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Variant<class_Variant>` | :ref:`get_typed_script<class_Array_method_get_typed_script>`\ (\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`has<class_Array_method_has>`\ (\ value\: :ref:`Variant<class_Variant>`\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`hash<class_Array_method_hash>`\ (\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`insert<class_Array_method_insert>`\ (\ position\: :ref:`int<class_int>`, value\: :ref:`Variant<class_Variant>`\ ) |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`is_empty<class_Array_method_is_empty>`\ (\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`is_read_only<class_Array_method_is_read_only>`\ (\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`is_same_typed<class_Array_method_is_same_typed>`\ (\ array\: :ref:`Array<class_Array>`\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`is_typed<class_Array_method_is_typed>`\ (\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`make_read_only<class_Array_method_make_read_only>`\ (\ ) |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Array<class_Array>` | :ref:`map<class_Array_method_map>`\ (\ method\: :ref:`Callable<class_Callable>`\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Variant<class_Variant>` | :ref:`max<class_Array_method_max>`\ (\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Variant<class_Variant>` | :ref:`min<class_Array_method_min>`\ (\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Variant<class_Variant>` | :ref:`pick_random<class_Array_method_pick_random>`\ (\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Variant<class_Variant>` | :ref:`pop_at<class_Array_method_pop_at>`\ (\ position\: :ref:`int<class_int>`\ ) |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Variant<class_Variant>` | :ref:`pop_back<class_Array_method_pop_back>`\ (\ ) |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Variant<class_Variant>` | :ref:`pop_front<class_Array_method_pop_front>`\ (\ ) |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`push_back<class_Array_method_push_back>`\ (\ value\: :ref:`Variant<class_Variant>`\ ) |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`push_front<class_Array_method_push_front>`\ (\ value\: :ref:`Variant<class_Variant>`\ ) |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Variant<class_Variant>` | :ref:`reduce<class_Array_method_reduce>`\ (\ method\: :ref:`Callable<class_Callable>`, accum\: :ref:`Variant<class_Variant>` = null\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`remove_at<class_Array_method_remove_at>`\ (\ position\: :ref:`int<class_int>`\ ) |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`resize<class_Array_method_resize>`\ (\ size\: :ref:`int<class_int>`\ ) |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`reverse<class_Array_method_reverse>`\ (\ ) |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`rfind<class_Array_method_rfind>`\ (\ what\: :ref:`Variant<class_Variant>`, from\: :ref:`int<class_int>` = -1\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`rfind_custom<class_Array_method_rfind_custom>`\ (\ method\: :ref:`Callable<class_Callable>`, from\: :ref:`int<class_int>` = -1\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`set<class_Array_method_set>`\ (\ index\: :ref:`int<class_int>`, value\: :ref:`Variant<class_Variant>`\ ) |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`shuffle<class_Array_method_shuffle>`\ (\ ) |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`size<class_Array_method_size>`\ (\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Array<class_Array>` | :ref:`slice<class_Array_method_slice>`\ (\ begin\: :ref:`int<class_int>`, end\: :ref:`int<class_int>` = 2147483647, step\: :ref:`int<class_int>` = 1, deep\: :ref:`bool<class_bool>` = false\ ) |const| |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`sort<class_Array_method_sort>`\ (\ ) |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`sort_custom<class_Array_method_sort_custom>`\ (\ func\: :ref:`Callable<class_Callable>`\ ) |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. rst-class:: classref-reftable-group
Operators
---------
.. table::
:widths: auto
+-------------------------------+----------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`operator !=<class_Array_operator_neq_Array>`\ (\ right\: :ref:`Array<class_Array>`\ ) |
+-------------------------------+----------------------------------------------------------------------------------------------+
| :ref:`Array<class_Array>` | :ref:`operator +<class_Array_operator_sum_Array>`\ (\ right\: :ref:`Array<class_Array>`\ ) |
+-------------------------------+----------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`operator \<<class_Array_operator_lt_Array>`\ (\ right\: :ref:`Array<class_Array>`\ ) |
+-------------------------------+----------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`operator \<=<class_Array_operator_lte_Array>`\ (\ right\: :ref:`Array<class_Array>`\ ) |
+-------------------------------+----------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`operator ==<class_Array_operator_eq_Array>`\ (\ right\: :ref:`Array<class_Array>`\ ) |
+-------------------------------+----------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`operator ><class_Array_operator_gt_Array>`\ (\ right\: :ref:`Array<class_Array>`\ ) |
+-------------------------------+----------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`operator >=<class_Array_operator_gte_Array>`\ (\ right\: :ref:`Array<class_Array>`\ ) |
+-------------------------------+----------------------------------------------------------------------------------------------+
| :ref:`Variant<class_Variant>` | :ref:`operator []<class_Array_operator_idx_int>`\ (\ index\: :ref:`int<class_int>`\ ) |
+-------------------------------+----------------------------------------------------------------------------------------------+
.. rst-class:: classref-section-separator
----
.. rst-class:: classref-descriptions-group
Constructor Descriptions
------------------------
.. _class_Array_constructor_Array:
.. rst-class:: classref-constructor
:ref:`Array<class_Array>` **Array**\ (\ ) :ref:`🔗<class_Array_constructor_Array>`
Constructs an empty **Array**.
.. rst-class:: classref-item-separator
----
.. rst-class:: classref-constructor
:ref:`Array<class_Array>` **Array**\ (\ base\: :ref:`Array<class_Array>`, type\: :ref:`int<class_int>`, class_name\: :ref:`StringName<class_StringName>`, script\: :ref:`Variant<class_Variant>`\ )
Creates a typed array from the ``base`` array. A typed array can only contain elements of the given type, or that inherit from the given class, as described by this constructor's parameters:
- ``type`` is the built-in :ref:`Variant<class_Variant>` type, as one the :ref:`Variant.Type<enum_@GlobalScope_Variant.Type>` constants.
- ``class_name`` is the built-in class name (see :ref:`Object.get_class()<class_Object_method_get_class>`).
- ``script`` is the associated script. It must be a :ref:`Script<class_Script>` instance or ``null``.
If ``type`` is not :ref:`@GlobalScope.TYPE_OBJECT<class_@GlobalScope_constant_TYPE_OBJECT>`, ``class_name`` must be an empty :ref:`StringName<class_StringName>` and ``script`` must be ``null``.
::
class_name Sword
extends Node
class Stats:
pass
func _ready():
var a = Array([], TYPE_INT, "", null) # Array[int]
var b = Array([], TYPE_OBJECT, "Node", null) # Array[Node]
var c = Array([], TYPE_OBJECT, "Node", Sword) # Array[Sword]
var d = Array([], TYPE_OBJECT, "RefCounted", Stats) # Array[Stats]
The ``base`` array's elements are converted when necessary. If this is not possible or ``base`` is already typed, this constructor fails and returns an empty **Array**.
In GDScript, this constructor is usually not necessary, as it is possible to create a typed array through static typing:
::
var numbers: Array[float] = []
var children: Array[Node] = [$Node, $Sprite2D, $RigidBody3D]
var integers: Array[int] = [0.2, 4.5, -2.0]
print(integers) # Prints [0, 4, -2]
.. rst-class:: classref-item-separator
----
.. rst-class:: classref-constructor
:ref:`Array<class_Array>` **Array**\ (\ from\: :ref:`Array<class_Array>`\ )
Returns the same array as ``from``. If you need a copy of the array, use :ref:`duplicate()<class_Array_method_duplicate>`.
.. rst-class:: classref-item-separator
----
.. rst-class:: classref-constructor
:ref:`Array<class_Array>` **Array**\ (\ from\: :ref:`PackedByteArray<class_PackedByteArray>`\ )
Constructs an array from a :ref:`PackedByteArray<class_PackedByteArray>`.
.. rst-class:: classref-item-separator
----
.. rst-class:: classref-constructor
:ref:`Array<class_Array>` **Array**\ (\ from\: :ref:`PackedColorArray<class_PackedColorArray>`\ )
Constructs an array from a :ref:`PackedColorArray<class_PackedColorArray>`.
.. rst-class:: classref-item-separator
----
.. rst-class:: classref-constructor
:ref:`Array<class_Array>` **Array**\ (\ from\: :ref:`PackedFloat32Array<class_PackedFloat32Array>`\ )
Constructs an array from a :ref:`PackedFloat32Array<class_PackedFloat32Array>`.
.. rst-class:: classref-item-separator
----
.. rst-class:: classref-constructor
:ref:`Array<class_Array>` **Array**\ (\ from\: :ref:`PackedFloat64Array<class_PackedFloat64Array>`\ )
Constructs an array from a :ref:`PackedFloat64Array<class_PackedFloat64Array>`.
.. rst-class:: classref-item-separator
----
.. rst-class:: classref-constructor
:ref:`Array<class_Array>` **Array**\ (\ from\: :ref:`PackedInt32Array<class_PackedInt32Array>`\ )
Constructs an array from a :ref:`PackedInt32Array<class_PackedInt32Array>`.
.. rst-class:: classref-item-separator
----
.. rst-class:: classref-constructor
:ref:`Array<class_Array>` **Array**\ (\ from\: :ref:`PackedInt64Array<class_PackedInt64Array>`\ )
Constructs an array from a :ref:`PackedInt64Array<class_PackedInt64Array>`.
.. rst-class:: classref-item-separator
----
.. rst-class:: classref-constructor
:ref:`Array<class_Array>` **Array**\ (\ from\: :ref:`PackedStringArray<class_PackedStringArray>`\ )
Constructs an array from a :ref:`PackedStringArray<class_PackedStringArray>`.
.. rst-class:: classref-item-separator
----
.. rst-class:: classref-constructor
:ref:`Array<class_Array>` **Array**\ (\ from\: :ref:`PackedVector2Array<class_PackedVector2Array>`\ )
Constructs an array from a :ref:`PackedVector2Array<class_PackedVector2Array>`.
.. rst-class:: classref-item-separator
----
.. rst-class:: classref-constructor
:ref:`Array<class_Array>` **Array**\ (\ from\: :ref:`PackedVector3Array<class_PackedVector3Array>`\ )
Constructs an array from a :ref:`PackedVector3Array<class_PackedVector3Array>`.
.. rst-class:: classref-item-separator
----
.. rst-class:: classref-constructor
:ref:`Array<class_Array>` **Array**\ (\ from\: :ref:`PackedVector4Array<class_PackedVector4Array>`\ )
Constructs an array from a :ref:`PackedVector4Array<class_PackedVector4Array>`.
.. rst-class:: classref-section-separator
----
.. rst-class:: classref-descriptions-group
Method Descriptions
-------------------
.. _class_Array_method_all:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **all**\ (\ method\: :ref:`Callable<class_Callable>`\ ) |const| :ref:`🔗<class_Array_method_all>`
Calls the given :ref:`Callable<class_Callable>` on each element in the array and returns ``true`` if the :ref:`Callable<class_Callable>` returns ``true`` for *all* elements in the array. If the :ref:`Callable<class_Callable>` returns ``false`` for one array element or more, this method returns ``false``.
The ``method`` should take one :ref:`Variant<class_Variant>` parameter (the current array element) and return a :ref:`bool<class_bool>`.
.. tabs::
.. code-tab:: gdscript
func greater_than_5(number):
return number > 5
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).
# Same as the first line above, but using a lambda function.
print([6, 10, 6].all(func(element): return element > 5)) # Prints true
.. code-tab:: csharp
private static bool GreaterThan5(int number)
{
return number > 5;
}
public override void _Ready()
{
// Prints True (3/3 elements evaluate to true).
GD.Print(new Godot.Collections.Array>int< { 6, 10, 6 }.All(GreaterThan5));
// Prints False (1/3 elements evaluate to true).
GD.Print(new Godot.Collections.Array>int< { 4, 10, 4 }.All(GreaterThan5));
// Prints False (0/3 elements evaluate to true).
GD.Print(new Godot.Collections.Array>int< { 4, 4, 4 }.All(GreaterThan5));
// Prints True (0/0 elements evaluate to true).
GD.Print(new Godot.Collections.Array>int< { }.All(GreaterThan5));
// Same as the first line above, but using a lambda function.
GD.Print(new Godot.Collections.Array>int< { 6, 10, 6 }.All(element => element > 5)); // Prints True
}
See also :ref:`any()<class_Array_method_any>`, :ref:`filter()<class_Array_method_filter>`, :ref:`map()<class_Array_method_map>` and :ref:`reduce()<class_Array_method_reduce>`.
\ **Note:** Unlike relying on the size of an array returned by :ref:`filter()<class_Array_method_filter>`, this method will return as early as possible to improve performance (especially with large arrays).
\ **Note:** For an empty array, this method `always <https://en.wikipedia.org/wiki/Vacuous_truth>`__ returns ``true``.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_any:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **any**\ (\ method\: :ref:`Callable<class_Callable>`\ ) |const| :ref:`🔗<class_Array_method_any>`
Calls the given :ref:`Callable<class_Callable>` on each element in the array and returns ``true`` if the :ref:`Callable<class_Callable>` returns ``true`` for *one or more* elements in the array. If the :ref:`Callable<class_Callable>` returns ``false`` for all elements in the array, this method returns ``false``.
The ``method`` should take one :ref:`Variant<class_Variant>` parameter (the current array element) and return a :ref:`bool<class_bool>`.
::
func greater_than_5(number):
return number > 5
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).
# Same as the first line above, but using a lambda function.
print([6, 10, 6].any(func(number): return number > 5)) # Prints true
See also :ref:`all()<class_Array_method_all>`, :ref:`filter()<class_Array_method_filter>`, :ref:`map()<class_Array_method_map>` and :ref:`reduce()<class_Array_method_reduce>`.
\ **Note:** Unlike relying on the size of an array returned by :ref:`filter()<class_Array_method_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``.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_append:
.. rst-class:: classref-method
|void| **append**\ (\ value\: :ref:`Variant<class_Variant>`\ ) :ref:`🔗<class_Array_method_append>`
Appends ``value`` at the end of the array (alias of :ref:`push_back()<class_Array_method_push_back>`).
.. rst-class:: classref-item-separator
----
.. _class_Array_method_append_array:
.. rst-class:: classref-method
|void| **append_array**\ (\ array\: :ref:`Array<class_Array>`\ ) :ref:`🔗<class_Array_method_append_array>`
Appends another ``array`` at the end of this array.
::
var numbers = [1, 2, 3]
var extra = [4, 5, 6]
numbers.append_array(extra)
print(numbers) # Prints [1, 2, 3, 4, 5, 6]
.. rst-class:: classref-item-separator
----
.. _class_Array_method_assign:
.. rst-class:: classref-method
|void| **assign**\ (\ array\: :ref:`Array<class_Array>`\ ) :ref:`🔗<class_Array_method_assign>`
Assigns elements of another ``array`` into the array. Resizes the array to match ``array``. Performs type conversions if the array is typed.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_back:
.. rst-class:: classref-method
:ref:`Variant<class_Variant>` **back**\ (\ ) |const| :ref:`🔗<class_Array_method_back>`
Returns the last element of the array. If the array is empty, fails and returns ``null``. See also :ref:`front()<class_Array_method_front>`.
\ **Note:** Unlike with the ``[]`` operator (``array[-1]``), an error is generated without stopping project execution.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_bsearch:
.. rst-class:: classref-method
:ref:`int<class_int>` **bsearch**\ (\ value\: :ref:`Variant<class_Variant>`, before\: :ref:`bool<class_bool>` = true\ ) |const| :ref:`🔗<class_Array_method_bsearch>`
Returns the index of ``value`` in the sorted array. If it cannot be found, returns where ``value`` should be inserted to keep the array sorted. The algorithm used is `binary search <https://en.wikipedia.org/wiki/Binary_search_algorithm>`__.
If ``before`` is ``true`` (as by default), the returned index comes before all existing elements equal to ``value`` in the array.
::
var numbers = [2, 4, 8, 10]
var idx = numbers.bsearch(7)
numbers.insert(idx, 7)
print(numbers) # Prints [2, 4, 7, 8, 10]
var fruits = ["Apple", "Lemon", "Lemon", "Orange"]
print(fruits.bsearch("Lemon", true)) # Prints 1, points at the first "Lemon".
print(fruits.bsearch("Lemon", false)) # Prints 3, points at "Orange".
\ **Note:** Calling :ref:`bsearch()<class_Array_method_bsearch>` on an *unsorted* array will result in unexpected behavior. Use :ref:`sort()<class_Array_method_sort>` before calling this method.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_bsearch_custom:
.. rst-class:: classref-method
:ref:`int<class_int>` **bsearch_custom**\ (\ value\: :ref:`Variant<class_Variant>`, func\: :ref:`Callable<class_Callable>`, before\: :ref:`bool<class_bool>` = true\ ) |const| :ref:`🔗<class_Array_method_bsearch_custom>`
Returns the index of ``value`` in the sorted array. If it cannot be found, returns where ``value`` should be inserted to keep the array sorted (using ``func`` for the comparisons). The algorithm used is `binary search <https://en.wikipedia.org/wiki/Binary_search_algorithm>`__.
Similar to :ref:`sort_custom()<class_Array_method_sort_custom>`, ``func`` is called as many times as necessary, receiving one array element and ``value`` as arguments. The function should return ``true`` if the array element should be *behind* ``value``, otherwise it should return ``false``.
If ``before`` is ``true`` (as by default), the returned index comes before all existing elements equal to ``value`` in the array.
::
func sort_by_amount(a, b):
if a[1] < b[1]:
return true
return false
func _ready():
var my_items = [["Tomato", 2], ["Kiwi", 5], ["Rice", 9]]
var apple = ["Apple", 5]
# "Apple" is inserted before "Kiwi".
my_items.insert(my_items.bsearch_custom(apple, sort_by_amount, true), apple)
var banana = ["Banana", 5]
# "Banana" is inserted after "Kiwi".
my_items.insert(my_items.bsearch_custom(banana, sort_by_amount, false), banana)
# Prints [["Tomato", 2], ["Apple", 5], ["Kiwi", 5], ["Banana", 5], ["Rice", 9]]
print(my_items)
\ **Note:** Calling :ref:`bsearch_custom()<class_Array_method_bsearch_custom>` on an *unsorted* array will result in unexpected behavior. Use :ref:`sort_custom()<class_Array_method_sort_custom>` with ``func`` before calling this method.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_clear:
.. rst-class:: classref-method
|void| **clear**\ (\ ) :ref:`🔗<class_Array_method_clear>`
Removes all elements from the array. This is equivalent to using :ref:`resize()<class_Array_method_resize>` with a size of ``0``.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_count:
.. rst-class:: classref-method
:ref:`int<class_int>` **count**\ (\ value\: :ref:`Variant<class_Variant>`\ ) |const| :ref:`🔗<class_Array_method_count>`
Returns the number of times an element is in the array.
To count how many elements in an array satisfy a condition, see :ref:`reduce()<class_Array_method_reduce>`.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_duplicate:
.. rst-class:: classref-method
:ref:`Array<class_Array>` **duplicate**\ (\ deep\: :ref:`bool<class_bool>` = false\ ) |const| :ref:`🔗<class_Array_method_duplicate>`
Returns a new copy of the array.
By default, a **shallow** copy is returned: all nested **Array**, :ref:`Dictionary<class_Dictionary>`, and :ref:`Resource<class_Resource>` elements are shared with the original array. Modifying any of those in one array will also affect them in the other.
If ``deep`` is ``true``, a **deep** copy is returned: all nested arrays and dictionaries are also duplicated (recursively). Any :ref:`Resource<class_Resource>` is still shared with the original array, though.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_duplicate_deep:
.. rst-class:: classref-method
:ref:`Array<class_Array>` **duplicate_deep**\ (\ deep_subresources_mode\: :ref:`int<class_int>` = 1\ ) |const| :ref:`🔗<class_Array_method_duplicate_deep>`
Duplicates this array, deeply, like :ref:`duplicate()<class_Array_method_duplicate>` when passing ``true``, with extra control over how subresources are handled.
\ ``deep_subresources_mode`` must be one of the values from :ref:`DeepDuplicateMode<enum_Resource_DeepDuplicateMode>`. By default, only internal resources will be duplicated (recursively).
.. rst-class:: classref-item-separator
----
.. _class_Array_method_erase:
.. rst-class:: classref-method
|void| **erase**\ (\ value\: :ref:`Variant<class_Variant>`\ ) :ref:`🔗<class_Array_method_erase>`
Finds and removes the first occurrence of ``value`` from the array. If ``value`` does not exist in the array, nothing happens. To remove an element by index, use :ref:`remove_at()<class_Array_method_remove_at>` instead.
\ **Note:** This method shifts every element's index after the removed ``value`` back, which may have a noticeable performance cost, especially on larger arrays.
\ **Note:** Erasing elements while iterating over arrays is **not** supported and will result in unpredictable behavior.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_fill:
.. rst-class:: classref-method
|void| **fill**\ (\ value\: :ref:`Variant<class_Variant>`\ ) :ref:`🔗<class_Array_method_fill>`
Assigns the given ``value`` to all elements in the array.
This method can often be combined with :ref:`resize()<class_Array_method_resize>` to create an array with a given size and initialized elements:
.. tabs::
.. code-tab:: gdscript
var array = []
array.resize(5)
array.fill(2)
print(array) # Prints [2, 2, 2, 2, 2]
.. code-tab:: csharp
Godot.Collections.Array array = [];
array.Resize(5);
array.Fill(2);
GD.Print(array); // Prints [2, 2, 2, 2, 2]
\ **Note:** If ``value`` is a :ref:`Variant<class_Variant>` passed by reference (:ref:`Object<class_Object>`-derived, **Array**, :ref:`Dictionary<class_Dictionary>`, etc.), the array will be filled with references to the same ``value``, which are not duplicates.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_filter:
.. rst-class:: classref-method
:ref:`Array<class_Array>` **filter**\ (\ method\: :ref:`Callable<class_Callable>`\ ) |const| :ref:`🔗<class_Array_method_filter>`
Calls the given :ref:`Callable<class_Callable>` on each element in the array and returns a new, filtered **Array**.
The ``method`` receives one of the array elements as an argument, and should return ``true`` to add the element to the filtered array, or ``false`` to exclude it.
::
func is_even(number):
return number % 2 == 0
func _ready():
print([1, 4, 5, 8].filter(is_even)) # Prints [4, 8]
# Same as above, but using a lambda function.
print([1, 4, 5, 8].filter(func(number): return number % 2 == 0))
See also :ref:`any()<class_Array_method_any>`, :ref:`all()<class_Array_method_all>`, :ref:`map()<class_Array_method_map>` and :ref:`reduce()<class_Array_method_reduce>`.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_find:
.. rst-class:: classref-method
:ref:`int<class_int>` **find**\ (\ what\: :ref:`Variant<class_Variant>`, from\: :ref:`int<class_int>` = 0\ ) |const| :ref:`🔗<class_Array_method_find>`
Returns the index of the **first** occurrence of ``what`` in this array, or ``-1`` if there are none. The search's start can be specified with ``from``, continuing to the end of the array.
\ **Note:** If you just want to know whether the array contains ``what``, use :ref:`has()<class_Array_method_has>` (``Contains`` in C#). In GDScript, you may also use the ``in`` operator.
\ **Note:** For performance reasons, the search is affected by ``what``'s :ref:`Variant.Type<enum_@GlobalScope_Variant.Type>`. For example, ``7`` (:ref:`int<class_int>`) and ``7.0`` (:ref:`float<class_float>`) are not considered equal for this method.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_find_custom:
.. rst-class:: classref-method
:ref:`int<class_int>` **find_custom**\ (\ method\: :ref:`Callable<class_Callable>`, from\: :ref:`int<class_int>` = 0\ ) |const| :ref:`🔗<class_Array_method_find_custom>`
Returns the index of the **first** element in the array that causes ``method`` to return ``true``, or ``-1`` if there are none. The search's start can be specified with ``from``, continuing to the end of the array.
\ ``method`` is a callable that takes an element of the array, and returns a :ref:`bool<class_bool>`.
\ **Note:** If you just want to know whether the array contains *anything* that satisfies ``method``, use :ref:`any()<class_Array_method_any>`.
.. tabs::
.. code-tab:: gdscript
func is_even(number):
return number % 2 == 0
func _ready():
print([1, 3, 4, 7].find_custom(is_even.bind())) # Prints 2
.. rst-class:: classref-item-separator
----
.. _class_Array_method_front:
.. rst-class:: classref-method
:ref:`Variant<class_Variant>` **front**\ (\ ) |const| :ref:`🔗<class_Array_method_front>`
Returns the first element of the array. If the array is empty, fails and returns ``null``. See also :ref:`back()<class_Array_method_back>`.
\ **Note:** Unlike with the ``[]`` operator (``array[0]``), an error is generated without stopping project execution.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_get:
.. rst-class:: classref-method
:ref:`Variant<class_Variant>` **get**\ (\ index\: :ref:`int<class_int>`\ ) |const| :ref:`🔗<class_Array_method_get>`
Returns the element at the given ``index`` in the array. If ``index`` is out-of-bounds or negative, this method fails and returns ``null``.
This method is similar (but not identical) to the ``[]`` operator. Most notably, when this method fails, it doesn't pause project execution if run from the editor.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_get_typed_builtin:
.. rst-class:: classref-method
:ref:`int<class_int>` **get_typed_builtin**\ (\ ) |const| :ref:`🔗<class_Array_method_get_typed_builtin>`
Returns the built-in :ref:`Variant<class_Variant>` type of the typed array as a :ref:`Variant.Type<enum_@GlobalScope_Variant.Type>` constant. If the array is not typed, returns :ref:`@GlobalScope.TYPE_NIL<class_@GlobalScope_constant_TYPE_NIL>`. See also :ref:`is_typed()<class_Array_method_is_typed>`.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_get_typed_class_name:
.. rst-class:: classref-method
:ref:`StringName<class_StringName>` **get_typed_class_name**\ (\ ) |const| :ref:`🔗<class_Array_method_get_typed_class_name>`
Returns the **built-in** class name of the typed array, if the built-in :ref:`Variant<class_Variant>` type :ref:`@GlobalScope.TYPE_OBJECT<class_@GlobalScope_constant_TYPE_OBJECT>`. Otherwise, returns an empty :ref:`StringName<class_StringName>`. See also :ref:`is_typed()<class_Array_method_is_typed>` and :ref:`Object.get_class()<class_Object_method_get_class>`.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_get_typed_script:
.. rst-class:: classref-method
:ref:`Variant<class_Variant>` **get_typed_script**\ (\ ) |const| :ref:`🔗<class_Array_method_get_typed_script>`
Returns the :ref:`Script<class_Script>` instance associated with this typed array, or ``null`` if it does not exist. See also :ref:`is_typed()<class_Array_method_is_typed>`.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_has:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **has**\ (\ value\: :ref:`Variant<class_Variant>`\ ) |const| :ref:`🔗<class_Array_method_has>`
Returns ``true`` if the array contains the given ``value``.
.. tabs::
.. code-tab:: gdscript
print(["inside", 7].has("inside")) # Prints true
print(["inside", 7].has("outside")) # Prints false
print(["inside", 7].has(7)) # Prints true
print(["inside", 7].has("7")) # Prints false
.. code-tab:: csharp
Godot.Collections.Array arr = ["inside", 7];
// By C# convention, this method is renamed to `Contains`.
GD.Print(arr.Contains("inside")); // Prints True
GD.Print(arr.Contains("outside")); // Prints False
GD.Print(arr.Contains(7)); // Prints True
GD.Print(arr.Contains("7")); // Prints False
In GDScript, this is equivalent to the ``in`` operator:
::
if 4 in [2, 4, 6, 8]:
print("4 is here!") # Will be printed.
\ **Note:** For performance reasons, the search is affected by the ``value``'s :ref:`Variant.Type<enum_@GlobalScope_Variant.Type>`. For example, ``7`` (:ref:`int<class_int>`) and ``7.0`` (:ref:`float<class_float>`) are not considered equal for this method.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_hash:
.. rst-class:: classref-method
:ref:`int<class_int>` **hash**\ (\ ) |const| :ref:`🔗<class_Array_method_hash>`
Returns a hashed 32-bit integer value representing the array and its contents.
\ **Note:** Arrays with equal hash values are *not* guaranteed to be the same, as a result of hash collisions. On the contrary, arrays with different hash values are guaranteed to be different.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_insert:
.. rst-class:: classref-method
:ref:`int<class_int>` **insert**\ (\ position\: :ref:`int<class_int>`, value\: :ref:`Variant<class_Variant>`\ ) :ref:`🔗<class_Array_method_insert>`
Inserts a new element (``value``) at a given index (``position``) in the array. ``position`` should be between ``0`` and the array's :ref:`size()<class_Array_method_size>`. If negative, ``position`` is considered relative to the end of the array.
Returns :ref:`@GlobalScope.OK<class_@GlobalScope_constant_OK>` on success, or one of the other :ref:`Error<enum_@GlobalScope_Error>` constants if this method fails.
\ **Note:** Every element's index after ``position`` needs to be shifted forward, which may have a noticeable performance cost, especially on larger arrays.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_is_empty:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **is_empty**\ (\ ) |const| :ref:`🔗<class_Array_method_is_empty>`
Returns ``true`` if the array is empty (``[]``). See also :ref:`size()<class_Array_method_size>`.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_is_read_only:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **is_read_only**\ (\ ) |const| :ref:`🔗<class_Array_method_is_read_only>`
Returns ``true`` if the array is read-only. See :ref:`make_read_only()<class_Array_method_make_read_only>`.
In GDScript, arrays are automatically read-only if declared with the ``const`` keyword.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_is_same_typed:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **is_same_typed**\ (\ array\: :ref:`Array<class_Array>`\ ) |const| :ref:`🔗<class_Array_method_is_same_typed>`
Returns ``true`` if this array is typed the same as the given ``array``. See also :ref:`is_typed()<class_Array_method_is_typed>`.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_is_typed:
.. rst-class:: classref-method
:ref:`bool<class_bool>` **is_typed**\ (\ ) |const| :ref:`🔗<class_Array_method_is_typed>`
Returns ``true`` if the array is typed. Typed arrays can only contain elements of a specific type, as defined by the typed array constructor. The methods of a typed array are still expected to return a generic :ref:`Variant<class_Variant>`.
In GDScript, it is possible to define a typed array with static typing:
::
var numbers: Array[float] = [0.2, 4.2, -2.0]
print(numbers.is_typed()) # Prints true
.. rst-class:: classref-item-separator
----
.. _class_Array_method_make_read_only:
.. rst-class:: classref-method
|void| **make_read_only**\ (\ ) :ref:`🔗<class_Array_method_make_read_only>`
Makes the array read-only. The array's elements cannot be overridden with different values, and their order cannot change. Does not apply to nested elements, such as dictionaries.
In GDScript, arrays are automatically read-only if declared with the ``const`` keyword.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_map:
.. rst-class:: classref-method
:ref:`Array<class_Array>` **map**\ (\ method\: :ref:`Callable<class_Callable>`\ ) |const| :ref:`🔗<class_Array_method_map>`
Calls the given :ref:`Callable<class_Callable>` for each element in the array and returns a new array filled with values returned by the ``method``.
The ``method`` should take one :ref:`Variant<class_Variant>` parameter (the current array element) and can return any :ref:`Variant<class_Variant>`.
::
func double(number):
return number * 2
func _ready():
print([1, 2, 3].map(double)) # Prints [2, 4, 6]
# Same as above, but using a lambda function.
print([1, 2, 3].map(func(element): return element * 2))
See also :ref:`filter()<class_Array_method_filter>`, :ref:`reduce()<class_Array_method_reduce>`, :ref:`any()<class_Array_method_any>` and :ref:`all()<class_Array_method_all>`.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_max:
.. rst-class:: classref-method
:ref:`Variant<class_Variant>` **max**\ (\ ) |const| :ref:`🔗<class_Array_method_max>`
Returns the maximum value contained in the array, if all elements can be compared. Otherwise, returns ``null``. See also :ref:`min()<class_Array_method_min>`.
To find the maximum value using a custom comparator, you can use :ref:`reduce()<class_Array_method_reduce>`.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_min:
.. rst-class:: classref-method
:ref:`Variant<class_Variant>` **min**\ (\ ) |const| :ref:`🔗<class_Array_method_min>`
Returns the minimum value contained in the array, if all elements can be compared. Otherwise, returns ``null``. See also :ref:`max()<class_Array_method_max>`.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_pick_random:
.. rst-class:: classref-method
:ref:`Variant<class_Variant>` **pick_random**\ (\ ) |const| :ref:`🔗<class_Array_method_pick_random>`
Returns a random element from the array. Generates an error and returns ``null`` if the array is empty.
.. tabs::
.. code-tab:: gdscript
# May print 1, 2, 3.25, or "Hi".
print([1, 2, 3.25, "Hi"].pick_random())
.. code-tab:: csharp
Godot.Collections.Array array = [1, 2, 3.25f, "Hi"];
GD.Print(array.PickRandom()); // May print 1, 2, 3.25, or "Hi".
\ **Note:** Like many similar functions in the engine (such as :ref:`@GlobalScope.randi()<class_@GlobalScope_method_randi>` or :ref:`shuffle()<class_Array_method_shuffle>`), this method uses a common, global random seed. To get a predictable outcome from this method, see :ref:`@GlobalScope.seed()<class_@GlobalScope_method_seed>`.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_pop_at:
.. rst-class:: classref-method
:ref:`Variant<class_Variant>` **pop_at**\ (\ position\: :ref:`int<class_int>`\ ) :ref:`🔗<class_Array_method_pop_at>`
Removes and returns the element of the array at index ``position``. If negative, ``position`` is considered relative to the end of the array. Returns ``null`` if the array is empty. If ``position`` is out of bounds, an error message is also generated.
\ **Note:** This method shifts every element's index after ``position`` back, which may have a noticeable performance cost, especially on larger arrays.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_pop_back:
.. rst-class:: classref-method
:ref:`Variant<class_Variant>` **pop_back**\ (\ ) :ref:`🔗<class_Array_method_pop_back>`
Removes and returns the last element of the array. Returns ``null`` if the array is empty, without generating an error. See also :ref:`pop_front()<class_Array_method_pop_front>`.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_pop_front:
.. rst-class:: classref-method
:ref:`Variant<class_Variant>` **pop_front**\ (\ ) :ref:`🔗<class_Array_method_pop_front>`
Removes and returns the first element of the array. Returns ``null`` if the array is empty, without generating an error. See also :ref:`pop_back()<class_Array_method_pop_back>`.
\ **Note:** This method shifts every other element's index back, which may have a noticeable performance cost, especially on larger arrays.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_push_back:
.. rst-class:: classref-method
|void| **push_back**\ (\ value\: :ref:`Variant<class_Variant>`\ ) :ref:`🔗<class_Array_method_push_back>`
Appends an element at the end of the array. See also :ref:`push_front()<class_Array_method_push_front>`.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_push_front:
.. rst-class:: classref-method
|void| **push_front**\ (\ value\: :ref:`Variant<class_Variant>`\ ) :ref:`🔗<class_Array_method_push_front>`
Adds an element at the beginning of the array. See also :ref:`push_back()<class_Array_method_push_back>`.
\ **Note:** This method shifts every other element's index forward, which may have a noticeable performance cost, especially on larger arrays.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_reduce:
.. rst-class:: classref-method
:ref:`Variant<class_Variant>` **reduce**\ (\ method\: :ref:`Callable<class_Callable>`, accum\: :ref:`Variant<class_Variant>` = null\ ) |const| :ref:`🔗<class_Array_method_reduce>`
Calls the given :ref:`Callable<class_Callable>` for each element in array, accumulates the result in ``accum``, then returns it.
The ``method`` takes two arguments: the current value of ``accum`` and the current array element. If ``accum`` is ``null`` (as by default), the iteration will start from the second element, with the first one used as initial value of ``accum``.
::
func sum(accum, number):
return accum + number
func _ready():
print([1, 2, 3].reduce(sum, 0)) # Prints 6
print([1, 2, 3].reduce(sum, 10)) # Prints 16
# Same as above, but using a lambda function.
print([1, 2, 3].reduce(func(accum, number): return accum + number, 10))
If :ref:`max()<class_Array_method_max>` is not desirable, this method may also be used to implement a custom comparator:
::
func _ready():
var arr = [Vector2i(5, 0), Vector2i(3, 4), Vector2i(1, 2)]
var longest_vec = arr.reduce(func(max, vec): return vec if is_length_greater(vec, max) else max)
print(longest_vec) # Prints (3, 4)
func is_length_greater(a, b):
return a.length() > b.length()
This method can also be used to count how many elements in an array satisfy a certain condition, similar to :ref:`count()<class_Array_method_count>`:
::
func is_even(number):
return number % 2 == 0
func _ready():
var arr = [1, 2, 3, 4, 5]
# If the current element is even, increment count, otherwise leave count the same.
var even_count = arr.reduce(func(count, next): return count + 1 if is_even(next) else count, 0)
print(even_count) # Prints 2
See also :ref:`map()<class_Array_method_map>`, :ref:`filter()<class_Array_method_filter>`, :ref:`any()<class_Array_method_any>`, and :ref:`all()<class_Array_method_all>`.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_remove_at:
.. rst-class:: classref-method
|void| **remove_at**\ (\ position\: :ref:`int<class_int>`\ ) :ref:`🔗<class_Array_method_remove_at>`
Removes the element from the array at the given index (``position``). If the index is out of bounds, this method fails. If the index is negative, ``position`` is considered relative to the end of the array.
If you need to return the removed element, use :ref:`pop_at()<class_Array_method_pop_at>`. To remove an element by value, use :ref:`erase()<class_Array_method_erase>` instead.
\ **Note:** This method shifts every element's index after ``position`` back, which may have a noticeable performance cost, especially on larger arrays.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_resize:
.. rst-class:: classref-method
:ref:`int<class_int>` **resize**\ (\ size\: :ref:`int<class_int>`\ ) :ref:`🔗<class_Array_method_resize>`
Sets the array's number of elements to ``size``. If ``size`` is smaller than the array's current size, the elements at the end are removed. If ``size`` is greater, new default elements (usually ``null``) are added, depending on the array's type.
Returns :ref:`@GlobalScope.OK<class_@GlobalScope_constant_OK>` on success, or one of the following :ref:`Error<enum_@GlobalScope_Error>` constants if this method fails: :ref:`@GlobalScope.ERR_LOCKED<class_@GlobalScope_constant_ERR_LOCKED>` if the array is read-only, :ref:`@GlobalScope.ERR_INVALID_PARAMETER<class_@GlobalScope_constant_ERR_INVALID_PARAMETER>` if the size is negative, or :ref:`@GlobalScope.ERR_OUT_OF_MEMORY<class_@GlobalScope_constant_ERR_OUT_OF_MEMORY>` if allocations fail. Use :ref:`size()<class_Array_method_size>` to find the actual size of the array after resize.
\ **Note:** Calling this method once and assigning the new values is faster than calling :ref:`append()<class_Array_method_append>` for every new element.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_reverse:
.. rst-class:: classref-method
|void| **reverse**\ (\ ) :ref:`🔗<class_Array_method_reverse>`
Reverses the order of all elements in the array.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_rfind:
.. rst-class:: classref-method
:ref:`int<class_int>` **rfind**\ (\ what\: :ref:`Variant<class_Variant>`, from\: :ref:`int<class_int>` = -1\ ) |const| :ref:`🔗<class_Array_method_rfind>`
Returns the index of the **last** occurrence of ``what`` in this array, or ``-1`` if there are none. The search's start can be specified with ``from``, continuing to the beginning of the array. This method is the reverse of :ref:`find()<class_Array_method_find>`.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_rfind_custom:
.. rst-class:: classref-method
:ref:`int<class_int>` **rfind_custom**\ (\ method\: :ref:`Callable<class_Callable>`, from\: :ref:`int<class_int>` = -1\ ) |const| :ref:`🔗<class_Array_method_rfind_custom>`
Returns the index of the **last** element of the array that causes ``method`` to return ``true``, or ``-1`` if there are none. The search's start can be specified with ``from``, continuing to the beginning of the array. This method is the reverse of :ref:`find_custom()<class_Array_method_find_custom>`.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_set:
.. rst-class:: classref-method
|void| **set**\ (\ index\: :ref:`int<class_int>`, value\: :ref:`Variant<class_Variant>`\ ) :ref:`🔗<class_Array_method_set>`
Sets the value of the element at the given ``index`` to the given ``value``. This will not change the size of the array, it only changes the value at an index already in the array. This is the same as using the ``[]`` operator (``array[index] = value``).
.. rst-class:: classref-item-separator
----
.. _class_Array_method_shuffle:
.. rst-class:: classref-method
|void| **shuffle**\ (\ ) :ref:`🔗<class_Array_method_shuffle>`
Shuffles all elements of the array in a random order.
\ **Note:** Like many similar functions in the engine (such as :ref:`@GlobalScope.randi()<class_@GlobalScope_method_randi>` or :ref:`pick_random()<class_Array_method_pick_random>`), this method uses a common, global random seed. To get a predictable outcome from this method, see :ref:`@GlobalScope.seed()<class_@GlobalScope_method_seed>`.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_size:
.. rst-class:: classref-method
:ref:`int<class_int>` **size**\ (\ ) |const| :ref:`🔗<class_Array_method_size>`
Returns the number of elements in the array. Empty arrays (``[]``) always return ``0``. See also :ref:`is_empty()<class_Array_method_is_empty>`.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_slice:
.. rst-class:: classref-method
:ref:`Array<class_Array>` **slice**\ (\ begin\: :ref:`int<class_int>`, end\: :ref:`int<class_int>` = 2147483647, step\: :ref:`int<class_int>` = 1, deep\: :ref:`bool<class_bool>` = false\ ) |const| :ref:`🔗<class_Array_method_slice>`
Returns a new **Array** containing this array's elements, from index ``begin`` (inclusive) to ``end`` (exclusive), every ``step`` elements.
If either ``begin`` or ``end`` are negative, their value is relative to the end of the array.
If ``step`` is negative, this method iterates through the array in reverse, returning a slice ordered backwards. For this to work, ``begin`` must be greater than ``end``.
If ``deep`` is ``true``, all nested **Array** and :ref:`Dictionary<class_Dictionary>` elements in the slice are duplicated from the original, recursively. See also :ref:`duplicate()<class_Array_method_duplicate>`.
::
var letters = ["A", "B", "C", "D", "E", "F"]
print(letters.slice(0, 2)) # Prints ["A", "B"]
print(letters.slice(2, -2)) # Prints ["C", "D"]
print(letters.slice(-2, 6)) # Prints ["E", "F"]
print(letters.slice(0, 6, 2)) # Prints ["A", "C", "E"]
print(letters.slice(4, 1, -1)) # Prints ["E", "D", "C"]
.. rst-class:: classref-item-separator
----
.. _class_Array_method_sort:
.. rst-class:: classref-method
|void| **sort**\ (\ ) :ref:`🔗<class_Array_method_sort>`
Sorts the array in ascending order. The final order is dependent on the "less than" (``<``) comparison between elements.
.. tabs::
.. code-tab:: gdscript
var numbers = [10, 5, 2.5, 8]
numbers.sort()
print(numbers) # Prints [2.5, 5, 8, 10]
.. code-tab:: csharp
Godot.Collections.Array numbers = [10, 5, 2.5, 8];
numbers.Sort();
GD.Print(numbers); // Prints [2.5, 5, 8, 10]
\ **Note:** The sorting algorithm used is not `stable <https://en.wikipedia.org/wiki/Sorting_algorithm#Stability>`__. This means that equivalent elements (such as ``2`` and ``2.0``) may have their order changed when calling :ref:`sort()<class_Array_method_sort>`.
.. rst-class:: classref-item-separator
----
.. _class_Array_method_sort_custom:
.. rst-class:: classref-method
|void| **sort_custom**\ (\ func\: :ref:`Callable<class_Callable>`\ ) :ref:`🔗<class_Array_method_sort_custom>`
Sorts the array using a custom :ref:`Callable<class_Callable>`.
\ ``func`` is called as many times as necessary, receiving two array elements as arguments. The function should return ``true`` if the first element should be moved *before* the second one, otherwise it should return ``false``.
::
func sort_ascending(a, b):
if a[1] < b[1]:
return true
return false
func _ready():
var my_items = [["Tomato", 5], ["Apple", 9], ["Rice", 4]]
my_items.sort_custom(sort_ascending)
print(my_items) # Prints [["Rice", 4], ["Tomato", 5], ["Apple", 9]]
# Sort descending, using a lambda function.
my_items.sort_custom(func(a, b): return a[1] > b[1])
print(my_items) # Prints [["Apple", 9], ["Tomato", 5], ["Rice", 4]]
It may also be necessary to use this method to sort strings by natural order, with :ref:`String.naturalnocasecmp_to()<class_String_method_naturalnocasecmp_to>`, as in the following example:
::
var files = ["newfile1", "newfile2", "newfile10", "newfile11"]
files.sort_custom(func(a, b): return a.naturalnocasecmp_to(b) < 0)
print(files) # Prints ["newfile1", "newfile2", "newfile10", "newfile11"]
\ **Note:** In C#, this method is not supported.
\ **Note:** The sorting algorithm used is not `stable <https://en.wikipedia.org/wiki/Sorting_algorithm#Stability>`__. This means that values considered equal may have their order changed when calling this method.
\ **Note:** You should not randomize the return value of ``func``, as the heapsort algorithm expects a consistent result. Randomizing the return value will result in unexpected behavior.
.. rst-class:: classref-section-separator
----
.. rst-class:: classref-descriptions-group
Operator Descriptions
---------------------
.. _class_Array_operator_neq_Array:
.. rst-class:: classref-operator
:ref:`bool<class_bool>` **operator !=**\ (\ right\: :ref:`Array<class_Array>`\ ) :ref:`🔗<class_Array_operator_neq_Array>`
Returns ``true`` if the array's size or its elements are different than ``right``'s.
.. rst-class:: classref-item-separator
----
.. _class_Array_operator_sum_Array:
.. rst-class:: classref-operator
:ref:`Array<class_Array>` **operator +**\ (\ right\: :ref:`Array<class_Array>`\ ) :ref:`🔗<class_Array_operator_sum_Array>`
Appends the ``right`` array to the left operand, creating a new **Array**. This is also known as an array concatenation.
.. tabs::
.. code-tab:: gdscript
var array1 = ["One", 2]
var array2 = [3, "Four"]
print(array1 + array2) # Prints ["One", 2, 3, "Four"]
.. code-tab:: csharp
// Note that concatenation is not possible with C#'s native Array type.
Godot.Collections.Array array1 = ["One", 2];
Godot.Collections.Array array2 = [3, "Four"];
GD.Print(array1 + array2); // Prints ["One", 2, 3, "Four"]
\ **Note:** For existing arrays, :ref:`append_array()<class_Array_method_append_array>` is much more efficient than concatenation and assignment with the ``+=`` operator.
.. rst-class:: classref-item-separator
----
.. _class_Array_operator_lt_Array:
.. rst-class:: classref-operator
:ref:`bool<class_bool>` **operator <**\ (\ right\: :ref:`Array<class_Array>`\ ) :ref:`🔗<class_Array_operator_lt_Array>`
Compares the elements of both arrays in order, starting from index ``0`` and ending on the last index in common between both arrays. For each pair of elements, returns ``true`` if this array's element is less than ``right``'s, ``false`` if this element is greater. Otherwise, continues to the next pair.
If all searched elements are equal, returns ``true`` if this array's size is less than ``right``'s, otherwise returns ``false``.
.. rst-class:: classref-item-separator
----
.. _class_Array_operator_lte_Array:
.. rst-class:: classref-operator
:ref:`bool<class_bool>` **operator <=**\ (\ right\: :ref:`Array<class_Array>`\ ) :ref:`🔗<class_Array_operator_lte_Array>`
Compares the elements of both arrays in order, starting from index ``0`` and ending on the last index in common between both arrays. For each pair of elements, returns ``true`` if this array's element is less than ``right``'s, ``false`` if this element is greater. Otherwise, continues to the next pair.
If all searched elements are equal, returns ``true`` if this array's size is less or equal to ``right``'s, otherwise returns ``false``.
.. rst-class:: classref-item-separator
----
.. _class_Array_operator_eq_Array:
.. rst-class:: classref-operator
:ref:`bool<class_bool>` **operator ==**\ (\ right\: :ref:`Array<class_Array>`\ ) :ref:`🔗<class_Array_operator_eq_Array>`
Compares the left operand **Array** against the ``right`` **Array**. Returns ``true`` if the sizes and contents of the arrays are equal, ``false`` otherwise.
.. rst-class:: classref-item-separator
----
.. _class_Array_operator_gt_Array:
.. rst-class:: classref-operator
:ref:`bool<class_bool>` **operator >**\ (\ right\: :ref:`Array<class_Array>`\ ) :ref:`🔗<class_Array_operator_gt_Array>`
Compares the elements of both arrays in order, starting from index ``0`` and ending on the last index in common between both arrays. For each pair of elements, returns ``true`` if this array's element is greater than ``right``'s, ``false`` if this element is less. Otherwise, continues to the next pair.
If all searched elements are equal, returns ``true`` if this array's size is greater than ``right``'s, otherwise returns ``false``.
.. rst-class:: classref-item-separator
----
.. _class_Array_operator_gte_Array:
.. rst-class:: classref-operator
:ref:`bool<class_bool>` **operator >=**\ (\ right\: :ref:`Array<class_Array>`\ ) :ref:`🔗<class_Array_operator_gte_Array>`
Compares the elements of both arrays in order, starting from index ``0`` and ending on the last index in common between both arrays. For each pair of elements, returns ``true`` if this array's element is greater than ``right``'s, ``false`` if this element is less. Otherwise, continues to the next pair.
If all searched elements are equal, returns ``true`` if this array's size is greater or equal to ``right``'s, otherwise returns ``false``.
.. rst-class:: classref-item-separator
----
.. _class_Array_operator_idx_int:
.. rst-class:: classref-operator
:ref:`Variant<class_Variant>` **operator []**\ (\ index\: :ref:`int<class_int>`\ ) :ref:`🔗<class_Array_operator_idx_int>`
Returns the :ref:`Variant<class_Variant>` element at the specified ``index``. Arrays start at index 0. If ``index`` is greater or equal to ``0``, the element is fetched starting from the beginning of the array. If ``index`` is a negative value, the element is fetched starting from the end. Accessing an array out-of-bounds will cause a run-time error, pausing the project execution if run from the editor.
.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)`
.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`
.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)`
.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`
.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)`
.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)`
.. |void| replace:: :abbr:`void (No return value.)`
Reference in New Issue View Git Blame Copy Permalink