Trait godot::meta::ArrayElement
pub trait ArrayElement: GodotType + Sealed {
// Provided method
fn debug_validate_elements(_array: &Array<Self>) -> Result<(), ConvertError> { ... }
}
Expand description
Marker trait to identify types that can be stored in Array<T>
.
The types, for which this trait is implemented, overlap mostly with GodotType
.
Notable differences are:
- Only
VariantArray
, notArray<T>
is allowed (typed arrays cannot be nested). Option
is only supported forOption<Gd<T>>
, but not e.g.Option<i32>
.
§Integer and float types
u8
, i8
, u16
, i16
, u32
, i32
and f32
are supported by this trait, however they don’t have their own array type in Godot.
The engine only knows about i64
(“int”) and f64
(“float”) types. This means that when using any integer or float type, Godot
will treat it as the equivalent of GDScript’s Array[int]
or Array[float]
, respectively.
As a result, when converting from a Godot typed array to a Rust Array<T>
, the values stored may not actually fit into a T
.
For example, you have a GDScript Array[int]
which stores value 160, and you convert it to a Rust Array<i8>
. This means that you may
end up with panics on element access (since the Variant
storing 160 will fail to convert to i8
). In Debug mode, we add additional
best-effort checks to detect such errors, however they are expensive and not bullet-proof. If you need very rigid type safety, stick to
i64
and f64
. The other types however can be extremely convenient and work well, as long as you are aware of the limitations.
u64
is entirely unsupported since it cannot be safely stored inside a Variant
.
Also, keep in mind that Godot uses Variant
for each element. If performance matters and you have small element types such as u8
,
consider using packed arrays (e.g. PackedByteArray
) instead.