Merge #708 #710

708: Method converting Variants to primitives by type r=toasteater a=toasteater

Adds `Variant::dispatch`, a method that converts the variant to a primitive value depending on its type, and returns that result as a Rust enum the user can then conveniently `match` on.

710: TypedArray: mention use cases and limitations in doc r=toasteater a=Bromeon

Adds a short paragraph to the `TypedArray` documentation:
![grafik](https://user-images.githubusercontent.com/708488/111084207-7d6a7880-8511-11eb-8167-d7ab26459fc1.png)


Co-authored-by: toasteater <48371905+toasteater@users.noreply.github.com>
Co-authored-by: Jan Haller <bromeon@gmail.com>

Author: 3 people

gdnative-core/src/core_types/typed_array.rs

@@ -14,6 +14,13 @@ use crate::NewRef;
 /// A reference-counted CoW typed vector using Godot's pool allocator, generic over possible
 /// element types.
 ///
+/// `TypedArray` unifies all the different `Pool*Array` types exported by Godot. It can be used
+/// in exported Rust methods as parameter and return types, as well as in exported properties.
+/// However, it is limited to the element types, for which a `Pool*Array` exists in GDScript,
+/// i.e. it cannot contain user-defined types.
+/// If you need other types, look into [`VariantArray`](struct.VariantArray.html) or directly use
+/// `Vec<T>` for type safety.
+///
 /// This type is CoW. The `Clone` implementation of this type creates a new reference without
 /// copying the contents.
 ///

gdnative-core/src/core_types/variant.rs

@@ -84,38 +84,89 @@ macro_rules! variant_to_type_from_sys {
     )
 }
 
-#[repr(u32)]
-#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
-pub enum VariantType {
-    Nil = sys::godot_variant_type_GODOT_VARIANT_TYPE_NIL as u32,
-    Bool = sys::godot_variant_type_GODOT_VARIANT_TYPE_BOOL as u32,
-    I64 = sys::godot_variant_type_GODOT_VARIANT_TYPE_INT as u32,
-    F64 = sys::godot_variant_type_GODOT_VARIANT_TYPE_REAL as u32,
-    GodotString = sys::godot_variant_type_GODOT_VARIANT_TYPE_STRING as u32,
-    Vector2 = sys::godot_variant_type_GODOT_VARIANT_TYPE_VECTOR2 as u32,
-    Rect2 = sys::godot_variant_type_GODOT_VARIANT_TYPE_RECT2 as u32,
-    Vector3 = sys::godot_variant_type_GODOT_VARIANT_TYPE_VECTOR3 as u32,
-    Transform2D = sys::godot_variant_type_GODOT_VARIANT_TYPE_TRANSFORM2D as u32,
-    Plane = sys::godot_variant_type_GODOT_VARIANT_TYPE_PLANE as u32,
-    Quat = sys::godot_variant_type_GODOT_VARIANT_TYPE_QUAT as u32,
-    Aabb = sys::godot_variant_type_GODOT_VARIANT_TYPE_AABB as u32,
-    Basis = sys::godot_variant_type_GODOT_VARIANT_TYPE_BASIS as u32,
-    Transform = sys::godot_variant_type_GODOT_VARIANT_TYPE_TRANSFORM as u32,
-    Color = sys::godot_variant_type_GODOT_VARIANT_TYPE_COLOR as u32,
-    NodePath = sys::godot_variant_type_GODOT_VARIANT_TYPE_NODE_PATH as u32,
-    Rid = sys::godot_variant_type_GODOT_VARIANT_TYPE_RID as u32,
-    Object = sys::godot_variant_type_GODOT_VARIANT_TYPE_OBJECT as u32,
-    Dictionary = sys::godot_variant_type_GODOT_VARIANT_TYPE_DICTIONARY as u32,
-    VariantArray = sys::godot_variant_type_GODOT_VARIANT_TYPE_ARRAY as u32,
-    ByteArray = sys::godot_variant_type_GODOT_VARIANT_TYPE_POOL_BYTE_ARRAY as u32,
-    Int32Array = sys::godot_variant_type_GODOT_VARIANT_TYPE_POOL_INT_ARRAY as u32,
-    Float32Array = sys::godot_variant_type_GODOT_VARIANT_TYPE_POOL_REAL_ARRAY as u32,
-    StringArray = sys::godot_variant_type_GODOT_VARIANT_TYPE_POOL_STRING_ARRAY as u32,
-    Vector2Array = sys::godot_variant_type_GODOT_VARIANT_TYPE_POOL_VECTOR2_ARRAY as u32,
-    Vector3Array = sys::godot_variant_type_GODOT_VARIANT_TYPE_POOL_VECTOR3_ARRAY as u32,
-    ColorArray = sys::godot_variant_type_GODOT_VARIANT_TYPE_POOL_COLOR_ARRAY as u32,
+macro_rules! variant_dispatch_arm {
+    ($v:expr, $variant:ident ( $inner:ty )) => {
+        VariantDispatch::$variant(<$inner>::from_variant($v).unwrap())
+    };
+    ($v:expr, $variant:ident) => {
+        VariantDispatch::$variant
+    };
 }
 
+macro_rules! decl_variant_type {
+    (
+        pub enum VariantType, VariantDispatch {
+            $(
+                $variant:ident $( ($inner:ty) )? = $c_const:path,
+            )*
+        }
+    ) => {
+        #[repr(u32)]
+        #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
+        pub enum VariantType {
+            $(
+                $variant = $c_const as u32,
+            )*
+        }
+
+        /// Rust enum associating each primitive variant type to its value.
+        ///
+        /// For `Variant`s containing objects, the original `Variant` is returned unchanged, due to
+        /// the limitations of statically-determined memory management.
+        #[repr(u32)]
+        pub enum VariantDispatch {
+            $(
+                $variant $( ($inner) )?,
+            )*
+        }
+
+        impl<'a> From<&'a Variant> for VariantDispatch {
+            #[inline]
+            fn from(v: &'a Variant) -> Self {
+                match v.get_type() {
+                    $(
+                        VariantType::$variant => {
+                            variant_dispatch_arm!(v, $variant $( ($inner) )?)
+                        },
+                    )*
+                }
+            }
+        }
+    }
+}
+
+decl_variant_type!(
+    pub enum VariantType, VariantDispatch {
+        Nil = sys::godot_variant_type_GODOT_VARIANT_TYPE_NIL,
+        Bool(bool) = sys::godot_variant_type_GODOT_VARIANT_TYPE_BOOL,
+        I64(i64) = sys::godot_variant_type_GODOT_VARIANT_TYPE_INT,
+        F64(f64) = sys::godot_variant_type_GODOT_VARIANT_TYPE_REAL,
+        GodotString(GodotString) = sys::godot_variant_type_GODOT_VARIANT_TYPE_STRING,
+        Vector2(Vector2) = sys::godot_variant_type_GODOT_VARIANT_TYPE_VECTOR2,
+        Rect2(Rect2) = sys::godot_variant_type_GODOT_VARIANT_TYPE_RECT2,
+        Vector3(Vector3) = sys::godot_variant_type_GODOT_VARIANT_TYPE_VECTOR3,
+        Transform2D(Transform2D) = sys::godot_variant_type_GODOT_VARIANT_TYPE_TRANSFORM2D,
+        Plane(Plane) = sys::godot_variant_type_GODOT_VARIANT_TYPE_PLANE,
+        Quat(Quat) = sys::godot_variant_type_GODOT_VARIANT_TYPE_QUAT,
+        Aabb(Aabb) = sys::godot_variant_type_GODOT_VARIANT_TYPE_AABB,
+        Basis(Basis) = sys::godot_variant_type_GODOT_VARIANT_TYPE_BASIS,
+        Transform(Transform) = sys::godot_variant_type_GODOT_VARIANT_TYPE_TRANSFORM,
+        Color(Color) = sys::godot_variant_type_GODOT_VARIANT_TYPE_COLOR,
+        NodePath(NodePath) = sys::godot_variant_type_GODOT_VARIANT_TYPE_NODE_PATH,
+        Rid(Rid) = sys::godot_variant_type_GODOT_VARIANT_TYPE_RID,
+        Object(Variant) = sys::godot_variant_type_GODOT_VARIANT_TYPE_OBJECT,
+        Dictionary(Dictionary) = sys::godot_variant_type_GODOT_VARIANT_TYPE_DICTIONARY,
+        VariantArray(VariantArray) = sys::godot_variant_type_GODOT_VARIANT_TYPE_ARRAY,
+        ByteArray(ByteArray) = sys::godot_variant_type_GODOT_VARIANT_TYPE_POOL_BYTE_ARRAY,
+        Int32Array(Int32Array) = sys::godot_variant_type_GODOT_VARIANT_TYPE_POOL_INT_ARRAY,
+        Float32Array(Float32Array) = sys::godot_variant_type_GODOT_VARIANT_TYPE_POOL_REAL_ARRAY,
+        StringArray(StringArray) = sys::godot_variant_type_GODOT_VARIANT_TYPE_POOL_STRING_ARRAY,
+        Vector2Array(Vector2Array) = sys::godot_variant_type_GODOT_VARIANT_TYPE_POOL_VECTOR2_ARRAY,
+        Vector3Array(Vector3Array) = sys::godot_variant_type_GODOT_VARIANT_TYPE_POOL_VECTOR3_ARRAY,
+        ColorArray(ColorArray) = sys::godot_variant_type_GODOT_VARIANT_TYPE_POOL_COLOR_ARRAY,
+    }
+);
+
 impl VariantType {
     #[doc(hidden)]
     #[inline]
@@ -674,6 +725,24 @@ impl Variant {
         unsafe { VariantType::from_sys((get_api().godot_variant_get_type)(&self.0)) }
     }
 
+    /// Converts this variant to a primitive value depending on its type.
+    ///
+    /// # Examples
+    ///
+    /// ```ignore
+    /// let variant = 42.to_variant();
+    /// let number_as_float = match variant.dispatch() {
+    ///     VariantDispatch::I64(i) => i as f64,
+    ///     VariantDispatch::F64(f) => f,
+    ///     _ => panic!("not a number"),
+    /// };
+    /// approx::assert_relative_eq!(42.0, number_as_float);
+    /// ```
+    #[inline]
+    pub fn dispatch(&self) -> VariantDispatch {
+        self.into()
+    }
+
     /// Returns true if this is an empty variant.
     #[inline]
     pub fn is_nil(&self) -> bool {
@@ -1928,4 +1997,28 @@ godot_test!(
         let tuple = <(i64, i64)>::from_variant(&variant);
         assert_eq!(Ok((42, 54)), tuple);
     }
+
+    test_variant_dispatch {
+        let variant = 42i64.to_variant();
+        if let VariantDispatch::I64(i) = variant.dispatch() {
+            assert_eq!(42, i);
+        } else {
+            panic!("incorrect dispatch type");
+        };
+
+        let variant = true.to_variant();
+        if let VariantDispatch::Bool(b) = variant.dispatch() {
+            assert!(b);
+        } else {
+            panic!("incorrect dispatch type");
+        };
+
+        let variant = 42.to_variant();
+        let number_as_float = match variant.dispatch() {
+            VariantDispatch::I64(i) => i as f64,
+            VariantDispatch::F64(f) => f,
+            _ => panic!("not a number"),
+        };
+        approx::assert_relative_eq!(42.0, number_as_float);
+    }
 );

gdnative/src/prelude.rs

@@ -2,8 +2,8 @@ pub use gdnative_core::core_types::{
     self, error::GodotError, Aabb, Angle, Basis, ByteArray, Color, ColorArray, Dictionary,
     Float32Array, GodotString, Int32Array, NodePath, Plane, Point2, Point3, Quat, Rect2, Rid,
     Rotation2D, Rotation3D, Size2, StringArray, StringName, Transform, Transform2D, TypedArray,
-    Variant, VariantArray, VariantOperator, VariantType, Vector2, Vector2Array, Vector3,
-    Vector3Array,
+    Variant, VariantArray, VariantDispatch, VariantOperator, VariantType, Vector2, Vector2Array,
+    Vector3, Vector3Array,
 };
 pub use gdnative_core::core_types::{
     FromVariant, FromVariantError, OwnedToVariant, ToVariant, ToVariantEq, Vector2Godot,

test/src/lib.rs

@@ -39,6 +39,7 @@ pub extern "C" fn run_tests(
     status &= gdnative::core_types::test_variant_result();
     status &= gdnative::core_types::test_to_variant_iter();
     status &= gdnative::core_types::test_variant_tuple();
+    status &= gdnative::core_types::test_variant_dispatch();
 
     status &= gdnative::core_types::test_byte_array_access();
     status &= gdnative::core_types::test_byte_array_debug();