diff options
| -rw-r--r-- | library/core/src/num/uint_macros.rs | 66 |
1 files changed, 42 insertions, 24 deletions
diff --git a/library/core/src/num/uint_macros.rs b/library/core/src/num/uint_macros.rs index 10d9498d15e..c556d951034 100644 --- a/library/core/src/num/uint_macros.rs +++ b/library/core/src/num/uint_macros.rs @@ -2447,7 +2447,7 @@ macro_rules! uint_impl { } /// Calculates `self` + `rhs` + `carry` and returns a tuple containing - /// the sum and the output carry. + /// the sum and the output carry (in that order). /// /// Performs "ternary addition" of two integer operands and a carry-in /// bit, and returns an output integer and a carry-out bit. This allows @@ -2465,8 +2465,6 @@ macro_rules! uint_impl { /// # Examples /// /// ``` - /// #![feature(bigint_helper_methods)] - /// #[doc = concat!("// 3 MAX (a = 3 × 2^", stringify!($BITS), " + 2^", stringify!($BITS), " - 1)")] #[doc = concat!("// + 5 7 (b = 5 × 2^", stringify!($BITS), " + 7)")] /// // --------- @@ -2483,7 +2481,7 @@ macro_rules! uint_impl { /// /// assert_eq!((sum1, sum0), (9, 6)); /// ``` - #[unstable(feature = "bigint_helper_methods", issue = "85532")] + #[stable(feature = "unsigned_bigint_helpers", since = "CURRENT_RUSTC_VERSION")] #[rustc_const_unstable(feature = "bigint_helper_methods", issue = "85532")] #[must_use = "this returns the result of the operation, \ without modifying the original"] @@ -2559,8 +2557,6 @@ macro_rules! uint_impl { /// # Examples /// /// ``` - /// #![feature(bigint_helper_methods)] - /// #[doc = concat!("// 9 6 (a = 9 × 2^", stringify!($BITS), " + 6)")] #[doc = concat!("// - 5 7 (b = 5 × 2^", stringify!($BITS), " + 7)")] /// // --------- @@ -2577,7 +2573,7 @@ macro_rules! uint_impl { /// #[doc = concat!("assert_eq!((diff1, diff0), (3, ", stringify!($SelfT), "::MAX));")] /// ``` - #[unstable(feature = "bigint_helper_methods", issue = "85532")] + #[stable(feature = "unsigned_bigint_helpers", since = "CURRENT_RUSTC_VERSION")] #[rustc_const_unstable(feature = "bigint_helper_methods", issue = "85532")] #[must_use = "this returns the result of the operation, \ without modifying the original"] @@ -2651,10 +2647,12 @@ macro_rules! uint_impl { /// indicating whether an arithmetic overflow would occur. If an /// overflow would have occurred then the wrapped value is returned. /// + /// If you want the *value* of the overflow, rather than just *whether* + /// an overflow occurred, see [`Self::carrying_mul`]. + /// /// # Examples /// - /// Please note that this example is shared among integer types, which is why why `u32` - /// is used. + /// Please note that this example is shared among integer types, which is why `u32` is used. /// /// ``` /// assert_eq!(5u32.overflowing_mul(2), (10, false)); @@ -2670,16 +2668,38 @@ macro_rules! uint_impl { (a as Self, b) } - /// Calculates the complete product `self * rhs` without the possibility to overflow. + /// Calculates the complete double-width product `self * rhs`. /// /// This returns the low-order (wrapping) bits and the high-order (overflow) bits - /// of the result as two separate values, in that order. + /// of the result as two separate values, in that order. As such, + /// `a.widening_mul(b).0` produces the same result as `a.wrapping_mul(b)`. + /// + /// If you also need to add a value and carry to the wide result, then you want + /// [`Self::carrying_mul_add`] instead. /// /// If you also need to add a carry to the wide result, then you want /// [`Self::carrying_mul`] instead. /// + /// If you just want to know *whether* the multiplication overflowed, then you + /// want [`Self::overflowing_mul`] instead. + /// /// # Examples /// + /// ``` + /// #![feature(bigint_helper_methods)] + #[doc = concat!("assert_eq!(5_", stringify!($SelfT), ".widening_mul(7), (35, 0));")] + #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.widening_mul(", stringify!($SelfT), "::MAX), (1, ", stringify!($SelfT), "::MAX - 1));")] + /// ``` + /// + /// Compared to other `*_mul` methods: + /// ``` + /// #![feature(bigint_helper_methods)] + #[doc = concat!("assert_eq!(", stringify!($SelfT), "::widening_mul(1 << ", stringify!($BITS_MINUS_ONE), ", 6), (0, 3));")] + #[doc = concat!("assert_eq!(", stringify!($SelfT), "::overflowing_mul(1 << ", stringify!($BITS_MINUS_ONE), ", 6), (0, true));")] + #[doc = concat!("assert_eq!(", stringify!($SelfT), "::wrapping_mul(1 << ", stringify!($BITS_MINUS_ONE), ", 6), 0);")] + #[doc = concat!("assert_eq!(", stringify!($SelfT), "::checked_mul(1 << ", stringify!($BITS_MINUS_ONE), ", 6), None);")] + /// ``` + /// /// Please note that this example is shared among integer types, which is why `u32` is used. /// /// ``` @@ -2706,14 +2726,13 @@ macro_rules! uint_impl { /// additional amount of overflow. This allows for chaining together multiple /// multiplications to create "big integers" which represent larger values. /// - /// If you don't need the `carry`, then you can use [`Self::widening_mul`] instead. + /// If you also need to add a value, then use [`Self::carrying_mul_add`]. /// /// # Examples /// /// Please note that this example is shared among integer types, which is why `u32` is used. /// /// ``` - /// #![feature(bigint_helper_methods)] /// assert_eq!(5u32.carrying_mul(2, 0), (10, 0)); /// assert_eq!(5u32.carrying_mul(2, 10), (20, 0)); /// assert_eq!(1_000_000_000u32.carrying_mul(10, 0), (1410065408, 2)); @@ -2771,7 +2790,7 @@ macro_rules! uint_impl { /// 789_u16.wrapping_mul(456).wrapping_add(123), /// ); /// ``` - #[unstable(feature = "bigint_helper_methods", issue = "85532")] + #[stable(feature = "unsigned_bigint_helpers", since = "CURRENT_RUSTC_VERSION")] #[rustc_const_unstable(feature = "bigint_helper_methods", issue = "85532")] #[must_use = "this returns the result of the operation, \ without modifying the original"] @@ -2780,18 +2799,20 @@ macro_rules! uint_impl { Self::carrying_mul_add(self, rhs, carry, 0) } - /// Calculates the "full multiplication" `self * rhs + carry1 + carry2` - /// without the possibility to overflow. + /// Calculates the "full multiplication" `self * rhs + carry1 + carry2`. /// /// This returns the low-order (wrapping) bits and the high-order (overflow) bits /// of the result as two separate values, in that order. /// + /// This cannot overflow, as the double-width result has exactly enough + /// space for the largest possible result. This is equivalent to how, in + /// decimal, 9 × 9 + 9 + 9 = 81 + 18 = 99 = 9×10⁰ + 9×10¹ = 10² - 1. + /// /// Performs "long multiplication" which takes in an extra amount to add, and may return an /// additional amount of overflow. This allows for chaining together multiple /// multiplications to create "big integers" which represent larger values. /// - /// If you don't need either `carry`, then you can use [`Self::widening_mul`] instead, - /// and if you only need one `carry`, then you can use [`Self::carrying_mul`] instead. + /// If you don't need the `add` part, then you can use [`Self::carrying_mul`] instead. /// /// # Examples /// @@ -2799,7 +2820,6 @@ macro_rules! uint_impl { /// which explains why `u32` is used here. /// /// ``` - /// #![feature(bigint_helper_methods)] /// assert_eq!(5u32.carrying_mul_add(2, 0, 0), (10, 0)); /// assert_eq!(5u32.carrying_mul_add(2, 10, 10), (30, 0)); /// assert_eq!(1_000_000_000u32.carrying_mul_add(10, 0, 0), (1410065408, 2)); @@ -2816,8 +2836,6 @@ macro_rules! uint_impl { /// using `u8` for simplicity of the demonstration. /// /// ``` - /// #![feature(bigint_helper_methods)] - /// /// fn quadratic_mul<const N: usize>(a: [u8; N], b: [u8; N]) -> [u8; N] { /// let mut out = [0; N]; /// for j in 0..N { @@ -2832,13 +2850,13 @@ macro_rules! uint_impl { /// // -1 * -1 == 1 /// assert_eq!(quadratic_mul([0xFF; 3], [0xFF; 3]), [1, 0, 0]); /// - /// assert_eq!(u32::wrapping_mul(0x9e3779b9, 0x7f4a7c15), 0xCFFC982D); + /// assert_eq!(u32::wrapping_mul(0x9e3779b9, 0x7f4a7c15), 0xcffc982d); /// assert_eq!( /// quadratic_mul(u32::to_le_bytes(0x9e3779b9), u32::to_le_bytes(0x7f4a7c15)), - /// u32::to_le_bytes(0xCFFC982D) + /// u32::to_le_bytes(0xcffc982d) /// ); /// ``` - #[unstable(feature = "bigint_helper_methods", issue = "85532")] + #[stable(feature = "unsigned_bigint_helpers", since = "CURRENT_RUSTC_VERSION")] #[rustc_const_unstable(feature = "bigint_helper_methods", issue = "85532")] #[must_use = "this returns the result of the operation, \ without modifying the original"] |