Deprecate EngineEnum::godot_name()

Author: Bromeon

godot-core/src/meta/inspect.rs

@@ -18,7 +18,10 @@ pub struct EnumConstant<T: Copy + 'static> {
     value: T,
 }
 
-impl<T: Copy + 'static> EnumConstant<T> {
+impl<T> EnumConstant<T>
+where
+    T: Copy + Eq + PartialEq + 'static,
+{
     /// Creates a new enum constant metadata entry.
     pub(crate) const fn new(rust_name: &'static str, godot_name: &'static str, value: T) -> Self {
         Self {

godot-core/src/obj/traits.rs

@@ -201,6 +201,25 @@ pub trait EngineEnum: Copy {
     /// The equivalent name of the enumerator, as specified in Godot.
     ///
     /// If the value does not match one of the known enumerators, the empty string is returned.
+    ///
+    /// # Deprecation
+    /// Design change is due to the fact that Godot enums may have multiple constants with the same ordinal value, and `godot_name()` cannot
+    /// always return a unique name for it. So there are cases where this method returns unexpected results.
+    ///
+    /// To keep the old -- possibly incorrect -- behavior, you can write the following function. However, it runs in linear rather than constant
+    /// time (which is often OK, given that there are very few constants per enum).
+    /// ```
+    /// use godot::obj::EngineEnum;
+    ///
+    /// fn godot_name<T: EngineEnum + Eq + PartialEq + 'static>(value: T) -> &'static str {
+    ///     T::all_constants()
+    ///         .iter()
+    ///         .find(|c| c.value() == value)
+    ///         .map(|c| c.godot_name())
+    ///         .unwrap_or("") // Previous behavior.
+    /// }
+    /// ```
+    #[deprecated = "Moved to introspection API, see `EngineEnum::all_constants()` and `EnumConstant::godot_name()`"]
     fn godot_name(&self) -> &'static str;
 
     /// Returns a slice of distinct enum values.

itest/rust/src/object_tests/enum_test.rs

@@ -12,7 +12,7 @@ use godot::classes::mesh::PrimitiveType;
 use godot::classes::window::LayoutDirection;
 use godot::classes::{time, ArrayMesh};
 use godot::global::{Key, Orientation};
-use godot::obj::NewGd;
+use godot::obj::{EngineEnum, NewGd};
 use std::collections::HashSet;
 
 #[itest]
@@ -92,6 +92,29 @@ fn enum_as_str() {
 
 #[itest]
 fn enum_godot_name() {
+    use godot::obj::EngineEnum;
+    assert_eq!(
+        godot_name(Orientation::VERTICAL),
+        Orientation::VERTICAL.as_str()
+    );
+    assert_eq!(
+        godot_name(Orientation::HORIZONTAL),
+        Orientation::HORIZONTAL.as_str()
+    );
+
+    assert_eq!(godot_name(Key::NONE), "KEY_NONE");
+    assert_eq!(godot_name(Key::SPECIAL), "KEY_SPECIAL");
+    assert_eq!(godot_name(Key::ESCAPE), "KEY_ESCAPE");
+    assert_eq!(godot_name(Key::TAB), "KEY_TAB");
+    assert_eq!(godot_name(Key::A), "KEY_A");
+
+    // Unknown enumerators (might come from the future).
+    assert_eq!(godot_name(Key::from_ord(1234)), "");
+}
+
+#[itest]
+#[expect(deprecated)]
+fn enum_godot_name_deprecated() {
     use godot::obj::EngineEnum;
     assert_eq!(
         Orientation::VERTICAL.godot_name(),
@@ -107,4 +130,15 @@ fn enum_godot_name() {
     assert_eq!(Key::ESCAPE.godot_name(), "KEY_ESCAPE");
     assert_eq!(Key::TAB.godot_name(), "KEY_TAB");
     assert_eq!(Key::A.godot_name(), "KEY_A");
+
+    // Unknown enumerators (might come from the future).
+    assert_eq!(Key::from_ord(1234).godot_name(), "");
+}
+
+fn godot_name<T: EngineEnum + Eq + PartialEq + 'static>(value: T) -> &'static str {
+    T::all_constants()
+        .iter()
+        .find(|c| c.value() == value)
+        .map(|c| c.godot_name())
+        .unwrap_or("") // Previous behavior.
 }