Struct gdnative::core_types::PoolArray

pub struct PoolArray<T>where
    T: PoolElement,{ /* private fields */ }

A reference-counted CoW typed vector using Godot’s pool allocator, generic over possible element types.

PoolArray unifies all the different Pool*Array types exported by Godot. It can be used in exported Rust methods as parameter and return types, as well as in exported properties. However, it is limited to the element types, for which a Pool*Array exists in GDScript, i.e. it cannot contain user-defined types. If you need other types, look into VariantArray or directly use Vec<T> for type safety.

This type is CoW (copy-on-write). The Clone implementation of this type creates a new reference without copying the contents.

If you need to read elements, e.g. for iteration or conversion to another collection, the read() method provides a view that dereferences to &[T]. Analogously, write() provides a writable view that dereferences to &mut [T].

For element mutations, it’s usually recommended to do process them in batch using write() or the append() methods, as opposed to push() or set(), because the latter ones trigger CoW behavior each time they are called.

Implementations

impl<T> PoolArray<T>where
    T: PoolElement,

pub fn new() -> PoolArray<T>

Creates an empty array.

pub fn from_variant_array(array: &VariantArray<Shared>) -> PoolArray<T>

Creates from a VariantArray by making a best effort to convert each variant.

pub fn from_vec(src: Vec<T, Global>) -> PoolArray<T>

Creates a PoolArray moving elements from src.

If your source type isn’t precisely a Vec<T>, keep in mind that PoolElement implements the FromIterator trait, which allows it to be constructed from iterators, typically through collect().

For example:

// Int32Array is a type alias for PoolArray<i32>
use gdnative::core_types::Int32Array;

// Collect from range
let arr = (0..4).collect::<Int32Array>();

// Type conversion
let vec: Vec<u32> = vec![1, 1, 2, 3, 5]; // note: unsigned
let arr = vec.iter().map(|&e| e as i32).collect::<Int32Array>();

pub fn to_vec(&self) -> Vec<T, Global>where
    T: Clone,

Copies all elements to a Vec, leaving this instance untouched.

Equivalent to self.read().to_vec(). Only use this if your destination type is precisely a Vec<T>. Otherwise, call read() which can be used as a slice.

pub fn push(&mut self, val: T)

Appends an element to the end of the array.

Calling push() triggers copy-on-write behavior. To insert a large number of elements, consider using append(), resize() or write().

pub fn push_ref(&mut self, val: &T)

Appends an element to the end of the array by reference.

Calling push_ref() triggers copy-on-write behavior. To insert a large number of elements, consider using append(), resize() or write().

pub fn append(&mut self, src: &PoolArray<T>)

Copies and appends all values in src to the end of the array.

pub fn append_vec(&mut self, src: &mut Vec<T, Global>)

Moves all the elements from src into self, leaving src empty.

Panics

If the resulting length would not fit in i32.

pub fn insert(&mut self, offset: i32, val: T) -> bool

Inserts an element at the given offset and returns true if successful.

pub fn insert_ref(&mut self, offset: i32, val: &T) -> bool

Inserts an element by reference at the given offset and returns true if successful.

pub fn invert(&mut self)

Inverts the order of the elements in the array.

pub fn remove(&mut self, idx: i32)

Removes an element at the given offset.

pub fn resize(&mut self, size: i32)

Changes the size of the array, possibly removing elements or pushing default values.

pub fn get(&self, idx: i32) -> T

Returns a copy of the element at the given offset.

pub fn set(&mut self, idx: i32, val: T)

Sets the value of the element at the given offset.

pub fn set_ref(&mut self, idx: i32, val: &T)

Sets the value of the element at the given offset by reference.

pub fn len(&self) -> i32

Returns the number of elements in the array.

pub fn is_empty(&self) -> bool

Returns true if the container is empty.

pub fn read(&self) -> Aligned<ReadGuard<'_, T>>

Returns a scoped read-only view into this array.

The returned read guard implements Deref with target type [T], i.e. can be dereferenced to &[T]. This means all non-mutating (&self) slice methods can be used, see here.

pub fn write(&mut self) -> Aligned<WriteGuard<'_, T>>

Returns a scoped read-write view into this array. This triggers CoW once per lock, instead of once each mutation.

The returned write guard implements DerefMut with target type [T], i.e. can be dereferenced to &mut [T]. This means all mutating and read-only slice methods can be used, see here.

impl<T> PoolArray<T>where
    T: PoolElement + Copy,

pub fn from_slice(src: &[T]) -> PoolArray<T>

Creates a new PoolArray by copying from src.

Equivalent to a new object created with new(), followed by a subsequent append_slice().

Panics

If the length of src does not fit in i32.

pub fn append_slice(&mut self, src: &[T])

Copies and appends all values in src to the end of the array.

Panics

If the resulting length would not fit in i32.

Trait Implementations

impl<T> Clone for PoolArray<T>where
    T: PoolElement,

fn clone(&self) -> PoolArray<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl CoerceFromVariant for PoolArray<Color>

fn coerce_from_variant(v: &Variant) -> PoolArray<Color>

impl CoerceFromVariant for PoolArray<GodotString>

fn coerce_from_variant(v: &Variant) -> PoolArray<GodotString>

impl CoerceFromVariant for PoolArray<Vector2>

fn coerce_from_variant(v: &Variant) -> PoolArray<Vector2>

impl CoerceFromVariant for PoolArray<Vector3>

fn coerce_from_variant(v: &Variant) -> PoolArray<Vector3>

impl CoerceFromVariant for PoolArray<f32>

fn coerce_from_variant(v: &Variant) -> PoolArray<f32>

impl CoerceFromVariant for PoolArray<i32>

fn coerce_from_variant(v: &Variant) -> PoolArray<i32>

impl CoerceFromVariant for PoolArray<u8>

fn coerce_from_variant(v: &Variant) -> PoolArray<u8>

impl<T> Debug for PoolArray<T>where
    T: PoolElement + Debug,

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

Formats the value using the given formatter.

impl<T> Default for PoolArray<T>where
    T: PoolElement,

fn default() -> PoolArray<T>

Returns the “default value” for a type.

impl<'de, T> Deserialize<'de> for PoolArray<T>where
    T: Deserialize<'de> + PoolElement,

fn deserialize<D>(
    deserializer: D
) -> Result<PoolArray<T>, <D as Deserializer<'de>>::Error>where
    D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T> Drop for PoolArray<T>where
    T: PoolElement,

fn drop(&mut self)

Executes the destructor for this type.

impl Export for PoolArray<Color>

type Hint = NoHint

A type-specific hint type that is valid for the type being exported.

fn export_info(_hint: Option<<PoolArray<Color> as Export>::Hint>) -> ExportInfo

Returns ExportInfo given an optional typed hint.

impl Export for PoolArray<GodotString>

type Hint = NoHint

A type-specific hint type that is valid for the type being exported.

fn export_info(
    _hint: Option<<PoolArray<GodotString> as Export>::Hint>
) -> ExportInfo

Returns ExportInfo given an optional typed hint.

impl Export for PoolArray<Vector2>

type Hint = NoHint

A type-specific hint type that is valid for the type being exported.

fn export_info(
    _hint: Option<<PoolArray<Vector2> as Export>::Hint>
) -> ExportInfo

Returns ExportInfo given an optional typed hint.

impl Export for PoolArray<Vector3>

type Hint = NoHint

A type-specific hint type that is valid for the type being exported.

fn export_info(
    _hint: Option<<PoolArray<Vector3> as Export>::Hint>
) -> ExportInfo

Returns ExportInfo given an optional typed hint.

impl Export for PoolArray<f32>

type Hint = NoHint

A type-specific hint type that is valid for the type being exported.

fn export_info(_hint: Option<<PoolArray<f32> as Export>::Hint>) -> ExportInfo

Returns ExportInfo given an optional typed hint.

impl Export for PoolArray<i32>

type Hint = NoHint

A type-specific hint type that is valid for the type being exported.

fn export_info(_hint: Option<<PoolArray<i32> as Export>::Hint>) -> ExportInfo

Returns ExportInfo given an optional typed hint.

impl Export for PoolArray<u8>

type Hint = NoHint

A type-specific hint type that is valid for the type being exported.

fn export_info(_hint: Option<<PoolArray<u8> as Export>::Hint>) -> ExportInfo

Returns ExportInfo given an optional typed hint.

impl<T> Extend<T> for PoolArray<T>where
    T: PoolElement,

fn extend<I>(&mut self, iter: I)where
    I: IntoIterator<Item = T>,

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<T> FromIterator<T> for PoolArray<T>where
    T: PoolElement,

fn from_iter<I>(iter: I) -> PoolArray<T>where
    I: IntoIterator<Item = T>,

Creates a value from an iterator.

impl<T> FromVariant for PoolArray<T>where
    T: PoolElement,

fn from_variant(variant: &Variant) -> Result<PoolArray<T>, FromVariantError>

impl<T> NewRef for PoolArray<T>where
    T: PoolElement,

fn new_ref(&self) -> PoolArray<T>

Creates a new reference to this reference-counted instance.

impl<T> PartialEq<PoolArray<T>> for PoolArray<T>where
    T: PoolElement + PartialEq<T>,

fn eq(&self, other: &PoolArray<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

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

impl<T> Serialize for PoolArray<T>where
    T: Serialize + PoolElement,

fn serialize<S>(
    &self,
    ser: S
) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>where
    S: Serializer,

Serialize this value into the given Serde serializer.

impl<T> ToVariant for PoolArray<T>where
    T: PoolElement,

fn to_variant(&self) -> Variant

impl<T> Eq for PoolArray<T>where
    T: PoolElement + Eq,

impl<T> ToVariantEq for PoolArray<T>where
    T: PoolElement + Eq,