EngineBitfield::all_constants()

Author: Bromeon

godot-codegen/src/generator/enums.rs

@@ -227,6 +227,8 @@ fn make_enum_engine_trait_impl(enum_: &Enum, enum_bitmask: Option<&RustTy>) -> T
     if enum_.is_bitfield {
         // Bitfields: u64, assume any combination is valid.
 
+        let constants_function = make_all_constants_function(enum_);
+
         quote! {
             // We may want to add this in the future.
             //
@@ -242,6 +244,8 @@ fn make_enum_engine_trait_impl(enum_: &Enum, enum_bitmask: Option<&RustTy>) -> T
                 fn ord(self) -> u64 {
                     self.ord
                 }
+
+                #constants_function
             }
         }
     } else if enum_.is_exhaustive {
@@ -332,33 +336,49 @@ fn make_enum_values_and_constants_functions(enum_: &Enum) -> TokenStream {
     let name = &enum_.name;
 
     let mut distinct_values = Vec::new();
-    let mut all_constants = Vec::new();
     let mut seen_ordinals = HashSet::new();
 
     for (index, enumerator) in enum_.enumerators.iter().enumerate() {
         let constant = &enumerator.name;
-        let rust_name = enumerator.name.to_string();
-        let godot_name = enumerator.godot_name.to_string();
         let ordinal = &enumerator.value;
 
-        // all_constants() includes every constant unconditionally.
-        all_constants.push(quote! {
-            crate::meta::inspect::EnumConstant::new(#rust_name, #godot_name, #ordinal, #name::#constant)
-        });
-
         // values() contains value only if distinct (first time seen) and not MAX.
         if enum_.max_index != Some(index) && seen_ordinals.insert(ordinal.clone()) {
             distinct_values.push(quote! { #name::#constant });
         }
     }
 
-    quote! {
+    let values_function = quote! {
         fn values() -> &'static [Self] {
             &[
                 #( #distinct_values ),*
             ]
         }
+    };
+
+    let all_constants_function = make_all_constants_function(enum_);
 
+    quote! {
+        #values_function
+        #all_constants_function
+    }
+}
+
+/// Creates a shared `all_constants()` implementation for enums and bitfields.
+fn make_all_constants_function(enum_: &Enum) -> TokenStream {
+    let name = &enum_.name;
+
+    let all_constants = enum_.enumerators.iter().map(|enumerator| {
+        let ident = &enumerator.name;
+        let rust_name = enumerator.name.to_string();
+        let godot_name = enumerator.godot_name.to_string();
+
+        quote! {
+            crate::meta::inspect::EnumConstant::new(#rust_name, #godot_name, #name::#ident)
+        }
+    });
+
+    quote! {
         fn all_constants() -> &'static [crate::meta::inspect::EnumConstant<#name>] {
             const {
                 &[

godot-core/src/builtin/vectors/vector_axis.rs

@@ -69,7 +69,6 @@ macro_rules! impl_vector_axis_enum {
                         EnumConstant::new(
                             stringify!($axis),
                             concat!("AXIS_", stringify!($axis)),
-                            $AxisEnum::$axis as i32,
                             $AxisEnum::$axis
                         ),
                     )+

godot-core/src/meta/inspect.rs

@@ -7,34 +7,32 @@
 
 //! Introspection metadata for Godot engine types.
 
-/// Metadata for a single enum constant.
+/// Metadata for a single enum or bitfield constant.
+///
+/// Returned by [`EngineEnum::all_constants()`][crate::obj::EngineEnum::all_constants] and
+/// [`EngineBitfield::all_constants()`][crate::obj::EngineBitfield::all_constants].
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct EnumConstant<T: Copy + 'static> {
     rust_name: &'static str,
     godot_name: &'static str,
-    ord: i32,
     value: T,
 }
 
 impl<T: Copy + 'static> EnumConstant<T> {
     /// Creates a new enum constant metadata entry.
-    pub(crate) const fn new(
-        rust_name: &'static str,
-        godot_name: &'static str,
-        ord: i32,
-        value: T,
-    ) -> Self {
+    pub(crate) const fn new(rust_name: &'static str, godot_name: &'static str, value: T) -> Self {
         Self {
             rust_name,
             godot_name,
-            ord,
             value,
         }
     }
 
-    /// Rust name of the enum variant, usually without Prefix (e.g. `"ESCAPE"` for `Key::ESCAPE`).
+    /// Rust name of the constant, usually without prefix (e.g. `"ESCAPE"` for `Key::ESCAPE`).
     ///
-    /// This is returned by [`EngineEnum::as_str()`](crate::obj::EngineEnum::as_str()).
+    /// For enums, this is the value returned by [`EngineEnum::as_str()`](crate::obj::EngineEnum::as_str()) **if the value is unique.**
+    /// If multiple enum values share the same ordinal, then this function will return each one separately, while `as_str()` will return the
+    /// first one.
     pub const fn rust_name(&self) -> &'static str {
         self.rust_name
     }
@@ -44,12 +42,9 @@ impl<T: Copy + 'static> EnumConstant<T> {
         self.godot_name
     }
 
-    /// Ordinal value of this enum variant.
-    pub const fn ord(&self) -> i32 {
-        self.ord
-    }
-
-    /// The enum value itself.
+    /// The Rust value itself.
+    ///
+    /// Use `value().ord()` to get the ordinal value.
     pub const fn value(&self) -> T {
         self.value
     }

godot-core/src/obj/traits.rs

@@ -190,10 +190,10 @@ pub trait EngineEnum: Copy {
 
     /// The name of the enumerator, as it appears in Rust.
     ///
-    /// Note that **this may not match the Rust constant name!** In case of multiple constants with the same ordinal value, this method returns
-    /// the first one in the order of definition. For example, `LayoutDirection::LOCALE.as_str()` (ord 1) returns `"APPLICATION_LOCALE"`, because
-    /// that happens to be the first constant with ordinal `1`. See [`all_constants()`][Self::all_constants] for a more robust and general
-    /// approach to introspection of enum constants.
+    /// Note that **this may not match the Rust constant name.** In case of multiple constants with the same ordinal value, this method returns
+    /// the first one in the order of definition. For example, [`LayoutDirection::LOCALE.as_str()`][crate::classes::window::LayoutDirection::LOCALE]
+    /// (ord 1) returns `"APPLICATION_LOCALE"`, because that happens to be the first constant with ordinal `1`.
+    /// See [`all_constants()`][Self::all_constants] for a more robust and general approach to introspection of enum constants.
     ///
     /// If the value does not match one of the known enumerators, the empty string is returned.
     fn as_str(&self) -> &'static str;
@@ -205,9 +205,10 @@ pub trait EngineEnum: Copy {
 
     /// Returns a slice of distinct enum values.
     ///
-    /// This excludes MAX constants and deduplicates aliases, providing only meaningful enum values.
+    /// This excludes `MAX` constants at the end (existing only to express the number of enumerators) and deduplicates aliases,
+    /// providing only meaningful enum values. See [`all_constants()`][Self::all_constants] for a complete list of all constants.
     ///
-    /// This enables iteration over distinct enum variants:
+    /// Enables iteration over distinct enum variants:
     /// ```no_run
     /// use godot::classes::window;
     /// use godot::obj::EngineEnum;
@@ -220,18 +221,19 @@ pub trait EngineEnum: Copy {
 
     /// Returns metadata for all enum constants.
     ///
-    /// This includes all constants as they appear in the enum definition, including duplicates and MAX constants.
+    /// This includes all constants as they appear in the enum definition, including duplicates and `MAX` constants.
+    /// For a list of useful, distinct values, use [`values()`][Self::values].
     ///
-    /// This enables complete introspection and debugging:
+    /// Enables introspection of available constants:
     /// ```no_run
     /// use godot::classes::window;
     /// use godot::obj::EngineEnum;
     ///
     /// for constant in window::Mode::all_constants() {
-    ///     println!("* {}: {} (ord: {})",
+    ///     println!("* window::Mode.{} (original {}) has ordinal value {}.",
     ///         constant.rust_name(),
     ///         constant.godot_name(),
-    ///         constant.ord()
+    ///         constant.value().ord()
     ///     );
     /// }
     /// ```
@@ -254,6 +256,25 @@ pub trait EngineBitfield: Copy {
     fn is_set(self, flag: Self) -> bool {
         self.ord() & flag.ord() != 0
     }
+
+    /// Returns metadata for all bitfield constants.
+    ///
+    /// This includes all constants as they appear in the bitfield definition.
+    ///
+    /// Enables introspection of available constants:
+    /// ```no_run
+    /// use godot::global::KeyModifierMask;
+    /// use godot::obj::EngineBitfield;
+    ///
+    /// for constant in KeyModifierMask::all_constants() {
+    ///     println!("* KeyModifierMask.{} (original {}) has ordinal value {}.",
+    ///         constant.rust_name(),
+    ///         constant.godot_name(),
+    ///         constant.value().ord()
+    ///     );
+    /// }
+    /// ```
+    fn all_constants() -> &'static [EnumConstant<Self>];
 }
 
 /// Trait for enums that can be used as indices in arrays.

itest/rust/src/engine_tests/engine_enum_test.rs

@@ -97,7 +97,7 @@ fn enum_values_duplicates() {
         }
 
         assert_eq!(c.value(), value);
-        assert_eq!(c.ord(), ord);
+        assert_eq!(c.value().ord(), ord);
     }
 
     assert_eq!(InlineAlignment::values(), &expected_distinct_values);
@@ -156,26 +156,38 @@ fn enum_all_constants() {
     let first = constants[0];
     assert_eq!(first.rust_name(), "TOP_TO");
     assert_eq!(first.godot_name(), "INLINE_ALIGNMENT_TOP_TO");
-    assert_eq!(first.ord(), 0);
     assert_eq!(first.value(), InlineAlignment::TOP_TO);
+    assert_eq!(first.value().ord(), 0);
 
     // Check specific constants at known indices, with equal ordinals.
     let known_a = constants[2];
     let known_b = constants[11];
 
-    assert_eq!(known_a.ord(), 3);
     assert_eq!(known_a.rust_name(), "BASELINE_TO");
     assert_eq!(known_a.godot_name(), "INLINE_ALIGNMENT_BASELINE_TO");
     assert_eq!(known_a.value(), InlineAlignment::BASELINE_TO);
+    assert_eq!(known_a.value().ord(), 3);
 
-    assert_eq!(known_b.ord(), 3);
     assert_eq!(known_b.rust_name(), "IMAGE_MASK");
     assert_eq!(known_b.godot_name(), "INLINE_ALIGNMENT_IMAGE_MASK");
     assert_eq!(known_b.value(), InlineAlignment::IMAGE_MASK);
+    assert_eq!(known_b.value().ord(), 3);
 
     // "Front-end" values are equal, too.
     assert_eq!(
         InlineAlignment::IMAGE_MASK.ord(),
         InlineAlignment::BASELINE_TO.ord()
     );
 }
+
+#[itest]
+fn bitfield_all_constants() {
+    let shift_constant = KeyModifierMask::all_constants()
+        .iter()
+        .find(|c| c.rust_name() == "SHIFT")
+        .expect("SHIFT constant should exist");
+
+    assert_eq!(shift_constant.godot_name(), "KEY_MASK_SHIFT");
+    assert_eq!(shift_constant.value(), KeyModifierMask::SHIFT);
+    assert_eq!(shift_constant.value().ord(), 1 << 25);
+}

itest/rust/src/object_tests/enum_test.rs

@@ -9,6 +9,7 @@ use crate::framework::itest;
 use godot::builtin::varray;
 use godot::classes::input::CursorShape;
 use godot::classes::mesh::PrimitiveType;
+use godot::classes::window::LayoutDirection;
 use godot::classes::{time, ArrayMesh};
 use godot::global::{Key, Orientation};
 use godot::obj::NewGd;
@@ -84,6 +85,9 @@ fn enum_as_str() {
     assert_eq!(Key::ESCAPE.as_str(), "ESCAPE");
     assert_eq!(Key::TAB.as_str(), "TAB");
     assert_eq!(Key::A.as_str(), "A");
+
+    #[cfg(since_api = "4.4")] // Deprecated in Godot, LOCALE is now alias for APPLICATION_LOCALE.
+    assert_eq!(LayoutDirection::LOCALE.as_str(), "APPLICATION_LOCALE");
 }
 
 #[itest]