Add Variant::object_id()

Author: Bromeon

godot-core/src/builtin/variant/mod.rs

@@ -46,14 +46,14 @@ impl Variant {
 
     /// Create a variant holding a non-nil value.
     ///
-    /// Equivalent to `value.to_variant()`.
+    /// Equivalent to [`value.to_variant()`][ToGodot::to_variant], but consumes the argument.
     pub fn from<T: ToGodot>(value: T) -> Self {
         value.to_variant()
     }
 
     /// ⚠️ Convert to type `T`, panicking on failure.
     ///
-    /// Equivalent to `T::from_variant(&self)`.
+    /// Equivalent to [`T::from_variant(&self)`][FromGodot::from_variant].
     ///
     /// # Panics
     /// When this variant holds a different type.
@@ -63,14 +63,14 @@ impl Variant {
 
     /// Convert to type `T`, returning `Err` on failure.
     ///
-    /// Equivalent to `T::try_from_variant(&self)`.
+    /// Equivalent to [`T::try_from_variant(&self)`][FromGodot::try_from_variant].
     pub fn try_to<T: FromGodot>(&self) -> Result<T, ConvertError> {
         T::try_from_variant(self)
     }
 
     /// Checks whether the variant is empty (`null` value in GDScript).
     ///
-    /// See also [`Self::get_type`].
+    /// See also [`get_type()`][Self::get_type].
     pub fn is_nil(&self) -> bool {
         // Use get_type() rather than sys_type(), to also cover nullptr OBJECT as NIL
         self.get_type() == VariantType::NIL
@@ -79,8 +79,8 @@ impl Variant {
     /// Returns the type that is currently held by this variant.
     ///
     /// If this variant holds a type `Object` but no instance (represented as a null object pointer), then `Nil` will be returned for
-    /// consistency. This may deviate from Godot behavior -- for example, calling `Node::get_node_or_null()` with an invalid
-    /// path returns a variant that has type `Object` but acts like `Nil` for all practical purposes.
+    /// consistency. This may deviate from Godot behavior -- for example, calling [`Node::get_node_or_null()`][crate::classes::Node::get_node_or_null]
+    ///  with an invalid path returns a variant that has type `Object` but acts like `Nil` for all practical purposes.
     pub fn get_type(&self) -> VariantType {
         let sys_type = self.sys_type();
 
@@ -106,6 +106,20 @@ impl Variant {
         }
     }
 
+    /// For variants holding an object, returns the object's instance ID.
+    ///
+    /// If the variant is not an object, returns `None`.
+    ///
+    /// If the object is dead, the instance ID is still returned. Use [`Variant::try_to::<Gd<T>>()`][Self::try_to]
+    /// to retrieve only live objects.
+    #[cfg(since_api = "4.4")]
+    pub fn object_id(&self) -> Option<crate::obj::InstanceId> {
+        // SAFETY: safe to call for non-object variants (returns 0).
+        let raw_id: u64 = unsafe { interface_fn!(variant_get_object_instance_id)(self.var_sys()) };
+
+        crate::obj::InstanceId::try_from_u64(raw_id)
+    }
+
     /// ⚠️ Calls the specified `method` with the given `args`.
     ///
     /// Supports `Object` as well as built-ins with methods (e.g. `Array`, `Vector3`, `GString`, etc.).

itest/rust/src/builtin_tests/containers/variant_test.rs

@@ -186,6 +186,27 @@ fn variant_get_type() {
     assert_eq!(variant.get_type(), VariantType::BASIS)
 }
 
+#[cfg(since_api = "4.4")]
+#[itest]
+fn variant_object_id() {
+    let variant = Variant::nil();
+    assert_eq!(variant.object_id(), None);
+
+    let variant = Variant::from(77);
+    assert_eq!(variant.object_id(), None);
+
+    let node = Node::new_alloc();
+    let id = node.instance_id();
+
+    let variant = node.to_variant();
+    assert_eq!(variant.object_id(), Some(id));
+
+    node.free();
+
+    // When freed, variant still returns the object ID.
+    assert_eq!(variant.object_id(), Some(id));
+}
+
 #[itest]
 fn variant_equal() {
     assert_eq!(Variant::nil(), ().to_variant());