OutArray, a possibly typed array.

godot-codegen/src/conv/type_conversions.rs

@@ -48,7 +48,7 @@ fn to_hardcoded_rust_ident(full_ty: &GodotTy) -> Option<&str> {
         // Others
         ("bool", None) => "bool",
         ("String", None) => "GString",
-        ("Array", None) => "VariantArray",
+        ("Array", None) => "OutArray",
 
         // Types needed for native structures mapping
         ("uint8_t", None) => "u8",
@@ -217,7 +217,9 @@ fn to_rust_type_uncached(full_ty: &GodotTy, ctx: &mut Context) -> RustTy {
     } else if let Some(elem_ty) = ty.strip_prefix("typedarray::") {
         let rust_elem_ty = to_rust_type(elem_ty, None, ctx);
         return if ctx.is_builtin(elem_ty) {
-            RustTy::BuiltinArray(quote! { Array<#rust_elem_ty> })
+            RustTy::BuiltinArray {
+                elem_type: quote! { Array<#rust_elem_ty> },
+            }
         } else {
             RustTy::EngineArray {
                 tokens: quote! { Array<#rust_elem_ty> },
@@ -256,6 +258,7 @@ fn to_rust_expr_inner(expr: &str, ty: &RustTy, is_inner: bool) -> TokenStream {
         "true" => return quote! { true },
         "false" => return quote! { false },
         "[]" | "{}" if is_inner => return quote! {},
+        "[]" if ty.is_out_array() => return quote! { OutArray::new_untyped() },
         "[]" => return quote! { Array::new() }, // VariantArray or Array<T>
         "{}" => return quote! { Dictionary::new() },
         "null" => {

godot-codegen/src/generator/builtins.rs

@@ -164,16 +164,9 @@ fn make_special_builtin_methods(class_name: &TyName, _ctx: &Context) -> TokenStr
 }
 
 /// Get the safety docs of an unsafe method, or `None` if it is safe.
-fn method_safety_doc(class_name: &TyName, method: &BuiltinMethod) -> Option<TokenStream> {
-    if class_name.godot_ty == "Array"
-        && &method.return_value().type_tokens().to_string() == "VariantArray"
-    {
-        return Some(quote! {
-            /// # Safety
-            ///
-            /// You must ensure that the returned array fulfils the safety invariants of [`Array`](crate::builtin::Array).
-        });
-    }
+fn method_safety_doc(_class_name: &TyName, _method: &BuiltinMethod) -> Option<TokenStream> {
+    // Was previously used for InnerArray methods returning VariantArray.
+    // Now safe with OutArray -> conversion happens in client code.
 
     None
 }

godot-codegen/src/models/domain.rs

@@ -582,11 +582,13 @@ pub struct GodotTy {
 
 #[derive(Clone, Debug)]
 pub enum RustTy {
-    /// `bool`, `Vector3i`
+    /// `bool`, `Vector3i`, `Array`
     BuiltinIdent(Ident),
 
     /// `Array<i32>`
-    BuiltinArray(TokenStream),
+    ///
+    /// Note that untyped arrays are mapped as `BuiltinIdent("Array")`.
+    BuiltinArray { elem_type: TokenStream },
 
     /// C-style raw pointer to a `RustTy`.
     RawPointer { inner: Box<RustTy>, is_const: bool },
@@ -634,13 +636,17 @@ impl RustTy {
             other => quote! { -> #other },
         }
     }
+
+    pub fn is_out_array(&self) -> bool {
+        matches!(self, Self::BuiltinIdent(id) if id == "OutArray")
+    }
 }
 
 impl ToTokens for RustTy {
     fn to_tokens(&self, tokens: &mut TokenStream) {
         match self {
             RustTy::BuiltinIdent(ident) => ident.to_tokens(tokens),
-            RustTy::BuiltinArray(path) => path.to_tokens(tokens),
+            RustTy::BuiltinArray { elem_type } => elem_type.to_tokens(tokens),
             RustTy::RawPointer {
                 inner,
                 is_const: true,

godot-codegen/src/special_cases/codegen_special_cases.rs

@@ -37,7 +37,7 @@ fn is_type_excluded(ty: &str, ctx: &mut Context) -> bool {
     fn is_rust_type_excluded(ty: &RustTy) -> bool {
         match ty {
             RustTy::BuiltinIdent(_) => false,
-            RustTy::BuiltinArray(_) => false,
+            RustTy::BuiltinArray { .. } => false,
             RustTy::RawPointer { inner, .. } => is_rust_type_excluded(inner),
             RustTy::EngineArray { elem_class, .. } => is_class_excluded(elem_class.as_str()),
             RustTy::EngineEnum {

godot-core/src/builtin/callable.rs

@@ -170,14 +170,14 @@ impl Callable {
     ///
     /// _Godot equivalent: `callv`_
     pub fn callv(&self, arguments: VariantArray) -> Variant {
-        self.as_inner().callv(arguments)
+        self.as_inner().callv(arguments.to_out_array())
     }
 
     /// Returns a copy of this Callable with one or more arguments bound, reading them from an array.
     ///
     /// _Godot equivalent: `bindv`_
     pub fn bindv(&self, arguments: VariantArray) -> Self {
-        self.as_inner().bindv(arguments)
+        self.as_inner().bindv(arguments.to_out_array())
     }
 
     /// Returns the name of the method represented by this callable. If the callable is a lambda function,

godot-core/src/builtin/collections/array.rs

@@ -9,6 +9,7 @@ use std::fmt;
 use std::marker::PhantomData;
 
 use crate::builtin::*;
+use crate::meta::error::ArrayMismatch;
 use crate::meta::error::{ConvertError, FromGodotError, FromVariantError};
 use crate::meta::{
     ArrayElement, ArrayTypeInfo, FromGodot, GodotConvert, GodotFfiVariant, GodotType, ToGodot,
@@ -107,7 +108,8 @@ use sys::{ffi_methods, interface_fn, GodotFfi};
 /// concurrent modification on other threads (e.g. created through GDScript).
 pub struct Array<T: ArrayElement> {
     // Safety Invariant: The type of all values in `opaque` matches the type `T`.
-    opaque: sys::types::OpaqueArray,
+    // Visibility: shared with OutArray.
+    pub(super) opaque: sys::types::OpaqueArray,
     _phantom: PhantomData<T>,
 }
 
@@ -146,7 +148,8 @@ impl_builtin_froms!(VariantArray;
 );
 
 impl<T: ArrayElement> Array<T> {
-    fn from_opaque(opaque: sys::types::OpaqueArray) -> Self {
+    // Visibility: shared with OutArray.
+    pub(super) fn from_opaque(opaque: sys::types::OpaqueArray) -> Self {
         // Note: type is not yet checked at this point, because array has not yet been initialized!
         Self {
             opaque,
@@ -417,13 +420,10 @@ impl<T: ArrayElement> Array<T> {
 
     /// Appends another array at the end of this array. Equivalent of `append_array` in GDScript.
     pub fn extend_array(&mut self, other: Array<T>) {
-        // SAFETY: `append_array` will only read values from `other`, and all types can be converted to `Variant`.
-        let other: VariantArray = unsafe { other.assume_type::<Variant>() };
-
-        // SAFETY: `append_array` will only write values gotten from `other` into `self`, and all values in `other` are guaranteed
+        // SAFETY: `append_array` only reads values from `other` and writes them to `self`, and all values in `other` are guaranteed
         // to be of type `T`.
         let mut inner_self = unsafe { self.as_inner_mut() };
-        inner_self.append_array(other);
+        inner_self.append_array(other.to_out_array());
     }
 
     /// Returns a shallow copy of the array. All array elements are copied, but any reference types
@@ -432,10 +432,9 @@ impl<T: ArrayElement> Array<T> {
     /// To create a deep copy, use [`duplicate_deep()`][Self::duplicate_deep] instead.
     /// To create a new reference to the same array data, use [`clone()`][Clone::clone].
     pub fn duplicate_shallow(&self) -> Self {
-        // SAFETY: We never write to the duplicated array, and all values read are read as `Variant`.
-        let duplicate: VariantArray = unsafe { self.as_inner().duplicate(false) };
+        let duplicate: OutArray = self.as_inner().duplicate(false);
 
-        // SAFETY: duplicate() returns a typed array with the same type as Self, and all values are taken from `self` so have the right type.
+        // SAFETY: duplicate() returns a typed array with the same type as Self.
         unsafe { duplicate.assume_type() }
     }
 
@@ -446,10 +445,9 @@ impl<T: ArrayElement> Array<T> {
     /// To create a shallow copy, use [`duplicate_shallow()`][Self::duplicate_shallow] instead.
     /// To create a new reference to the same array data, use [`clone()`][Clone::clone].
     pub fn duplicate_deep(&self) -> Self {
-        // SAFETY: We never write to the duplicated array, and all values read are read as `Variant`.
-        let duplicate: VariantArray = unsafe { self.as_inner().duplicate(true) };
+        let duplicate: OutArray = self.as_inner().duplicate(true);
 
-        // SAFETY: duplicate() returns a typed array with the same type as Self, and all values are taken from `self` so have the right type.
+        // SAFETY: duplicate() returns a typed array with the same type as Self.
         unsafe { duplicate.assume_type() }
     }
 
@@ -494,12 +492,11 @@ impl<T: ArrayElement> Array<T> {
         let step = step.unwrap_or(1);
 
         // SAFETY: The type of the array is `T` and we convert the returned array to an `Array<T>` immediately.
-        let subarray: VariantArray = unsafe {
+        let subarray: OutArray =
             self.as_inner()
-                .slice(to_i64(begin), to_i64(end), step.try_into().unwrap(), deep)
-        };
+                .slice(to_i64(begin), to_i64(end), step.try_into().unwrap(), deep);
 
-        // SAFETY: slice() returns a typed array with the same type as Self
+        // SAFETY: slice() returns a typed array with the same type as Self.
         unsafe { subarray.assume_type() }
     }
 
@@ -554,8 +551,7 @@ impl<T: ArrayElement> Array<T> {
     }
 
     /// 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.
+    /// `None` if not found. Starts searching at index `from`; pass `None` to search the entire array.
     pub fn rfind(&self, value: &T, from: Option<usize>) -> Option<usize> {
         let from = from.map(to_i64).unwrap_or(-1);
         let index = self.as_inner().rfind(value.to_variant(), from);
@@ -633,6 +629,10 @@ impl<T: ArrayElement> Array<T> {
         unsafe { self.as_inner_mut() }.shuffle();
     }
 
+    pub fn to_out_array(&self) -> OutArray {
+        OutArray::consume_typed_array(self.clone())
+    }
+
     /// Asserts that the given index refers to an existing element.
     ///
     /// # Panics
@@ -734,17 +734,45 @@ impl<T: ArrayElement> Array<T> {
     ///
     /// In the current implementation, both cases will produce a panic rather than undefined
     /// behavior, but this should not be relied upon.
-    unsafe fn assume_type<U: ArrayElement>(self) -> Array<U> {
+    // Visibility: shared with OutArray.
+    pub(super) unsafe fn assume_type<U: ArrayElement>(self) -> Array<U> {
         // SAFETY: The memory layout of `Array<T>` does not depend on `T`.
-        unsafe { std::mem::transmute(self) }
+        std::mem::transmute(self)
+    }
+
+    /// # Safety
+    /// Returned type may be inaccurate and must be type-checked after the call.
+    // Visibility: shared with OutArray.
+    pub(super) unsafe fn default_unchecked() -> Array<T> {
+        Self::new_with_uninit(|self_ptr| {
+            let ctor = sys::builtin_fn!(array_construct_default);
+            ctor(self_ptr, std::ptr::null_mut())
+        })
+    }
+
+    /// # Safety
+    /// Returned type may be inaccurate and must be type-checked after the call.
+    // Visibility: shared with OutArray.
+    pub(super) unsafe fn clone_unchecked(&self) -> Array<T> {
+        Self::new_with_uninit(|self_ptr| {
+            let ctor = sys::builtin_fn!(array_construct_copy);
+            let args = [self.sys()];
+            ctor(self_ptr, args.as_ptr());
+        })
     }
 
     /// Returns the runtime type info of this array.
-    fn type_info(&self) -> ArrayTypeInfo {
+    // Visibility: shared with OutArray.
+    pub(super) fn type_info(&self) -> ArrayTypeInfo {
         let variant_type = VariantType::from_sys(
             self.as_inner().get_typed_builtin() as sys::GDExtensionVariantType
         );
-        let class_name = self.as_inner().get_typed_class_name();
+
+        let class_name = if variant_type == VariantType::OBJECT {
+            Some(self.as_inner().get_typed_class_name())
+        } else {
+            None
+        };
 
         ArrayTypeInfo {
             variant_type,
@@ -760,10 +788,10 @@ impl<T: ArrayElement> Array<T> {
         if self_ty == target_ty {
             Ok(self)
         } else {
-            Err(FromGodotError::BadArrayType {
+            Err(FromGodotError::BadArrayType(ArrayMismatch {
                 expected: target_ty,
                 actual: self_ty,
-            }
+            })
             .into_error(self))
         }
     }
@@ -781,17 +809,49 @@ impl<T: ArrayElement> Array<T> {
         if type_info.is_typed() {
             let script = Variant::nil();
 
+            // A bit contrived because empty StringName is lazy-initialized but must also remain valid.
+            #[allow(unused_assignments)]
+            let mut empty_string_name = None;
+            let class_name = if let Some(class_name) = &type_info.class_name {
+                class_name.string_sys()
+            } else {
+                empty_string_name = Some(StringName::default());
+                empty_string_name.unwrap().string_sys()
+            };
+
             // SAFETY: The array is a newly created empty untyped array.
             unsafe {
                 interface_fn!(array_set_typed)(
                     self.sys_mut(),
                     type_info.variant_type.sys(),
-                    type_info.class_name.string_sys(),
+                    class_name, // must be empty if variant_type != OBJECT.
                     script.var_sys(),
                 );
             }
         }
     }
+
+    /// # Safety
+    /// Does not validate the array element type; `with_checked_type()` should be called afterward.
+    // Visibility: shared with OutArray.
+    pub(super) unsafe fn unchecked_from_variant(variant: &Variant) -> Result<Self, ConvertError> {
+        if variant.get_type() != Self::variant_type() {
+            return Err(FromVariantError::BadType {
+                expected: Self::variant_type(),
+                actual: variant.get_type(),
+            }
+            .into_error(variant.clone()));
+        }
+
+        let array = unsafe {
+            sys::new_with_uninit_or_init::<Self>(|self_ptr| {
+                let array_from_variant = sys::builtin_fn!(array_from_variant);
+                array_from_variant(self_ptr, sys::SysPtr::force_mut(variant.var_sys()));
+            })
+        };
+
+        Ok(array)
+    }
 }
 
 // ----------------------------------------------------------------------------------------------------------------------------------------------
@@ -885,14 +945,8 @@ impl<T: ArrayElement + fmt::Display> fmt::Display for Array<T> {
 /// [`Array::duplicate_deep()`].
 impl<T: ArrayElement> Clone for Array<T> {
     fn clone(&self) -> Self {
-        // SAFETY: `self` is a valid array, since we have a reference that keeps it alive.
-        let array = unsafe {
-            Self::new_with_uninit(|self_ptr| {
-                let ctor = sys::builtin_fn!(array_construct_copy);
-                let args = [self.sys()];
-                ctor(self_ptr, args.as_ptr());
-            })
-        };
+        // SAFETY: `self` is a valid array, since we have a reference that keeps it alive. Type is checked below.
+        let array = unsafe { self.clone_unchecked() };
 
         array
             .with_checked_type()
@@ -952,12 +1006,7 @@ impl Export for Array<Variant> {
 impl<T: ArrayElement> Default for Array<T> {
     #[inline]
     fn default() -> Self {
-        let mut array = unsafe {
-            Self::new_with_uninit(|self_ptr| {
-                let ctor = sys::builtin_fn!(array_construct_default);
-                ctor(self_ptr, std::ptr::null_mut())
-            })
-        };
+        let mut array = unsafe { Self::default_unchecked() };
 
         // SAFETY: We just created this array, and haven't called `init_inner_type` before.
         unsafe { array.init_inner_type() };
@@ -1010,22 +1059,10 @@ impl<T: ArrayElement> GodotFfiVariant for Array<T> {
     }
 
     fn ffi_from_variant(variant: &Variant) -> Result<Self, ConvertError> {
-        if variant.get_type() != Self::variant_type() {
-            return Err(FromVariantError::BadType {
-                expected: Self::variant_type(),
-                actual: variant.get_type(),
-            }
-            .into_error(variant.clone()));
-        }
-
-        let array = unsafe {
-            sys::new_with_uninit_or_init::<Self>(|self_ptr| {
-                let array_from_variant = sys::builtin_fn!(array_from_variant);
-                array_from_variant(self_ptr, sys::SysPtr::force_mut(variant.var_sys()));
-            })
-        };
+        // SAFETY: with_checked_type() is called right after, ensuring the array has the correct type.
+        let unchecked_array = unsafe { Self::unchecked_from_variant(variant) };
 
-        array.with_checked_type()
+        unchecked_array.and_then(|array| array.with_checked_type())
     }
 }