Struct PackedArray

pub struct PackedArray<T>where
    T: PackedArrayElement,
{ /* private fields */ }

Expand description

Space-efficient array of T 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.

§Type aliases

This generic type can be instantiated for a finite number of element types, which all implement PackedArrayElement.
Here is the exhaustive list:

Type alias	Element	Godot docs
`PackedByteArray`	`u8`	Link
`PackedInt32Array`	`i32`	Link
`PackedInt64Array`	`i64`	Link
`PackedFloat32Array`	`f32`	Link
`PackedFloat64Array`	`f64`	Link
`PackedVector2Array`	`Vector2`	Link
`PackedVector3Array`	`Vector3`	Link
`PackedVector4Array`	`Vector4`	Link
`PackedColorArray`	`Color`	Link
`PackedStringArray`	`GString`	Link

§Registering properties

You can use both #[var] and #[export] with packed arrays. In godot-rust, modifications to packed array properties are properly synchronized between Rust and GDScript/reflection access.

In GDScript, mutating methods like append_array() may not work on PackedArray properties of engine classes. See godot/#76150 for details.

§Thread safety

Usage is safe if the PackedArray<T> 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<T> PackedArray<T>
where T: PackedArrayElement,

pub fn new() -> PackedArray<T>

Constructs an empty array.

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

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

Returns true if the array contains the given value.

Godot equivalent: has

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

Godot equivalent: size

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

Appends an element to the end of the array.

Godot equivalent: append, push_back

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

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()).

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

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<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, 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: &PackedArray<T>)

Appends another array at the end of this array.

Godot equivalent: append_array

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

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

pub fn subarray(&self, range: impl SignedRange) -> PackedArray<T>

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

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.

§Usage

For negative indices, use wrapped().

let array = PackedArray::from([10, 20, 30, 40, 50]);

// If either `begin` or `end` is negative, its value is relative to the end of the array.
let sub = array.subarray(wrapped(-4..-2));
assert_eq!(sub, PackedArray::from([20, 30]));

// If `end` is not specified, the resulting subarray will span to the end of the array.
let sub = array.subarray(2..);
assert_eq!(sub, PackedArray::from([30, 40, 50]));

Godot equivalent: slice

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

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 [T]

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<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: impl AsArg<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: impl AsArg<T>) -> 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.

§

impl PackedArray<u8>

Specialized API for PackedByteArray.

pub fn to_float32_array(&self) -> PackedArray<f32>

Returns a copy of the data converted to a PackedFloat32Array, where each block of 4 bytes has been converted to a 32-bit float.

The size of the input array must be a multiple of 4 (size of 32-bit float). The size of the new array will be byte_array.size() / 4.

If the original data can’t be converted to 32-bit floats, the resulting data is undefined.

pub fn to_float64_array(&self) -> PackedArray<f64>

Returns a copy of the data converted to a PackedFloat64Array, where each block of 8 bytes has been converted to a 64-bit float.

The size of the input array must be a multiple of 8 (size of 64-bit float). The size of the new array will be byte_array.size() / 8.

If the original data can’t be converted to 64-bit floats, the resulting data is undefined.

pub fn to_int32_array(&self) -> PackedArray<i32>

Returns a copy of the data converted to a PackedInt32Array, where each block of 4 bytes has been converted to a 32-bit integer.

The size of the input array must be a multiple of 4 (size of 32-bit integer). The size of the new array will be byte_array.size() / 4.

If the original data can’t be converted to 32-bit integers, the resulting data is undefined.

pub fn to_int64_array(&self) -> PackedArray<i64>

Returns a copy of the data converted to a PackedInt64Array, where each block of 8 bytes has been converted to a 64-bit integer.

The size of the input array must be a multiple of 8 (size of 64-bit integer). The size of the new array will be byte_array.size() / 8.

If the original data can’t be converted to 64-bit integers, the resulting data is undefined.

§

impl PackedArray<i32>

pub fn to_byte_array(&self) -> PackedArray<u8>

Returns a PackedByteArray with each value encoded as bytes.

§

impl PackedArray<i64>

pub fn to_byte_array(&self) -> PackedArray<u8>

Returns a PackedByteArray with each value encoded as bytes.

§

impl PackedArray<f32>

pub fn to_byte_array(&self) -> PackedArray<u8>

Returns a PackedByteArray with each value encoded as bytes.

§

impl PackedArray<f64>

pub fn to_byte_array(&self) -> PackedArray<u8>

Returns a PackedByteArray with each value encoded as bytes.

§

impl PackedArray<GString>

pub fn to_byte_array(&self) -> PackedArray<u8>

Returns a PackedByteArray with each value encoded as bytes.

§

impl PackedArray<Vector2>

pub fn to_byte_array(&self) -> PackedArray<u8>

Returns a PackedByteArray with each value encoded as bytes.

§

impl PackedArray<Vector3>

pub fn to_byte_array(&self) -> PackedArray<u8>

Returns a PackedByteArray with each value encoded as bytes.

§

impl PackedArray<Vector4>

pub fn to_byte_array(&self) -> PackedArray<u8>

Returns a PackedByteArray with each value encoded as bytes.

§

impl PackedArray<Color>

pub fn to_byte_array(&self) -> PackedArray<u8>

Returns a PackedByteArray with each value encoded as bytes.

§

impl PackedArray<u8>

pub fn encode_u8(&mut self, byte_offset: usize, value: u8) -> Result<(), ()>

Encodes u8 as 1 byte(s) at position byte_offset.

Returns Err if there is not enough space left to write the value, and does nothing in that case.

Note: byte order and encoding pattern is an implementation detail. For portable byte representation and faster encoding, use as_mut_slice() and the various Rust standard APIs such as u8::to_be_bytes().

pub fn decode_u8(&self, byte_offset: usize) -> Result<u8, ()>

Decodes u8 from 1 byte(s) at position byte_offset.

Returns Err if there is not enough space left to read the value. In case Godot has other error conditions for decoding, it may return zero and print an error.

Note: byte order and encoding pattern is an implementation detail. For portable byte representation and faster decoding, use as_slice() and the various Rust standard APIs such as u8::from_be_bytes().

pub fn encode_s8(&mut self, byte_offset: usize, value: i8) -> Result<(), ()>

Encodes i8 as 1 byte(s) at position byte_offset.

Returns Err if there is not enough space left to write the value, and does nothing in that case.

Note: byte order and encoding pattern is an implementation detail. For portable byte representation and faster encoding, use as_mut_slice() and the various Rust standard APIs such as i8::to_be_bytes().

pub fn decode_s8(&self, byte_offset: usize) -> Result<i8, ()>

Decodes i8 from 1 byte(s) at position byte_offset.

Returns Err if there is not enough space left to read the value. In case Godot has other error conditions for decoding, it may return zero and print an error.

Note: byte order and encoding pattern is an implementation detail. For portable byte representation and faster decoding, use as_slice() and the various Rust standard APIs such as i8::from_be_bytes().

pub fn encode_u16(&mut self, byte_offset: usize, value: u16) -> Result<(), ()>

Encodes u16 as 2 byte(s) at position byte_offset.

Returns Err if there is not enough space left to write the value, and does nothing in that case.

Note: byte order and encoding pattern is an implementation detail. For portable byte representation and faster encoding, use as_mut_slice() and the various Rust standard APIs such as u16::to_be_bytes().

pub fn decode_u16(&self, byte_offset: usize) -> Result<u16, ()>

Decodes u16 from 2 byte(s) at position byte_offset.

Returns Err if there is not enough space left to read the value. In case Godot has other error conditions for decoding, it may return zero and print an error.

Note: byte order and encoding pattern is an implementation detail. For portable byte representation and faster decoding, use as_slice() and the various Rust standard APIs such as u16::from_be_bytes().

pub fn encode_s16(&mut self, byte_offset: usize, value: i16) -> Result<(), ()>

Encodes i16 as 2 byte(s) at position byte_offset.

Returns Err if there is not enough space left to write the value, and does nothing in that case.

Note: byte order and encoding pattern is an implementation detail. For portable byte representation and faster encoding, use as_mut_slice() and the various Rust standard APIs such as i16::to_be_bytes().

pub fn decode_s16(&self, byte_offset: usize) -> Result<i16, ()>

Decodes i16 from 2 byte(s) at position byte_offset.

Returns Err if there is not enough space left to read the value. In case Godot has other error conditions for decoding, it may return zero and print an error.

Note: byte order and encoding pattern is an implementation detail. For portable byte representation and faster decoding, use as_slice() and the various Rust standard APIs such as i16::from_be_bytes().

pub fn encode_u32(&mut self, byte_offset: usize, value: u32) -> Result<(), ()>

Encodes u32 as 4 byte(s) at position byte_offset.

Returns Err if there is not enough space left to write the value, and does nothing in that case.

Note: byte order and encoding pattern is an implementation detail. For portable byte representation and faster encoding, use as_mut_slice() and the various Rust standard APIs such as u32::to_be_bytes().

pub fn decode_u32(&self, byte_offset: usize) -> Result<u32, ()>

Decodes u32 from 4 byte(s) at position byte_offset.

Returns Err if there is not enough space left to read the value. In case Godot has other error conditions for decoding, it may return zero and print an error.

Note: byte order and encoding pattern is an implementation detail. For portable byte representation and faster decoding, use as_slice() and the various Rust standard APIs such as u32::from_be_bytes().

pub fn encode_s32(&mut self, byte_offset: usize, value: i32) -> Result<(), ()>

Encodes i32 as 4 byte(s) at position byte_offset.

Returns Err if there is not enough space left to write the value, and does nothing in that case.

Note: byte order and encoding pattern is an implementation detail. For portable byte representation and faster encoding, use as_mut_slice() and the various Rust standard APIs such as i32::to_be_bytes().

pub fn decode_s32(&self, byte_offset: usize) -> Result<i32, ()>

Decodes i32 from 4 byte(s) at position byte_offset.

Returns Err if there is not enough space left to read the value. In case Godot has other error conditions for decoding, it may return zero and print an error.

Note: byte order and encoding pattern is an implementation detail. For portable byte representation and faster decoding, use as_slice() and the various Rust standard APIs such as i32::from_be_bytes().

pub fn encode_u64(&mut self, byte_offset: usize, value: u64) -> Result<(), ()>

Encodes u64 as 8 byte(s) at position byte_offset.

Returns Err if there is not enough space left to write the value, and does nothing in that case.

Note: byte order and encoding pattern is an implementation detail. For portable byte representation and faster encoding, use as_mut_slice() and the various Rust standard APIs such as u64::to_be_bytes().

pub fn decode_u64(&self, byte_offset: usize) -> Result<u64, ()>

Decodes u64 from 8 byte(s) at position byte_offset.

Returns Err if there is not enough space left to read the value. In case Godot has other error conditions for decoding, it may return zero and print an error.

Note: byte order and encoding pattern is an implementation detail. For portable byte representation and faster decoding, use as_slice() and the various Rust standard APIs such as u64::from_be_bytes().

pub fn encode_s64(&mut self, byte_offset: usize, value: i64) -> Result<(), ()>

Encodes i64 as 8 byte(s) at position byte_offset.

Returns Err if there is not enough space left to write the value, and does nothing in that case.

Note: byte order and encoding pattern is an implementation detail. For portable byte representation and faster encoding, use as_mut_slice() and the various Rust standard APIs such as i64::to_be_bytes().

pub fn decode_s64(&self, byte_offset: usize) -> Result<i64, ()>

Decodes i64 from 8 byte(s) at position byte_offset.

Returns Err if there is not enough space left to read the value. In case Godot has other error conditions for decoding, it may return zero and print an error.

Note: byte order and encoding pattern is an implementation detail. For portable byte representation and faster decoding, use as_slice() and the various Rust standard APIs such as i64::from_be_bytes().

pub fn encode_half(&mut self, byte_offset: usize, value: f32) -> Result<(), ()>

Encodes f32 as 2 byte(s) at position byte_offset.

Returns Err if there is not enough space left to write the value, and does nothing in that case.

Note: byte order and encoding pattern is an implementation detail. For portable byte representation and faster encoding, use as_mut_slice() and the various Rust standard APIs such as f32::to_be_bytes().

pub fn decode_half(&self, byte_offset: usize) -> Result<f32, ()>

Decodes f32 from 2 byte(s) at position byte_offset.

Returns Err if there is not enough space left to read the value. In case Godot has other error conditions for decoding, it may return zero and print an error.

Note: byte order and encoding pattern is an implementation detail. For portable byte representation and faster decoding, use as_slice() and the various Rust standard APIs such as f32::from_be_bytes().

pub fn encode_float(&mut self, byte_offset: usize, value: f32) -> Result<(), ()>

Encodes f32 as 4 byte(s) at position byte_offset.

Returns Err if there is not enough space left to write the value, and does nothing in that case.

Note: byte order and encoding pattern is an implementation detail. For portable byte representation and faster encoding, use as_mut_slice() and the various Rust standard APIs such as f32::to_be_bytes().

pub fn decode_float(&self, byte_offset: usize) -> Result<f32, ()>

Decodes f32 from 4 byte(s) at position byte_offset.

Returns Err if there is not enough space left to read the value. In case Godot has other error conditions for decoding, it may return zero and print an error.

Note: byte order and encoding pattern is an implementation detail. For portable byte representation and faster decoding, use as_slice() and the various Rust standard APIs such as f32::from_be_bytes().

pub fn encode_double( &mut self, byte_offset: usize, value: f64, ) -> Result<(), ()>

Encodes f64 as 8 byte(s) at position byte_offset.

Returns Err if there is not enough space left to write the value, and does nothing in that case.

Note: byte order and encoding pattern is an implementation detail. For portable byte representation and faster encoding, use as_mut_slice() and the various Rust standard APIs such as f64::to_be_bytes().

pub fn decode_double(&self, byte_offset: usize) -> Result<f64, ()>

Decodes f64 from 8 byte(s) at position byte_offset.

Returns Err if there is not enough space left to read the value. In case Godot has other error conditions for decoding, it may return zero and print an error.

Note: byte order and encoding pattern is an implementation detail. For portable byte representation and faster decoding, use as_slice() and the various Rust standard APIs such as f64::from_be_bytes().

pub fn encode_var( &mut self, byte_offset: usize, value: impl AsArg<Variant>, allow_objects: bool, ) -> Result<usize, ()>

Encodes a Variant as bytes. Returns number of bytes written, or Err on encoding failure.

Sufficient space must be allocated, depending on the encoded variant’s size. If allow_objects is false, VariantType::OBJECT values are not permitted and will instead be serialized as ID-only. You should set allow_objects to false by default.

pub fn decode_var( &self, byte_offset: usize, allow_objects: bool, ) -> Result<(Variant, usize), ()>

Decodes a Variant from bytes and returns it, alongside the number of bytes read.

Returns Err on decoding error. If you store legit NIL variants inside the byte array, use decode_var_allow_nil() instead.

§API design

Godot offers three separate methods decode_var(), decode_var_size() and has_encoded_var(). That comes with several problems:

has_encoded_var() is practically useless, because it performs the full decoding work and then throws away the variant. decode_var() can do all that and more.
Both has_encoded_var() and decode_var_size() are unreliable. They don’t tell whether an actual variant has been written at the location. They interpret garbage as Variant::nil() and return true or 4, respectively. This can very easily cause bugs because surprisingly, some users may expect that has_encoded_var() returns whether a variant has been encoded.
The underlying C++ implementation has all the necessary information (whether a variant is there, how big it is and its value) but the GDExtension API returns only one info at a time, requiring re-decoding on each call.

godot-rust mitigates this somewhat, with the following design:

decode_var() treats all NILs as errors. This is most often the desired behavior, and if not, decode_var_allow_nil() can be used. It’s also the only way to detect errors at all – once you store legit NIL values, you can no longer differentiate them from garbage.
decode_var() returns both the decoded variant and its size. This requires two decoding runs, but only if the variant is actually valid. Again, in many cases, a user needs the size to know where follow-up data in the buffer starts.
decode_var_size() and has_encoded_var() are not exposed.

§Security

You should set allow_objects to false unless you have a good reason not to. Decoding objects (e.g. coming from remote sources) can cause arbitrary code execution.

pub fn decode_var_allow_nil( &self, byte_offset: usize, allow_objects: bool, ) -> (Variant, usize)

Unreliable Variant decoding, allowing NIL.

This method is highly unreliable and will try to interpret anything into variants, even zeroed memory or random byte patterns. Only use it if you need a 1:1 equivalent of Godot's decode_var() and decode_var_size() functions.

In the majority of cases, decode_var() is the better choice, as it’s much easier to use correctly. See also its section about the rationale behind the current API design.

Returns a tuple of two elements:

the decoded variant. This is Variant::nil() if a valid variant can’t be decoded, or the value is of type VariantType::OBJECT and allow_objects is false.
The number of bytes the variant occupies. This is 0 if running out of space, but most other failures are not recognized.

§Security

You should set allow_objects to false unless you have a good reason not to. Decoding objects (e.g. coming from remote sources) can cause arbitrary code execution.

pub fn compress( &self, compression_mode: CompressionMode, ) -> Result<PackedArray<u8>, ()>

Returns a new PackedByteArray, with the data of this array compressed.

On failure, Godot prints an error and this method returns Err. (Note that any empty results coming from Godot are mapped to Err in Rust.)

pub fn decompress( &self, buffer_size: usize, compression_mode: CompressionMode, ) -> Result<PackedArray<u8>, ()>

Returns a new PackedByteArray, with the data of this array decompressed.

Set buffer_size to the size of the uncompressed data.

On failure, Godot prints an error and this method returns Err. (Note that any empty results coming from Godot are mapped to Err in Rust.)

Note: Decompression is not guaranteed to work with data not compressed by Godot, for example if data compressed with the deflate compression mode lacks a checksum or header.

pub fn decompress_dynamic( &self, max_output_size: Option<usize>, compression_mode: CompressionMode, ) -> Result<PackedArray<u8>, ()>

Returns a new PackedByteArray, with the data of this array decompressed, and without fixed decompression buffer.

This method only accepts BROTLI, GZIP, and DEFLATE compression modes.

This method is potentially slower than decompress(), as it may have to re-allocate its output buffer multiple times while decompressing, whereas decompress() knows its output buffer size from the beginning.

GZIP has a maximal compression ratio of 1032:1, meaning it’s very possible for a small compressed payload to decompress to a potentially very large output. To guard against this, you may provide a maximum size this function is allowed to allocate in bytes via max_output_size. Passing None will allow for unbounded output. If any positive value is passed, and the decompression exceeds that amount in bytes, then an error will be returned.

On failure, Godot prints an error and this method returns Err. (Note that any empty results coming from Godot are mapped to Err in Rust.)

Note: Decompression is not guaranteed to work with data not compressed by Godot, for example if data compressed with the deflate compression mode lacks a checksum or header.

§