Rollup merge of rust-lang#128103 - folkertdev:unsigned-int-is-multiple-of, r=Amanieu

add `is_multiple_of` for unsigned integer types

tracking issue: rust-lang#128101

This adds the `.is_multiple_of` method on unsigned integers.

Returns `true` if `self` is an integer multiple of `rhs`, and false otherwise.

This function is equivalent to `self % rhs == 0`, except that it will not panic for `rhs == 0`. Instead, `0.is_multiple_of(0) == true`, and for any non-zero `n`, `n.is_multiple_of(0) == false`.

Author: GuillaumeGomez

core/src/num/uint_macros.rs

@@ -2853,6 +2853,35 @@ macro_rules! uint_impl {
             }
         }
 
+        /// Returns `true` if `self` is an integer multiple of `rhs`, and false otherwise.
+        ///
+        /// This function is equivalent to `self % rhs == 0`, except that it will not panic
+        /// for `rhs == 0`. Instead, `0.is_multiple_of(0) == true`, and for any non-zero `n`,
+        /// `n.is_multiple_of(0) == false`.
+        ///
+        /// # Examples
+        ///
+        /// Basic usage:
+        ///
+        /// ```
+        /// #![feature(unsigned_is_multiple_of)]
+        #[doc = concat!("assert!(6_", stringify!($SelfT), ".is_multiple_of(2));")]
+        #[doc = concat!("assert!(!5_", stringify!($SelfT), ".is_multiple_of(2));")]
+        ///
+        #[doc = concat!("assert!(0_", stringify!($SelfT), ".is_multiple_of(0));")]
+        #[doc = concat!("assert!(!6_", stringify!($SelfT), ".is_multiple_of(0));")]
+        /// ```
+        #[unstable(feature = "unsigned_is_multiple_of", issue = "128101")]
+        #[must_use]
+        #[inline]
+        #[rustc_inherit_overflow_checks]
+        pub const fn is_multiple_of(self, rhs: Self) -> bool {
+            match rhs {
+                0 => self == 0,
+                _ => self % rhs == 0,
+            }
+        }
+
         /// Returns `true` if and only if `self == 2^k` for some `k`.
         ///
         /// # Examples

core/tests/lib.rs

@@ -59,6 +59,7 @@
 #![feature(num_midpoint)]
 #![feature(offset_of_nested)]
 #![feature(isqrt)]
+#![feature(unsigned_is_multiple_of)]
 #![feature(step_trait)]
 #![feature(str_internals)]
 #![feature(std_internals)]

core/tests/num/uint_macros.rs

@@ -260,6 +260,14 @@ macro_rules! uint_module {
                 assert_eq!(MAX.checked_next_multiple_of(2), None);
             }
 
+            #[test]
+            fn test_is_next_multiple_of() {
+                assert!((12 as $T).is_multiple_of(4));
+                assert!(!(12 as $T).is_multiple_of(5));
+                assert!((0 as $T).is_multiple_of(0));
+                assert!(!(12 as $T).is_multiple_of(0));
+            }
+
             #[test]
             fn test_carrying_add() {
                 assert_eq!($T::MAX.carrying_add(1, false), (0, true));