Partial-stabilize the basics from `bigint_helper_methods` · rust-lang/rust@e49d000 (original) (raw)

`@@ -2447,7 +2447,7 @@ macro_rules! uint_impl {

2447

2448

2449

`` /// Calculates self + rhs + carry and returns a tuple containing

2450

/// the sum and the output carry.

2450

/// the sum and the output carry (in that order).

2451

`///

2452

`/// Performs "ternary addition" of two integer operands and a carry-in

2453

`/// bit, and returns an output integer and a carry-out bit. This allows

`@@ -2465,8 +2465,6 @@ macro_rules! uint_impl {

2465

`/// # Examples

2466

`///

2467

```` /// ```


`2468`

``

`-

/// #![feature(bigint_helper_methods)]

`

`2469`

``

`-

///

`

`2470`

`2468`

` #[doc = concat!("// 3 MAX (a = 3 × 2^", stringify!($BITS), " + 2^", stringify!($BITS), " - 1)")]

`

`2471`

`2469`

` #[doc = concat!("// + 5 7 (b = 5 × 2^", stringify!($BITS), " + 7)")]

`

`2472`

`2470`

`/// // ---------

`

`@@ -2483,7 +2481,7 @@ macro_rules! uint_impl {

`

`2483`

`2481`

`///

`

`2484`

`2482`

`/// assert_eq!((sum1, sum0), (9, 6));

`

`2485`

`2483`

```` /// ```

2486

#[unstable(feature = "bigint_helper_methods", issue = "85532")]

2484

#[stable(feature = "unsigned_bigint_helpers", since = "CURRENT_RUSTC_VERSION")]

2487

2485

` #[rustc_const_unstable(feature = "bigint_helper_methods", issue = "85532")]

2488

2486

` #[must_use = "this returns the result of the operation, \

2489

2487

` without modifying the original"]

`@@ -2559,8 +2557,6 @@ macro_rules! uint_impl {

2559

2557

`/// # Examples

2560

2558

`///

2561

2559

```` /// ```


`2562`

``

`-

/// #![feature(bigint_helper_methods)]

`

`2563`

``

`-

///

`

`2564`

`2560`

` #[doc = concat!("// 9 6 (a = 9 × 2^", stringify!($BITS), " + 6)")]

`

`2565`

`2561`

` #[doc = concat!("// - 5 7 (b = 5 × 2^", stringify!($BITS), " + 7)")]

`

`2566`

`2562`

`/// // ---------

`

`@@ -2577,7 +2573,7 @@ macro_rules! uint_impl {

`

`2577`

`2573`

`///

`

`2578`

`2574`

` #[doc = concat!("assert_eq!((diff1, diff0), (3, ", stringify!($SelfT), "::MAX));")]

`

`2579`

`2575`

```` /// ```

2580

#[unstable(feature = "bigint_helper_methods", issue = "85532")]

2576

#[stable(feature = "unsigned_bigint_helpers", since = "CURRENT_RUSTC_VERSION")]

2581

2577

` #[rustc_const_unstable(feature = "bigint_helper_methods", issue = "85532")]

2582

2578

` #[must_use = "this returns the result of the operation, \

2583

2579

` without modifying the original"]

`@@ -2651,10 +2647,12 @@ macro_rules! uint_impl {

2651

2647

`/// indicating whether an arithmetic overflow would occur. If an

2652

2648

`/// overflow would have occurred then the wrapped value is returned.

2653

2649

`///

2650

/// If you want the value of the overflow, rather than just whether

2651

`` +

/// an overflow occurred, see [Self::carrying_mul].

2652

///

2654

2653

`/// # Examples

2655

2654

`///

2656

`` -

/// Please note that this example is shared among integer types, which is why why u32

2657

/// is used.

2655

`` +

/// Please note that this example is shared among integer types, which is why u32 is used.

2658

2656

`///

2659

2657

```` /// ```


`2660`

`2658`

`/// assert_eq!(5u32.overflowing_mul(2), (10, false));

`

`@@ -2670,16 +2668,38 @@ macro_rules! uint_impl {

`

`2670`

`2668`

`(a as Self, b)

`

`2671`

`2669`

`}

`

`2672`

`2670`

``

`2673`

``

`` -

/// Calculates the complete product `self * rhs` without the possibility to overflow.

``

``

`2671`

`` +

/// Calculates the complete double-width product `self * rhs`.

``

`2674`

`2672`

`///

`

`2675`

`2673`

`/// This returns the low-order (wrapping) bits and the high-order (overflow) bits

`

`2676`

``

`-

/// of the result as two separate values, in that order.

`

``

`2674`

`+

/// of the result as two separate values, in that order. As such,

`

``

`2675`

`` +

/// `a.widening_mul(b).0` produces the same result as `a.wrapping_mul(b)`.

``

``

`2676`

`+

///

`

``

`2677`

`+

/// If you also need to add a value and carry to the wide result, then you want

`

``

`2678`

`` +

/// [`Self::carrying_mul_add`] instead.

``

`2677`

`2679`

`///

`

`2678`

`2680`

`/// If you also need to add a carry to the wide result, then you want

`

`2679`

`2681`

`` /// [`Self::carrying_mul`] instead.

``

`2680`

`2682`

`///

`

``

`2683`

`+

/// If you just want to know *whether* the multiplication overflowed, then you

`

``

`2684`

`` +

/// want [`Self::overflowing_mul`] instead.

``

``

`2685`

`+

///

`

`2681`

`2686`

`/// # Examples

`

`2682`

`2687`

`///

`

``

`2688`

```` +

/// ```

2689

/// #![feature(bigint_helper_methods)]

2690

#[doc = concat!("assert_eq!(5_", stringify!($SelfT), ".widening_mul(7), (35, 0));")]

2691

#[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.widening_mul(", stringify!($SelfT), "::MAX), (1, ", stringify!($SelfT), "::MAX - 1));")]

2692


/// ```

2693

///

2694

`` +

/// Compared to other *_mul methods:

2695


/// ```

2696

/// #![feature(bigint_helper_methods)]

2697

#[doc = concat!("assert_eq!(", stringify!($SelfT), "::widening_mul(1 << ", stringify!($BITS_MINUS_ONE), ", 6), (0, 3));")]

2698

#[doc = concat!("assert_eq!(", stringify!($SelfT), "::overflowing_mul(1 << ", stringify!($BITS_MINUS_ONE), ", 6), (0, true));")]

2699

#[doc = concat!("assert_eq!(", stringify!($SelfT), "::wrapping_mul(1 << ", stringify!($BITS_MINUS_ONE), ", 6), 0);")]

2700

#[doc = concat!("assert_eq!(", stringify!($SelfT), "::checked_mul(1 << ", stringify!($BITS_MINUS_ONE), ", 6), None);")]

2701


/// ```

2702

///

2683

2703

`` /// Please note that this example is shared among integer types, which is why u32 is used.

2684

2704

`///

2685

2705

```` /// ```


`@@ -2706,14 +2726,13 @@ macro_rules! uint_impl {

`

`2706`

`2726`

`/// additional amount of overflow. This allows for chaining together multiple

`

`2707`

`2727`

`/// multiplications to create "big integers" which represent larger values.

`

`2708`

`2728`

`///

`

`2709`

``

`` -

/// If you don't need the `carry`, then you can use [`Self::widening_mul`] instead.

``

``

`2729`

`` +

/// If you also need to add a value, then use [`Self::carrying_mul_add`].

``

`2710`

`2730`

`///

`

`2711`

`2731`

`/// # Examples

`

`2712`

`2732`

`///

`

`2713`

`2733`

`` /// Please note that this example is shared among integer types, which is why `u32` is used.

``

`2714`

`2734`

`///

`

`2715`

`2735`

```` /// ```

2716

/// #![feature(bigint_helper_methods)]

2717

2736

`/// assert_eq!(5u32.carrying_mul(2, 0), (10, 0));

2718

2737

`/// assert_eq!(5u32.carrying_mul(2, 10), (20, 0));

2719

2738

`/// assert_eq!(1_000_000_000u32.carrying_mul(10, 0), (1410065408, 2));

`@@ -2771,7 +2790,7 @@ macro_rules! uint_impl {

2771

2790

`/// 789_u16.wrapping_mul(456).wrapping_add(123),

2772

2791

`/// );

2773

2792

```` /// ```


`2774`

``

`-

#[unstable(feature = "bigint_helper_methods", issue = "85532")]

`

``

`2793`

`+

#[stable(feature = "unsigned_bigint_helpers", since = "CURRENT_RUSTC_VERSION")]

`

`2775`

`2794`

` #[rustc_const_unstable(feature = "bigint_helper_methods", issue = "85532")]

`

`2776`

`2795`

` #[must_use = "this returns the result of the operation, \

`

`2777`

`2796`

` without modifying the original"]

`

`@@ -2780,26 +2799,27 @@ macro_rules! uint_impl {

`

`2780`

`2799`

`Self::carrying_mul_add(self, rhs, carry, 0)

`

`2781`

`2800`

`}

`

`2782`

`2801`

``

`2783`

``

`` -

/// Calculates the "full multiplication" `self * rhs + carry1 + carry2`

``

`2784`

``

`-

/// without the possibility to overflow.

`

``

`2802`

`` +

/// Calculates the "full multiplication" `self * rhs + carry1 + carry2`.

``

`2785`

`2803`

`///

`

`2786`

`2804`

`/// This returns the low-order (wrapping) bits and the high-order (overflow) bits

`

`2787`

`2805`

`/// of the result as two separate values, in that order.

`

`2788`

`2806`

`///

`

``

`2807`

`+

/// This cannot overflow, as the double-width result has exactly enough

`

``

`2808`

`+

/// space for the largest possible result. This is equivalent to how, in

`

``

`2809`

`+

/// decimal, 9 × 9 + 9 + 9 = 81 + 18 = 99 = 9×10⁰ + 9×10¹ = 10² - 1.

`

``

`2810`

`+

///

`

`2789`

`2811`

`/// Performs "long multiplication" which takes in an extra amount to add, and may return an

`

`2790`

`2812`

`/// additional amount of overflow. This allows for chaining together multiple

`

`2791`

`2813`

`/// multiplications to create "big integers" which represent larger values.

`

`2792`

`2814`

`///

`

`2793`

``

`` -

/// If you don't need either `carry`, then you can use [`Self::widening_mul`] instead,

``

`2794`

``

`` -

/// and if you only need one `carry`, then you can use [`Self::carrying_mul`] instead.

``

``

`2815`

`` +

/// If you don't need the `add` part, then you can use [`Self::carrying_mul`] instead.

``

`2795`

`2816`

`///

`

`2796`

`2817`

`/// # Examples

`

`2797`

`2818`

`///

`

`2798`

`2819`

`/// Please note that this example is shared between integer types,

`

`2799`

`2820`

`` /// which explains why `u32` is used here.

``

`2800`

`2821`

`///

`

`2801`

`2822`

```` /// ```

2802

/// #![feature(bigint_helper_methods)]

2803

2823

`/// assert_eq!(5u32.carrying_mul_add(2, 0, 0), (10, 0));

2804

2824

`/// assert_eq!(5u32.carrying_mul_add(2, 10, 10), (30, 0));

2805

2825

`/// assert_eq!(1_000_000_000u32.carrying_mul_add(10, 0, 0), (1410065408, 2));

`@@ -2816,8 +2836,6 @@ macro_rules! uint_impl {

2816

2836

`` /// using u8 for simplicity of the demonstration.

2817

2837

`///

2818

2838

```` /// ```


`2819`

``

`-

/// #![feature(bigint_helper_methods)]

`

`2820`

``

`-

///

`

`2821`

`2839`

`/// fn quadratic_mul<const N: usize>(a: [u8; N], b: [u8; N]) -> [u8; N] {

`

`2822`

`2840`

`/// let mut out = [0; N];

`

`2823`

`2841`

`/// for j in 0..N {

`

`@@ -2832,13 +2850,13 @@ macro_rules! uint_impl {

`

`2832`

`2850`

`/// // -1 * -1 == 1

`

`2833`

`2851`

`/// assert_eq!(quadratic_mul([0xFF; 3], [0xFF; 3]), [1, 0, 0]);

`

`2834`

`2852`

`///

`

`2835`

``

`-

/// assert_eq!(u32::wrapping_mul(0x9e3779b9, 0x7f4a7c15), 0xCFFC982D);

`

``

`2853`

`+

/// assert_eq!(u32::wrapping_mul(0x9e3779b9, 0x7f4a7c15), 0xcffc982d);

`

`2836`

`2854`

`/// assert_eq!(

`

`2837`

`2855`

`/// quadratic_mul(u32::to_le_bytes(0x9e3779b9), u32::to_le_bytes(0x7f4a7c15)),

`

`2838`

``

`-

/// u32::to_le_bytes(0xCFFC982D)

`

``

`2856`

`+

/// u32::to_le_bytes(0xcffc982d)

`

`2839`

`2857`

`/// );

`

`2840`

`2858`

```` /// ```

2841

#[unstable(feature = "bigint_helper_methods", issue = "85532")]

2859

#[stable(feature = "unsigned_bigint_helpers", since = "CURRENT_RUSTC_VERSION")]

2842

2860

` #[rustc_const_unstable(feature = "bigint_helper_methods", issue = "85532")]

2843

2861

` #[must_use = "this returns the result of the operation, \

2844

2862

` without modifying the original"]

Partial-stabilize the basics from bigint_helper_methods · rust-lang/rust@e49d000 (original) (raw)

Partial-stabilize the basics from `bigint_helper_methods` · rust-lang/rust@e49d000 (original) (raw)