Skip to content

Commit

Permalink
Note about element type safety of Array<T>
Browse files Browse the repository at this point in the history
  • Loading branch information
Bromeon committed Dec 2, 2024
1 parent c6b2357 commit fb19420
Showing 1 changed file with 16 additions and 0 deletions.
16 changes: 16 additions & 0 deletions godot-core/src/builtin/collections/array.rs
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,22 @@ use sys::{ffi_methods, interface_fn, GodotFfi};
/// 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).
///
/// # Element type safety
///
/// We provide a richer set of element types than Godot, for convenience and stronger invariants in your _Rust_ code.
/// This, however, means that the Godot representation of such arrays is not capable of incorporating the additional "Rust-side" information.
/// This can lead to situations where GDScript code or the editor UI can insert values that do not fulfill the Rust-side invariants.
/// The library offers some best-effort protection in Debug mode, but certain errors may only occur on element access, in the form of panics.
///
/// Concretely, the following types lose type information when passed to Godot. If you want 100% bullet-proof arrays, avoid those.
/// - Non-`i64` integers: `i8`, `i16`, `i32`, `u8`, `u16`, `u32`. (`u64` is unsupported).
/// - Non-`f64` floats: `f32`.
/// - Non-null objects: [`Gd<T>`][crate::obj::Gd].
/// Godot generally allows `null` in arrays due to default-constructability, e.g. when using `resize()`.
/// The Godot-faithful (but less convenient) alternative is to use `Option<Gd<T>>` element types.
/// - Objects with dyn-trait association: [`DynGd<T, D>`][crate::obj::DynGd].
/// Godot doesn't know Rust traits and will only see the `T` part.
///
/// # Godot docs
///
/// [`Array[T]` (stable)](https://docs.godotengine.org/en/stable/classes/class_array.html)
Expand Down

0 comments on commit fb19420

Please sign in to comment.