Struct PackedByteArray

pub struct PackedByteArray { /* private fields */ }

Expand description

Implements Godot’s PackedByteArray type, which is a space-efficient array of u8s.

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.

§Thread safety

Usage is safe if the PackedByteArray 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 PackedByteArray

pub fn new() -> PackedByteArray

Constructs an empty array.

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

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<u8>) -> bool

Returns true if the array contains the given value.

Godot equivalent: has

pub fn count(&self, value: impl AsArg<u8>) -> 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<u8>)

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<u8>)

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) -> u8

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<u8>)

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: &PackedByteArray)

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

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

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

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

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) -> &[u8] ⓘ

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 [u8] ⓘ

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<u8>, 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<u8>, 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.