Add wrapper for from_instance_id

Co-authored-by: Jan Haller <[email protected]>

Author: toasteater

gdnative-core/src/object.rs

@@ -151,6 +151,36 @@ pub unsafe trait GodotObject: Sized + crate::private::godot_object::Sealed {
     {
         Ref::from_sys(self.as_raw().sys())
     }
+
+    /// Recovers a instance ID previously returned by `Object::get_instance_id` if the object is
+    /// still alive. See also `TRef::try_from_instance_id`.
+    ///
+    /// # Safety
+    ///
+    /// During the entirety of `'a`, the thread from which `try_from_instance_id` is called must
+    /// have exclusive access to the underlying object, if it is still alive.
+    #[inline]
+    unsafe fn try_from_instance_id<'a>(id: i64) -> Option<TRef<'a, Self, Shared>> {
+        TRef::try_from_instance_id(id)
+    }
+
+    /// Recovers a instance ID previously returned by `Object::get_instance_id` if the object is
+    /// still alive, and panics otherwise. This does **NOT** guarantee that the resulting
+    /// reference is safe to use.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the given id refers to a destroyed object. For a non-panicking version, see
+    /// `try_from_instance_id`.
+    ///
+    /// # Safety
+    ///
+    /// During the entirety of `'a`, the thread from which `try_from_instance_id` is called must
+    /// have exclusive access to the underlying object, if it is still alive.
+    #[inline]
+    unsafe fn from_instance_id<'a>(id: i64) -> TRef<'a, Self, Shared> {
+        TRef::from_instance_id(id)
+    }
 }
 
 /// Marker trait for API types that are subclasses of another type. This trait is implemented
@@ -892,6 +922,41 @@ where
     }
 }
 
+impl<'a, T: GodotObject> TRef<'a, T, Shared> {
+    /// Recovers a instance ID previously returned by `Object::get_instance_id` if the object is
+    /// still alive.
+    ///
+    /// # Safety
+    ///
+    /// During the entirety of `'a`, the thread from which `try_from_instance_id` is called must
+    /// have exclusive access to the underlying object, if it is still alive.
+    #[inline]
+    pub unsafe fn try_from_instance_id(id: i64) -> Option<Self> {
+        let api = get_api();
+        let ptr = NonNull::new((api.godot_instance_from_id)(id as sys::godot_int))?;
+        let raw = RawObject::try_from_sys_ref(ptr)?;
+        Some(TRef::new(T::cast_ref(raw)))
+    }
+
+    /// Recovers a instance ID previously returned by `Object::get_instance_id` if the object is
+    /// still alive, and panics otherwise. This does **NOT** guarantee that the resulting
+    /// reference is safe to use.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the given id refers to a destroyed object. For a non-panicking version, see
+    /// `try_from_instance_id`.
+    ///
+    /// # Safety
+    ///
+    /// During the entirety of `'a`, the thread from which `try_from_instance_id` is called must
+    /// have exclusive access to the underlying object, if it is still alive.
+    #[inline]
+    pub unsafe fn from_instance_id(id: i64) -> Self {
+        Self::try_from_instance_id(id).expect("instance should be alive")
+    }
+}
+
 /// Trait for safe conversion from Godot object references into API method arguments. This is
 /// a sealed trait with no public interface.
 ///

test/src/lib.rs

@@ -57,6 +57,7 @@ pub extern "C" fn run_tests(
     status &= test_constructor();
     status &= test_underscore_method_binding();
     status &= test_rust_class_construction();
+    status &= test_from_instance_id();
 
     status &= test_derive::run_tests();
     status &= test_free_ub::run_tests();
@@ -207,6 +208,61 @@ impl OptionalArgs {
     }
 }
 
+fn test_from_instance_id() -> bool {
+    println!(" -- test_from_instance_id");
+
+    let ok = std::panic::catch_unwind(|| {
+        assert!(unsafe { Node::try_from_instance_id(22).is_none() });
+        assert!(unsafe { Node::try_from_instance_id(42).is_none() });
+        assert!(unsafe { Node::try_from_instance_id(503).is_none() });
+
+        let instance_id;
+
+        {
+            let foo = unsafe { Node::new().into_shared().assume_safe() };
+            foo.set_name("foo");
+
+            instance_id = foo.get_instance_id();
+
+            assert!(unsafe { Reference::try_from_instance_id(instance_id).is_none() });
+
+            let reconstructed = unsafe { Node::from_instance_id(instance_id) };
+            assert_eq!("foo", reconstructed.name().to_string());
+
+            unsafe { foo.assume_unique().free() };
+        }
+
+        assert!(unsafe { Node::try_from_instance_id(instance_id).is_none() });
+
+        let instance_id;
+
+        {
+            let foo = Reference::new().into_shared();
+            let foo = unsafe { foo.assume_safe() };
+            foo.set_meta("foo", "bar");
+
+            instance_id = foo.get_instance_id();
+
+            assert!(unsafe { Node::try_from_instance_id(instance_id).is_none() });
+
+            let reconstructed = unsafe { Reference::from_instance_id(instance_id) };
+            assert_eq!(
+                "bar",
+                String::from_variant(&reconstructed.get_meta("foo")).unwrap()
+            );
+        }
+
+        assert!(unsafe { Reference::try_from_instance_id(instance_id).is_none() });
+    })
+    .is_ok();
+
+    if !ok {
+        gdnative::godot_error!("   !! Test test_from_instance_id failed");
+    }
+
+    ok
+}
+
 fn init(handle: InitHandle) {
     handle.add_class::<Foo>();
     handle.add_class::<OptionalArgs>();