Struct PackedStringArray

pub struct PackedStringArray { /* private fields */ }

Space-efficient array of GString elements.

Check out the book for a tutorial on packed arrays.

Note that, unlike Array, this type has value semantics: each copy will be independent of the original. Under the hood, Godot uses copy-on-write, so copies are still cheap to make.

Registering properties

You can use both #[var] and #[export] with packed arrays. However, since they use copy-on-write, GDScript (for #[var]) and the editor (for #[export]) will effectively keep an independent copy of the array. Writes to the packed array from Rust are thus not reflected on the other side – you may need to replace the entire array.

See also godot/#76150 for details.

Thread safety

Usage is safe if the PackedStringArray 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).

Implementations

impl PackedStringArray

pub fn new() -> PackedStringArray

Constructs an empty array.

pub fn get(&self, index: usize) -> Option<GString>

Returns a copy of the value at the specified index, or None if out-of-bounds.

If you know the index is valid, use the [] operator (Index/IndexMut traits) instead.

pub fn contains(&self, value: impl AsArg<GString>) -> bool

Returns true if the array contains the given value.

Godot equivalent: has

pub fn count(&self, value: impl AsArg<GString>) -> usize

Returns the number of times a value is in the array.

pub fn len(&self) -> usize

Returns the number of elements in the array. Equivalent of size() in Godot.

pub fn is_empty(&self) -> bool

Returns true if the array is empty.

pub fn clear(&mut self)

Clears the array, removing all elements.

pub fn push(&mut self, value: impl AsArg<GString>)

Appends an element to the end of the array. Equivalent of append and push_back in GDScript.

pub fn insert(&mut self, index: usize, value: impl AsArg<GString>)

Inserts a new element at a given index in the array. The index must be valid, or at the end of the array (index == len()).

Note: 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.

pub fn remove(&mut self, index: usize) -> GString

Removes and returns the element at the specified index. Similar to remove_at in GDScript, but also returns the removed value.

On large arrays, this method is much slower than pop_back 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: impl AsArg<GString>)

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, size: usize)

Resizes the array to contain a different number of elements. If the new size is smaller, elements are removed from the end. If the new size is larger, new elements are set to Default::default().

pub fn extend_array(&mut self, other: &PackedStringArray)

Appends another array at the end of this array. Equivalent of append_array in GDScript.

pub fn to_vec(&self) -> Vec<GString>

Converts this array to a Rust vector, making a copy of its contents.

pub fn subarray(&self, begin: usize, end: usize) -> PackedStringArray

Returns a sub-range begin..end, as a new packed array.

This method is called slice() in Godot. The values of begin (inclusive) and end (exclusive) will be clamped to the array size.

To obtain Rust slices, see as_slice and as_mut_slice.

pub fn as_slice(&self) -> &[GString]

Returns a shared Rust slice of the array.

The resulting slice can be further subdivided or converted into raw pointers.

See also as_mut_slice to get exclusive slices, and subarray to get a sub-array as a copy.

pub fn as_mut_slice(&mut self) -> &mut [GString]

Returns an exclusive Rust slice of the array.

The resulting slice can be further subdivided or converted into raw pointers.

See also as_slice to get shared slices, and subarray to get a sub-array as a copy.

pub fn find( &self, value: impl AsArg<GString>, 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: impl AsArg<GString>, 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: impl AsArg<GString>) -> usize

Finds the index of an existing value in a sorted array using binary search.

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 (but safe) behavior.

pub fn reverse(&mut self)

Reverses the order of the elements in the array.

pub fn sort(&mut self)

Sorts the elements of the array in ascending order.

This sort is stable, since elements inside packed arrays are indistinguishable. Relative order between equal elements thus isn’t observable.

pub fn to_byte_array(&self) -> PackedByteArray

Returns a PackedByteArray with each value encoded as bytes.

Trait Implementations

impl Clone for PackedStringArray

fn clone(&self) -> PackedStringArray

Returns a duplicate of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PackedStringArray

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for PackedStringArray

fn default() -> PackedStringArray

Returns the “default value” for a type.

impl Display for PackedStringArray

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats PackedArray to match Godot’s string representation.

impl Drop for PackedStringArray

fn drop(&mut self)

Executes the destructor for this type.

impl Export for PackedStringArray

fn export_hint() -> PropertyHintInfo

The export info to use for an exported field of this type, if no other export info is specified.

impl Extend<GString> for PackedStringArray

Extends aPackedStringArray with the contents of an iterator.

Performance note

This uses the lower bound from Iterator::size_hint() to allocate memory up front. If the iterator returns more than that number of elements, it falls back to reading elements into a fixed-size buffer before adding them all efficiently as a batch.

Panics

• If the iterator’s size_hint() returns an incorrect lower bound (which is a breach of the Iterator protocol).

fn extend<I>(&mut self, iter: I)

where I: IntoIterator<Item = GString>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl From<&[GString]> for PackedStringArray

Creates a PackedStringArray from the given slice.

fn from(slice: &[GString]) -> PackedStringArray

Converts to this type from the input type.

impl<const N: usize> From<&[GString; N]> for PackedStringArray

Creates a PackedStringArray from the given Rust array.

fn from(arr: &[GString; N]) -> PackedStringArray

Converts to this type from the input type.

impl From<&Array<Variant>> for PackedStringArray

fn from(other: &Array<Variant>) -> PackedStringArray

Converts to this type from the input type.

impl From<&PackedStringArray> for Array<Variant>

fn from(other: &PackedStringArray) -> Array<Variant>

Converts to this type from the input type.

impl<const N: usize> From<[GString; N]> for PackedStringArray

Creates a PackedStringArray from the given Rust array.

fn from(arr: [GString; N]) -> PackedStringArray

Converts to this type from the input type.

impl From<Vec<GString>> for PackedStringArray

Creates a PackedStringArray from the given Rust vec.

fn from(vec: Vec<GString>) -> PackedStringArray

Converts to this type from the input type.

impl FromGodot for PackedStringArray

fn try_from_godot( via: <PackedStringArray as GodotConvert>::Via, ) -> Result<PackedStringArray, ConvertError>

Converts the Godot representation to this type, returning Err on failure.

fn from_godot(via: Self::Via) -> Self

⚠️ Converts the Godot representation to this type.

fn try_from_variant(variant: &Variant) -> Result<Self, ConvertError>

Performs the conversion from a Variant, returning Err on failure.

fn from_variant(variant: &Variant) -> Self

⚠️ Performs the conversion from a Variant.

impl FromIterator<GString> for PackedStringArray

Creates a PackedStringArray from an iterator.

Performance note

This uses the lower bound from Iterator::size_hint() to allocate memory up front. If the iterator returns more than that number of elements, it falls back to reading elements into a fixed-size buffer before adding them all efficiently as a batch.

Panics

• If the iterator’s size_hint() returns an incorrect lower bound (which is a breach of the Iterator protocol).

fn from_iter<I>(iter: I) -> PackedStringArray

where I: IntoIterator<Item = GString>,

Creates a value from an iterator.

impl GodotConvert for PackedStringArray

type Via = PackedStringArray

The type through which Self is represented in Godot.

impl Index<usize> for PackedStringArray

type Output = GString

The returned type after indexing.

fn index(&self, index: usize) -> &<PackedStringArray as Index<usize>>::Output

Performs the indexing (container[index]) operation.

impl IndexMut<usize> for PackedStringArray

fn index_mut( &mut self, index: usize, ) -> &mut <PackedStringArray as Index<usize>>::Output

Performs the mutable indexing (container[index]) operation.

impl IntoDynamicSend for PackedStringArray

type Target = ThreadConfined<PackedStringArray>

fn into_dynamic_send(self) -> <PackedStringArray as IntoDynamicSend>::Target

impl ParamType for PackedStringArray

type ArgPassing = ByRef

fn owned_to_arg(self) -> impl AsArg<Self>

👎Deprecated since 0.3.2: This method is no longer needed and will be removed in 0.4

impl PartialEq for PackedStringArray

fn eq(&self, other: &PackedStringArray) -> bool

Tests for self and other values to be equal, and is used by ==.

const fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl ToGodot for PackedStringArray

type ToVia<'v> = <PackedStringArray as GodotConvert>::Via

Target type of to_godot(), which can differ from Via for pass-by-reference types.

fn to_godot(&self) -> <PackedStringArray as ToGodot>::ToVia<'_>

Converts this type to the Godot type by reference, usually by cloning.

fn to_variant(&self) -> Variant

Converts this type to a Variant.

impl Var for PackedStringArray

fn get_property(&self) -> <PackedStringArray as GodotConvert>::Via

fn set_property(&mut self, value: <PackedStringArray as GodotConvert>::Via)

fn var_hint() -> PropertyHintInfo

Specific property hints, only override if they deviate from GodotType::property_info, e.g. for enums/newtypes.

impl ArrayElement for PackedStringArray

impl Eq for PackedStringArray

impl GodotType for PackedStringArray