Struct Array
pub struct Array<T>where
T: ArrayElement,{ /* private fields */ }
Expand description
Godot’s Array
type.
Unlike GDScript, all indices and sizes are unsigned, so negative indices are not supported.
§Typed arrays
Godot’s Array
can be either typed or untyped.
An untyped array can contain any kind of Variant
, even different types in the same array.
We represent this in Rust as VariantArray
, which is just a type alias for Array<Variant>
.
Godot also supports typed arrays, which are also just Variant
arrays under the hood, but with
runtime checks, so that no values of the wrong type are inserted into the array. We represent this as
Array<T>
, where the type T
must implement ArrayElement
. Some types like Array<T>
cannot
be stored inside arrays, as Godot prevents nesting.
If you plan to use any integer or float types apart from i64
and f64
, read
this documentation.
§Reference semantics
Like in GDScript, Array
acts as a reference type: multiple Array
instances may
refer to the same underlying array, and changes to one are visible in the other.
To create a copy that shares data with the original array, use Clone::clone()
.
If you want to create a copy of the data, use duplicate_shallow()
or duplicate_deep()
.
§Typed array example
// Create typed Array<i64> and add values.
let mut array = Array::new();
array.push(10);
array.push(20);
array.push(30);
// Or create the same array in a single expression.
let array = array![10, 20, 30];
// Access elements.
let value: i64 = array.at(0); // 10
let maybe: Option<i64> = array.get(3); // None
// Iterate over i64 elements.
for value in array.iter_shared() {
println!("{value}");
}
// Clone array (shares the reference), and overwrite elements through clone.
let mut cloned = array.clone();
cloned.set(0, 50); // [50, 20, 30]
cloned.remove(1); // [50, 30]
cloned.pop(); // [50]
// Changes will be reflected in the original array.
assert_eq!(array.len(), 1);
assert_eq!(array.front(), Some(50));
§Untyped array example
// VariantArray allows dynamic element types.
let mut array = VariantArray::new();
array.push(10.to_variant());
array.push("Hello".to_variant());
// Or equivalent, use the `varray!` macro which converts each element.
let array = varray![10, "Hello"];
// Access elements.
let value: Variant = array.at(0);
let value: i64 = array.at(0).to(); // Variant::to() extracts i64.
let maybe: Result<i64, _> = array.at(1).try_to(); // "Hello" is not i64 -> Err.
let maybe: Option<Variant> = array.get(3);
// ...and so on.
§Thread safety
Usage is safe if the Array
is used on a single thread only. Concurrent reads on
different threads are also safe, but any writes must be externally synchronized. The Rust
compiler will enforce this as long as you use only Rust threads, but it cannot protect against
concurrent modification on other threads (e.g. created through GDScript).
§Godot docs
Implementations§
§impl<T> Array<T>where
T: ArrayElement,
impl<T> Array<T>where
T: ArrayElement,
pub fn get(&self, index: usize) -> Option<T>
pub fn get(&self, index: usize) -> Option<T>
Returns the value at the specified index, or None
if the index is out-of-bounds.
If you know the index is correct, use at()
instead.
pub fn contains(&self, value: &T) -> bool
pub fn contains(&self, value: &T) -> bool
Returns true
if the array contains the given value. Equivalent of has
in GDScript.
pub fn len(&self) -> usize
pub fn len(&self) -> usize
Returns the number of elements in the array. Equivalent of size()
in Godot.
Retrieving the size incurs an FFI call. If you know the size hasn’t changed, you may consider storing it in a variable. For loops, prefer iterators.
pub fn is_empty(&self) -> bool
pub fn is_empty(&self) -> bool
Returns true
if the array is empty.
Checking for emptiness incurs an FFI call. If you know the size hasn’t changed, you may consider storing it in a variable. For loops, prefer iterators.
pub fn hash(&self) -> u32
pub fn hash(&self) -> u32
Returns a 32-bit integer hash value representing the array and its contents.
Note: Arrays with equal content will always produce identical hash values. However, the reverse is not true. Returning identical hash values does not imply the arrays are equal, because different arrays can have identical hash values due to hash collisions.
pub fn front(&self) -> Option<T>
pub fn front(&self) -> Option<T>
Returns the first element in the array, or None
if the array is empty.
pub fn back(&self) -> Option<T>
pub fn back(&self) -> Option<T>
Returns the last element in the array, or None
if the array is empty.
pub fn clear(&mut self)
pub fn clear(&mut self)
Clears the array, removing all elements.
pub fn set(&mut self, index: usize, value: impl Borrow<T>)
pub fn set(&mut self, index: usize, value: impl Borrow<T>)
Sets the value at the specified index.
value
uses Borrow<T>
to accept either by value or by reference.
§Panics
If index
is out of bounds.
pub fn push(&mut self, value: impl Borrow<T>)
pub fn push(&mut self, value: impl Borrow<T>)
Appends an element to the end of the array.
value
uses Borrow<T>
to accept either by value or by reference.
Godot equivalents: append
and push_back
pub fn push_front(&mut self, value: T)
pub fn push_front(&mut self, value: T)
Adds an element at the beginning of the array, in O(n).
On large arrays, this method is much slower than push()
, as it will move all the array’s elements.
The larger the array, the slower push_front()
will be.
pub fn pop(&mut self) -> Option<T>
pub fn pop(&mut self) -> Option<T>
Removes and returns the last element of the array. Returns None
if the array is empty.
Godot equivalent: pop_back
pub fn pop_front(&mut self) -> Option<T>
pub fn pop_front(&mut self) -> Option<T>
Removes and returns the first element of the array, in O(n). Returns None
if the array is empty.
Note: On large arrays, this method is much slower than pop()
as it will move all the
array’s elements. The larger the array, the slower pop_front()
will be.
pub fn insert(&mut self, index: usize, value: T)
pub fn insert(&mut self, index: usize, value: T)
⚠️ Inserts a new element before the index. The index must be valid or the end of the array (index == len()
).
On large arrays, this method is much slower than push()
, as it will move all the array’s elements after the inserted element.
The larger the array, the slower insert()
will be.
§Panics
If index > len()
.
pub fn remove(&mut self, index: usize) -> T
pub fn remove(&mut self, index: usize) -> T
⚠️ Removes and returns the element at the specified index. Equivalent of pop_at
in GDScript.
On large arrays, this method is much slower than pop()
as it will move all the array’s
elements after the removed element. The larger the array, the slower remove()
will be.
§Panics
If index
is out of bounds.
pub fn fill(&mut self, value: &T)
pub fn fill(&mut self, value: &T)
Assigns the given value to all elements in the array. This can be used together with
resize
to create an array with a given size and initialized elements.
pub fn resize(&mut self, new_size: usize, value: &T)
pub fn resize(&mut self, new_size: usize, value: &T)
Resizes the array to contain a different number of elements.
If the new size is smaller than the current size, then it removes elements from the end. If the new size is bigger than the current one
then the new elements are set to value
.
If you know that the new size is smaller, then consider using shrink
instead.
pub fn shrink(&mut self, new_size: usize) -> bool
pub fn shrink(&mut self, new_size: usize) -> bool
Shrinks the array down to new_size
.
This will only change the size of the array if new_size
is smaller than the current size. Returns true
if the array was shrunk.
If you want to increase the size of the array, use resize
instead.
pub fn extend_array(&mut self, other: &Array<T>)
pub fn extend_array(&mut self, other: &Array<T>)
Appends another array at the end of this array. Equivalent of append_array
in GDScript.
pub fn duplicate_shallow(&self) -> Array<T>
pub fn duplicate_shallow(&self) -> Array<T>
Returns a shallow copy of the array. All array elements are copied, but any reference types
(such as Array
, Dictionary
and Object
) will still refer to the same value.
To create a deep copy, use duplicate_deep()
instead.
To create a new reference to the same array data, use clone()
.
pub fn duplicate_deep(&self) -> Array<T>
pub fn duplicate_deep(&self) -> Array<T>
Returns a deep copy of the array. All nested arrays and dictionaries are duplicated and
will not be shared with the original array. Note that any Object
-derived elements will
still be shallow copied.
To create a shallow copy, use duplicate_shallow()
instead.
To create a new reference to the same array data, use clone()
.
pub fn subarray_shallow(
&self,
begin: usize,
end: usize,
step: Option<isize>,
) -> Array<T>
pub fn subarray_shallow( &self, begin: usize, end: usize, step: Option<isize>, ) -> Array<T>
Returns a sub-range begin..end
, as a new array.
The values of begin
(inclusive) and end
(exclusive) will be clamped to the array size.
If specified, step
is the relative index between source elements. It can be negative,
in which case begin
must be higher than end
. For example,
Array::from(&[0, 1, 2, 3, 4, 5]).slice(5, 1, -2)
returns [5, 3]
.
Array elements are copied to the slice, but any reference types (such as Array
,
Dictionary
and Object
) will still refer to the same value. To create a deep copy, use
subarray_deep()
instead.
pub fn subarray_deep(
&self,
begin: usize,
end: usize,
step: Option<isize>,
) -> Array<T>
pub fn subarray_deep( &self, begin: usize, end: usize, step: Option<isize>, ) -> Array<T>
Returns a sub-range begin..end
, as a new Array
.
The values of begin
(inclusive) and end
(exclusive) will be clamped to the array size.
If specified, step
is the relative index between source elements. It can be negative,
in which case begin
must be higher than end
. For example,
Array::from(&[0, 1, 2, 3, 4, 5]).slice(5, 1, -2)
returns [5, 3]
.
All nested arrays and dictionaries are duplicated and will not be shared with the original
array. Note that any Object
-derived elements will still be shallow copied. To create a
shallow copy, use subarray_shallow()
instead.
Returns an iterator over the elements of the Array
. Note that this takes the array
by reference but returns its elements by value, since they are internally converted from
Variant
.
Notice that it’s possible to modify the Array
through another reference while
iterating over it. This will not result in unsoundness or crashes, but will cause the
iterator to behave in an unspecified way.
pub fn min(&self) -> Option<T>
pub fn min(&self) -> Option<T>
Returns the minimum value contained in the array if all elements are of comparable types.
If the elements can’t be compared or the array is empty, None
is returned.
pub fn max(&self) -> Option<T>
pub fn max(&self) -> Option<T>
Returns the maximum value contained in the array if all elements are of comparable types.
If the elements can’t be compared or the array is empty, None
is returned.
pub fn pick_random(&self) -> Option<T>
pub fn pick_random(&self) -> Option<T>
Returns a random element from the array, or None
if it is empty.
pub fn find(&self, value: &T, from: Option<usize>) -> Option<usize>
pub fn find(&self, value: &T, from: Option<usize>) -> Option<usize>
Searches the array for the first occurrence of a value and returns its index, or None
if
not found. Starts searching at index from
; pass None
to search the entire array.
pub fn rfind(&self, value: &T, from: Option<usize>) -> Option<usize>
pub fn rfind(&self, value: &T, from: Option<usize>) -> Option<usize>
Searches the array backwards for the last occurrence of a value and returns its index, or
None
if not found. Starts searching at index from
; pass None
to search the entire
array.
pub fn bsearch(&self, value: &T) -> usize
pub fn bsearch(&self, value: &T) -> usize
Finds the index of an existing value in a sorted array using binary search.
Equivalent of bsearch
in GDScript.
If the value is not present in the array, returns the insertion index that would maintain sorting order.
Calling bsearch
on an unsorted array results in unspecified behavior.
pub fn bsearch_custom(&self, value: &T, func: Callable) -> usize
pub fn bsearch_custom(&self, value: &T, func: Callable) -> usize
Finds the index of an existing value in a sorted array using binary search.
Equivalent of bsearch_custom
in GDScript.
Takes a Callable
and uses the return value of it to perform binary search.
If the value is not present in the array, returns the insertion index that would maintain sorting order.
Calling bsearch_custom
on an unsorted array results in unspecified behavior.
Consider using sort_custom()
to ensure the sorting order is compatible with
your callable’s ordering
pub fn reverse(&mut self)
pub fn reverse(&mut self)
Reverses the order of the elements in the array.
pub fn sort_unstable(&mut self)
pub fn sort_unstable(&mut self)
Sorts the array.
Note: The sorting algorithm used is not stable.
This means that values considered equal may have their order changed when using sort_unstable
.
pub fn sort_unstable_custom(&mut self, func: Callable)
pub fn sort_unstable_custom(&mut self, func: Callable)
Sorts the array.
Uses the provided Callable
to determine ordering.
Note: The sorting algorithm used is not stable.
This means that values considered equal may have their order changed when using sort_unstable_custom
.
pub fn shuffle(&mut self)
pub fn shuffle(&mut self)
Shuffles the array such that the items will have a random order. This method uses the
global random number generator common to methods such as randi
. Call randomize
to
ensure that a new seed will be used each time if you want non-reproducible shuffling.
Trait Implementations§
§impl ArrayElement for Array<Variant>
impl ArrayElement for Array<Variant>
fn debug_validate_elements(_array: &Array<Self>) -> Result<(), ConvertError>
§impl<T> Clone for Array<T>where
T: ArrayElement,
impl<T> Clone for Array<T>where
T: ArrayElement,
Creates a new reference to the data in this array. Changes to the original array will be reflected in the copy and vice versa.
To create a (mostly) independent copy instead, see Array::duplicate_shallow()
and
Array::duplicate_deep()
.
§impl<T> Debug for Array<T>where
T: ArrayElement,
impl<T> Debug for Array<T>where
T: ArrayElement,
§impl<T> Default for Array<T>where
T: ArrayElement,
impl<T> Default for Array<T>where
T: ArrayElement,
§impl<T> Display for Array<T>where
T: ArrayElement + Display,
impl<T> Display for Array<T>where
T: ArrayElement + Display,
§impl<T> Drop for Array<T>where
T: ArrayElement,
impl<T> Drop for Array<T>where
T: ArrayElement,
§impl<T> Export for Array<T>where
T: ArrayElement + Export,
impl<T> Export for Array<T>where
T: ArrayElement + Export,
§fn export_hint() -> PropertyHintInfo
fn export_hint() -> PropertyHintInfo
§fn as_node_class() -> Option<ClassName>
fn as_node_class() -> Option<ClassName>
§impl<T> Extend<T> for Array<T>where
T: ArrayElement + ToGodot,
impl<T> Extend<T> for Array<T>where
T: ArrayElement + ToGodot,
Extends a Array
with the contents of an iterator.
§fn extend<I>(&mut self, iter: I)where
I: IntoIterator<Item = T>,
fn extend<I>(&mut self, iter: I)where
I: IntoIterator<Item = T>,
Source§fn extend_one(&mut self, item: A)
fn extend_one(&mut self, item: A)
extend_one
)Source§fn extend_reserve(&mut self, additional: usize)
fn extend_reserve(&mut self, additional: usize)
extend_one
)§impl<T> From<&[T]> for Array<T>where
T: ArrayElement + ToGodot,
impl<T> From<&[T]> for Array<T>where
T: ArrayElement + ToGodot,
Creates a Array
from the given slice.
§impl<T, const N: usize> From<&[T; N]> for Array<T>where
T: ArrayElement + ToGodot,
impl<T, const N: usize> From<&[T; N]> for Array<T>where
T: ArrayElement + ToGodot,
Creates a Array
from the given Rust array.
§impl From<&Array<Variant>> for PackedByteArray
impl From<&Array<Variant>> for PackedByteArray
§fn from(other: &Array<Variant>) -> PackedByteArray
fn from(other: &Array<Variant>) -> PackedByteArray
§impl From<&Array<Variant>> for PackedColorArray
impl From<&Array<Variant>> for PackedColorArray
§fn from(other: &Array<Variant>) -> PackedColorArray
fn from(other: &Array<Variant>) -> PackedColorArray
§impl From<&Array<Variant>> for PackedFloat32Array
impl From<&Array<Variant>> for PackedFloat32Array
§fn from(other: &Array<Variant>) -> PackedFloat32Array
fn from(other: &Array<Variant>) -> PackedFloat32Array
§impl From<&Array<Variant>> for PackedFloat64Array
impl From<&Array<Variant>> for PackedFloat64Array
§fn from(other: &Array<Variant>) -> PackedFloat64Array
fn from(other: &Array<Variant>) -> PackedFloat64Array
§impl From<&Array<Variant>> for PackedInt32Array
impl From<&Array<Variant>> for PackedInt32Array
§fn from(other: &Array<Variant>) -> PackedInt32Array
fn from(other: &Array<Variant>) -> PackedInt32Array
§impl From<&Array<Variant>> for PackedInt64Array
impl From<&Array<Variant>> for PackedInt64Array
§fn from(other: &Array<Variant>) -> PackedInt64Array
fn from(other: &Array<Variant>) -> PackedInt64Array
§impl From<&Array<Variant>> for PackedStringArray
impl From<&Array<Variant>> for PackedStringArray
§fn from(other: &Array<Variant>) -> PackedStringArray
fn from(other: &Array<Variant>) -> PackedStringArray
§impl From<&Array<Variant>> for PackedVector2Array
impl From<&Array<Variant>> for PackedVector2Array
§fn from(other: &Array<Variant>) -> PackedVector2Array
fn from(other: &Array<Variant>) -> PackedVector2Array
§impl From<&Array<Variant>> for PackedVector3Array
impl From<&Array<Variant>> for PackedVector3Array
§fn from(other: &Array<Variant>) -> PackedVector3Array
fn from(other: &Array<Variant>) -> PackedVector3Array
§impl From<&Array<Variant>> for PackedVector4Array
impl From<&Array<Variant>> for PackedVector4Array
§fn from(other: &Array<Variant>) -> PackedVector4Array
fn from(other: &Array<Variant>) -> PackedVector4Array
§impl From<&PackedByteArray> for Array<Variant>
impl From<&PackedByteArray> for Array<Variant>
§fn from(other: &PackedByteArray) -> Array<Variant>
fn from(other: &PackedByteArray) -> Array<Variant>
§impl From<&PackedColorArray> for Array<Variant>
impl From<&PackedColorArray> for Array<Variant>
§fn from(other: &PackedColorArray) -> Array<Variant>
fn from(other: &PackedColorArray) -> Array<Variant>
§impl From<&PackedFloat32Array> for Array<Variant>
impl From<&PackedFloat32Array> for Array<Variant>
§fn from(other: &PackedFloat32Array) -> Array<Variant>
fn from(other: &PackedFloat32Array) -> Array<Variant>
§impl From<&PackedFloat64Array> for Array<Variant>
impl From<&PackedFloat64Array> for Array<Variant>
§fn from(other: &PackedFloat64Array) -> Array<Variant>
fn from(other: &PackedFloat64Array) -> Array<Variant>
§impl From<&PackedInt32Array> for Array<Variant>
impl From<&PackedInt32Array> for Array<Variant>
§fn from(other: &PackedInt32Array) -> Array<Variant>
fn from(other: &PackedInt32Array) -> Array<Variant>
§impl From<&PackedInt64Array> for Array<Variant>
impl From<&PackedInt64Array> for Array<Variant>
§fn from(other: &PackedInt64Array) -> Array<Variant>
fn from(other: &PackedInt64Array) -> Array<Variant>
§impl From<&PackedStringArray> for Array<Variant>
impl From<&PackedStringArray> for Array<Variant>
§fn from(other: &PackedStringArray) -> Array<Variant>
fn from(other: &PackedStringArray) -> Array<Variant>
§impl From<&PackedVector2Array> for Array<Variant>
impl From<&PackedVector2Array> for Array<Variant>
§fn from(other: &PackedVector2Array) -> Array<Variant>
fn from(other: &PackedVector2Array) -> Array<Variant>
§impl From<&PackedVector3Array> for Array<Variant>
impl From<&PackedVector3Array> for Array<Variant>
§fn from(other: &PackedVector3Array) -> Array<Variant>
fn from(other: &PackedVector3Array) -> Array<Variant>
§impl From<&PackedVector4Array> for Array<Variant>
impl From<&PackedVector4Array> for Array<Variant>
§fn from(other: &PackedVector4Array) -> Array<Variant>
fn from(other: &PackedVector4Array) -> Array<Variant>
§impl<T> FromGodot for Array<T>where
T: ArrayElement,
impl<T> FromGodot for Array<T>where
T: ArrayElement,
§fn try_from_godot(
via: <Array<T> as GodotConvert>::Via,
) -> Result<Array<T>, ConvertError>
fn try_from_godot( via: <Array<T> as GodotConvert>::Via, ) -> Result<Array<T>, ConvertError>
Err
on failure.§fn from_godot(via: Self::Via) -> Self
fn from_godot(via: Self::Via) -> Self
§fn try_from_variant(variant: &Variant) -> Result<Self, ConvertError>
fn try_from_variant(variant: &Variant) -> Result<Self, ConvertError>
Variant
, returning Err
on failure.§fn from_variant(variant: &Variant) -> Self
fn from_variant(variant: &Variant) -> Self
§impl<T> FromIterator<T> for Array<T>where
T: ArrayElement + ToGodot,
impl<T> FromIterator<T> for Array<T>where
T: ArrayElement + ToGodot,
Creates a Array
from an iterator.
§fn from_iter<I>(iter: I) -> Array<T>where
I: IntoIterator<Item = T>,
fn from_iter<I>(iter: I) -> Array<T>where
I: IntoIterator<Item = T>,
§impl<T> GodotConvert for Array<T>where
T: ArrayElement,
impl<T> GodotConvert for Array<T>where
T: ArrayElement,
§impl<T> PartialEq for Array<T>where
T: ArrayElement,
impl<T> PartialEq for Array<T>where
T: ArrayElement,
§impl<T> PartialOrd for Array<T>where
T: ArrayElement,
impl<T> PartialOrd for Array<T>where
T: ArrayElement,
§impl<T> ToGodot for Array<T>where
T: ArrayElement,
impl<T> ToGodot for Array<T>where
T: ArrayElement,
§type ToVia<'v> = <Array<T> as GodotConvert>::Via
type ToVia<'v> = <Array<T> as GodotConvert>::Via
to_godot()
, which differs from Via
for pass-by-reference types.§fn to_godot(&self) -> <Array<T> as ToGodot>::ToVia<'_>
fn to_godot(&self) -> <Array<T> as ToGodot>::ToVia<'_>
§fn to_variant(&self) -> Variant
fn to_variant(&self) -> Variant
§impl<T> Var for Array<T>where
T: ArrayElement,
impl<T> Var for Array<T>where
T: ArrayElement,
fn get_property(&self) -> <Array<T> as GodotConvert>::Via
fn set_property(&mut self, value: <Array<T> as GodotConvert>::Via)
§fn var_hint() -> PropertyHintInfo
fn var_hint() -> PropertyHintInfo
GodotType::property_info
, e.g. for enums/newtypes.impl<T> GodotType for Array<T>where
T: ArrayElement,
Auto Trait Implementations§
impl<T> Freeze for Array<T>
impl<T> RefUnwindSafe for Array<T>where
T: RefUnwindSafe,
impl<T> !Send for Array<T>
impl<T> !Sync for Array<T>
impl<T> Unpin for Array<T>where
T: Unpin,
impl<T> UnwindSafe for Array<T>where
T: UnwindSafe,
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)