summaryrefslogtreecommitdiff
path: root/doc/classes/Array.xml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/classes/Array.xml')
-rw-r--r--doc/classes/Array.xml236
1 files changed, 192 insertions, 44 deletions
diff --git a/doc/classes/Array.xml b/doc/classes/Array.xml
index b79b24e0bc..6a9eb89602 100644
--- a/doc/classes/Array.xml
+++ b/doc/classes/Array.xml
@@ -6,62 +6,89 @@
<description>
Generic array which can contain several elements of any type, accessible by a numerical index starting at 0. Negative indices can be used to count from the back, like in Python (-1 is the last element, -2 the second to last, etc.).
[b]Example:[/b]
- [codeblock]
+ [codeblocks]
+ [gdscript]
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.
- [/codeblock]
+ [/gdscript]
+ [csharp]
+ 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.
+ [/csharp]
+ [/codeblocks]
Arrays can be concatenated using the [code]+[/code] operator:
- [codeblock]
+ [codeblocks]
+ [gdscript]
var array1 = ["One", 2]
var array2 = [3, "Four"]
print(array1 + array2) # ["One", 2, 3, "Four"]
- [/codeblock]
+ [/gdscript]
+ [csharp]
+ // 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]
+ [/csharp]
+ [/codeblocks]
+ [b]Note:[/b] Concatenating with the [code]+=[/code] operator will create a new array, which has a cost. If you want to append another array to an existing array, [method append_array] is more efficient.
[b]Note:[/b] Arrays are always passed by reference. To get a copy of an array which can be modified independently of the original array, use [method duplicate].
+ [b]Note:[/b] When declaring an array with [code]const[/code], the array itself can still be mutated by defining the values at individual indices or pushing/removing elements. Using [code]const[/code] will only prevent assigning the constant with another value after it was initialized.
</description>
<tutorials>
</tutorials>
<methods>
- <method name="Array">
+ <method name="Array" qualifiers="constructor">
<return type="Array">
</return>
- <argument index="0" name="from" type="PackedColorArray">
+ <description>
+ Constructs an empty [Array].
+ </description>
+ </method>
+ <method name="Array" qualifiers="constructor">
+ <return type="Array">
+ </return>
+ <argument index="0" name="from" type="Array">
</argument>
<description>
- Constructs an array from a [PackedColorArray].
+ Constructs an [Array] as a copy of the given [Array].
</description>
</method>
- <method name="Array">
+ <method name="Array" qualifiers="constructor">
<return type="Array">
</return>
- <argument index="0" name="from" type="PackedVector3Array">
+ <argument index="0" name="from" type="PackedByteArray">
</argument>
<description>
- Constructs an array from a [PackedVector3Array].
+ Constructs an array from a [PackedByteArray].
</description>
</method>
- <method name="Array">
+ <method name="Array" qualifiers="constructor">
<return type="Array">
</return>
- <argument index="0" name="from" type="PackedVector2Array">
+ <argument index="0" name="from" type="PackedColorArray">
</argument>
<description>
- Constructs an array from a [PackedVector2Array].
+ Constructs an array from a [PackedColorArray].
</description>
</method>
- <method name="Array">
+ <method name="Array" qualifiers="constructor">
<return type="Array">
</return>
- <argument index="0" name="from" type="PackedStringArray">
+ <argument index="0" name="from" type="PackedFloat32Array">
</argument>
<description>
- Constructs an array from a [PackedStringArray].
+ Constructs an array from a [PackedFloat32Array].
</description>
</method>
- <method name="Array">
+ <method name="Array" qualifiers="constructor">
<return type="Array">
</return>
<argument index="0" name="from" type="PackedFloat64Array">
@@ -70,16 +97,16 @@
Constructs an array from a [PackedFloat64Array].
</description>
</method>
- <method name="Array">
+ <method name="Array" qualifiers="constructor">
<return type="Array">
</return>
- <argument index="0" name="from" type="PackedFloat32Array">
+ <argument index="0" name="from" type="PackedInt32Array">
</argument>
<description>
- Constructs an array from a [PackedFloat32Array].
+ Constructs an array from a [PackedInt32Array].
</description>
</method>
- <method name="Array">
+ <method name="Array" qualifiers="constructor">
<return type="Array">
</return>
<argument index="0" name="from" type="PackedInt64Array">
@@ -88,22 +115,31 @@
Constructs an array from a [PackedInt64Array].
</description>
</method>
- <method name="Array">
+ <method name="Array" qualifiers="constructor">
<return type="Array">
</return>
- <argument index="0" name="from" type="PackedInt32Array">
+ <argument index="0" name="from" type="PackedStringArray">
</argument>
<description>
- Constructs an array from a [PackedInt32Array].
+ Constructs an array from a [PackedStringArray].
</description>
</method>
- <method name="Array">
+ <method name="Array" qualifiers="constructor">
<return type="Array">
</return>
- <argument index="0" name="from" type="PackedByteArray">
+ <argument index="0" name="from" type="PackedVector2Array">
</argument>
<description>
- Constructs an array from a [PackedByteArray].
+ Constructs an array from a [PackedVector2Array].
+ </description>
+ </method>
+ <method name="Array" qualifiers="constructor">
+ <return type="Array">
+ </return>
+ <argument index="0" name="from" type="PackedVector3Array">
+ </argument>
+ <description>
+ Constructs an array from a [PackedVector3Array].
</description>
</method>
<method name="append">
@@ -115,11 +151,27 @@
Appends an element at the end of the array (alias of [method push_back]).
</description>
</method>
+ <method name="append_array">
+ <return type="void">
+ </return>
+ <argument index="0" name="array" type="Array">
+ </argument>
+ <description>
+ Appends another array at the end of this array.
+ [codeblock]
+ var array1 = [1, 2, 3]
+ var array2 = [4, 5, 6]
+ array1.append_array(array2)
+ print(array1) # Prints [1, 2, 3, 4, 5, 6].
+ [/codeblock]
+ </description>
+ </method>
<method name="back">
<return type="Variant">
</return>
<description>
- Returns the last element of the array, or [code]null[/code] if the array is empty.
+ Returns the last element of the array. Prints an error and returns [code]null[/code] if the array is empty.
+ [b]Note:[/b] Calling this function is not the same as writing [code]array[-1][/code]. If the array is empty, accessing by index will pause project execution when running from the editor.
</description>
</method>
<method name="bsearch">
@@ -141,7 +193,7 @@
</argument>
<argument index="1" name="obj" type="Object">
</argument>
- <argument index="2" name="func" type="String">
+ <argument index="2" name="func" type="StringName">
</argument>
<argument index="3" name="before" type="bool" default="true">
</argument>
@@ -216,7 +268,8 @@
<return type="Variant">
</return>
<description>
- Returns the first element of the array, or [code]null[/code] if the array is empty.
+ Returns the first element of the array. Prints an error and returns [code]null[/code] if the array is empty.
+ [b]Note:[/b] Calling this function is not the same as writing [code]array[0][/code]. If the array is empty, accessing by index will pause project execution when running from the editor.
</description>
</method>
<method name="has">
@@ -226,18 +279,39 @@
</argument>
<description>
Returns [code]true[/code] if the array contains the given value.
- [codeblock]
+ [codeblocks]
+ [gdscript]
print(["inside", 7].has("inside")) # True
print(["inside", 7].has("outside")) # False
print(["inside", 7].has(7)) # True
print(["inside", 7].has("7")) # False
- [/codeblock]
+ [/gdscript]
+ [csharp]
+ var arr = new Godot.Collections.Array{"inside", 7};
+ // has is renamed to Contains
+ GD.Print(arr.Contains("inside")); // True
+ GD.Print(arr.Contains("outside")); // False
+ GD.Print(arr.Contains(7)); // True
+ GD.Print(arr.Contains("7")); // False
+ [/csharp]
+ [/codeblocks]
+
[b]Note:[/b] This is equivalent to using the [code]in[/code] operator as follows:
- [codeblock]
+ [codeblocks]
+ [gdscript]
# Will evaluate to `true`.
if 2 in [2, 4, 6, 8]:
- pass
- [/codeblock]
+ print("Containes!")
+ [/gdscript]
+ [csharp]
+ // As there is no "in" keyword in C#, you have to use Contains
+ var array = new Godot.Collections.Array{2, 4, 6, 8};
+ if (array.Contains(2))
+ {
+ GD.Print("Containes!");
+ }
+ [/csharp]
+ [/codeblocks]
</description>
</method>
<method name="hash">
@@ -279,18 +353,82 @@
Returns the minimum value contained in the array if all elements are of comparable types. If the elements can't be compared, [code]null[/code] is returned.
</description>
</method>
+ <method name="operator !=" qualifiers="operator">
+ <return type="bool">
+ </return>
+ <argument index="0" name="right" type="Array">
+ </argument>
+ <description>
+ </description>
+ </method>
+ <method name="operator +" qualifiers="operator">
+ <return type="Array">
+ </return>
+ <argument index="0" name="right" type="Array">
+ </argument>
+ <description>
+ </description>
+ </method>
+ <method name="operator &lt;" qualifiers="operator">
+ <return type="bool">
+ </return>
+ <argument index="0" name="right" type="Array">
+ </argument>
+ <description>
+ </description>
+ </method>
+ <method name="operator &lt;=" qualifiers="operator">
+ <return type="bool">
+ </return>
+ <argument index="0" name="right" type="Array">
+ </argument>
+ <description>
+ </description>
+ </method>
+ <method name="operator ==" qualifiers="operator">
+ <return type="bool">
+ </return>
+ <argument index="0" name="right" type="Array">
+ </argument>
+ <description>
+ </description>
+ </method>
+ <method name="operator &gt;" qualifiers="operator">
+ <return type="bool">
+ </return>
+ <argument index="0" name="right" type="Array">
+ </argument>
+ <description>
+ </description>
+ </method>
+ <method name="operator &gt;=" qualifiers="operator">
+ <return type="bool">
+ </return>
+ <argument index="0" name="right" type="Array">
+ </argument>
+ <description>
+ </description>
+ </method>
+ <method name="operator []" qualifiers="operator">
+ <return type="void">
+ </return>
+ <argument index="0" name="index" type="int">
+ </argument>
+ <description>
+ </description>
+ </method>
<method name="pop_back">
<return type="Variant">
</return>
<description>
- Removes and returns the last element of the array. Returns [code]null[/code] if the array is empty.
+ Removes and returns the last element of the array. Returns [code]null[/code] if the array is empty, without printing an error message.
</description>
</method>
<method name="pop_front">
<return type="Variant">
</return>
<description>
- Removes and returns the first element of the array. Returns [code]null[/code] if the array is empty.
+ Removes and returns the first element of the array. Returns [code]null[/code] if the array is empty, without printing an error message.
</description>
</method>
<method name="push_back">
@@ -317,11 +455,11 @@
<argument index="0" name="position" type="int">
</argument>
<description>
- Removes an element from the array by index.
+ Removes an element from the array by index. If the index does not exist in the array, nothing happens.
</description>
</method>
<method name="resize">
- <return type="void">
+ <return type="int">
</return>
<argument index="0" name="size" type="int">
</argument>
@@ -375,11 +513,16 @@
<description>
Sorts the array.
[b]Note:[/b] Strings are sorted in alphabetical order (as opposed to natural order). This may lead to unexpected behavior when sorting an array of strings ending with a sequence of numbers. Consider the following example:
- [codeblock]
+ [codeblocks]
+ [gdscript]
var strings = ["string1", "string2", "string10", "string11"]
strings.sort()
print(strings) # Prints [string1, string10, string11, string2]
- [/codeblock]
+ [/gdscript]
+ [csharp]
+ // There is no sort support for Godot.Collections.Array
+ [/csharp]
+ [/codeblocks]
</description>
</method>
<method name="sort_custom">
@@ -387,12 +530,13 @@
</return>
<argument index="0" name="obj" type="Object">
</argument>
- <argument index="1" name="func" type="String">
+ <argument index="1" name="func" type="StringName">
</argument>
<description>
Sorts the array using a custom method. The arguments are an object that holds the method and the name of such method. The custom method receives two arguments (a pair of elements from the array) and must return either [code]true[/code] or [code]false[/code].
[b]Note:[/b] you cannot randomize the return value as the heapsort algorithm expects a deterministic result. Doing so will result in unexpected behavior.
- [codeblock]
+ [codeblocks]
+ [gdscript]
class MyCustomSorter:
static func sort_ascending(a, b):
if a[0] &lt; b[0]:
@@ -402,7 +546,11 @@
var my_items = [[5, "Potato"], [9, "Rice"], [4, "Tomato"]]
my_items.sort_custom(MyCustomSorter, "sort_ascending")
print(my_items) # Prints [[4, Tomato], [5, Potato], [9, Rice]].
- [/codeblock]
+ [/gdscript]
+ [csharp]
+ // There is no custom sort support for Godot.Collections.Array
+ [/csharp]
+ [/codeblocks]
</description>
</method>
</methods>
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-16 16:54:03 +0000