Rollup merge of #142328 - sorairolake:feature/uint-bit-width, r=tgross35

feat: Add `bit_width` for unsigned integer types

- Accepted ACP: rust-lang/libs-team#598
- Tracking issue: rust-lang/rust#142326

This PR adds methods to the primitive unsigned integer types that return the minimum number of bits required to represent an unsigned integer.

3 files changed, 33 insertions, 0 deletions

diff --git a/library/core/src/num/uint_macros.rs b/library/core/src/num/uint_macros.rs
index 5f82e6af86b..4ee0e7326b3 100644
--- a/library/core/src/num/uint_macros.rs
+++ b/library/core/src/num/uint_macros.rs
@@ -213,6 +213,30 @@ macro_rules! uint_impl {
             (!self).trailing_zeros()
         }
 
+        /// Returns the minimum number of bits required to represent `self`.
+        ///
+        /// This method returns zero if `self` is zero.
+        ///
+        /// # Examples
+        ///
+        /// Basic usage:
+        ///
+        /// ```
+        /// #![feature(uint_bit_width)]
+        ///
+        #[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".bit_width(), 0);")]
+        #[doc = concat!("assert_eq!(0b111_", stringify!($SelfT), ".bit_width(), 3);")]
+        #[doc = concat!("assert_eq!(0b1110_", stringify!($SelfT), ".bit_width(), 4);")]
+        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.bit_width(), ", stringify!($BITS), ");")]
+        /// ```
+        #[unstable(feature = "uint_bit_width", issue = "142326")]
+        #[must_use = "this returns the result of the operation, \
+                      without modifying the original"]
+        #[inline(always)]
+        pub const fn bit_width(self) -> u32 {
+            Self::BITS - self.leading_zeros()
+        }
+
         /// Returns `self` with only the most significant bit set, or `0` if
         /// the input is `0`.
         ///
diff --git a/library/coretests/tests/lib.rs b/library/coretests/tests/lib.rs
index 92b920dd775..5449132413b 100644
--- a/library/coretests/tests/lib.rs
+++ b/library/coretests/tests/lib.rs
@@ -94,6 +94,7 @@
 #![feature(try_blocks)]
 #![feature(try_find)]
 #![feature(try_trait_v2)]
+#![feature(uint_bit_width)]
 #![feature(unsize)]
 #![feature(unwrap_infallible)]
 // tidy-alphabetical-end
diff --git a/library/coretests/tests/num/uint_macros.rs b/library/coretests/tests/num/uint_macros.rs
index 6f3d160964f..7e02027bdd6 100644
--- a/library/coretests/tests/num/uint_macros.rs
+++ b/library/coretests/tests/num/uint_macros.rs
@@ -72,6 +72,14 @@ macro_rules! uint_module {
                 assert_eq_const_safe!(u32: X.trailing_ones(), 0);
             }
 
+            fn test_bit_width() {
+                assert_eq_const_safe!(u32: A.bit_width(), 6);
+                assert_eq_const_safe!(u32: B.bit_width(), 6);
+                assert_eq_const_safe!(u32: C.bit_width(), 7);
+                assert_eq_const_safe!(u32: _0.bit_width(), 0);
+                assert_eq_const_safe!(u32: _1.bit_width(), $T::BITS);
+            }
+
             fn test_rotate() {
                 assert_eq_const_safe!($T: A.rotate_left(6).rotate_right(2).rotate_right(4), A);
                 assert_eq_const_safe!($T: B.rotate_left(3).rotate_left(2).rotate_right(5), B);