int_macros.rs - source
Description: Source of the Rust file `library/core/src/num/int_macros.rs`.

#
core/num/
int_macros.rs

    1macro_rules! int_impl {
    2    (
    3        Self = $SelfT:ty,
    4        ActualT = $ActualT:ident,
    5        UnsignedT = $UnsignedT:ty,
    6
    7        // These are all for use *only* in doc comments.
    8        // As such, they're all passed as literals -- passing them as a string
    9        // literal is fine if they need to be multiple code tokens.
    10        // In non-comments, use the associated constants rather than these.
    11        BITS = $BITS:literal,
    12        BITS_MINUS_ONE = $BITS_MINUS_ONE:literal,
    13        Min = $Min:literal,
    14        Max = $Max:literal,
    15        rot = $rot:literal,
    16        rot_op = $rot_op:literal,
    17        rot_result = $rot_result:literal,
    18        swap_op = $swap_op:literal,
    19        swapped = $swapped:literal,
    20        reversed = $reversed:literal,
    21        le_bytes = $le_bytes:literal,
    22        be_bytes = $be_bytes:literal,
    23        to_xe_bytes_doc = $to_xe_bytes_doc:expr,
    24        from_xe_bytes_doc = $from_xe_bytes_doc:expr,
    25        bound_condition = $bound_condition:literal,
    26    ) => {
    27        /// The smallest value that can be represented by this integer type
    28        #[doc = concat!("(&minus;2<sup>", $BITS_MINUS_ONE, "</sup>", $bound_condition, ").")]
    29        ///
    30        /// # Examples
    31        ///
    32        /// ```
    33        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN, ", stringify!($Min), ");")]
    34        /// ```
    35        #[stable(feature = "assoc_int_consts", since = "1.43.0")]
    36        pub const MIN: Self = !Self::MAX;
    37
    38        /// The largest value that can be represented by this integer type
    39        #[doc = concat!("(2<sup>", $BITS_MINUS_ONE, "</sup> &minus; 1", $bound_condition, ").")]
    40        ///
    41        /// # Examples
    42        ///
    43        /// ```
    44        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX, ", stringify!($Max), ");")]
    45        /// ```
    46        #[stable(feature = "assoc_int_consts", since = "1.43.0")]
    47        pub const MAX: Self = (<$UnsignedT>::MAX >> 1) as Self;
    48
    49        /// The size of this integer type in bits.
    50        ///
    51        /// # Examples
    52        ///
    53        /// ```
    54        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::BITS, ", stringify!($BITS), ");")]
    55        /// ```
    56        #[stable(feature = "int_bits_const", since = "1.53.0")]
    57        pub const BITS: u32 = <$UnsignedT>::BITS;
    58
    59        /// Returns the number of ones in the binary representation of `self`.
    60        ///
    61        /// # Examples
    62        ///
    63        /// ```
    64        #[doc = concat!("let n = 0b100_0000", stringify!($SelfT), ";")]
    65        ///
    66        /// assert_eq!(n.count_ones(), 1);
    67        /// ```
    68        ///
    69        #[stable(feature = "rust1", since = "1.0.0")]
    70        #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
    71        #[doc(alias = "popcount")]
    72        #[doc(alias = "popcnt")]
    73        #[must_use = "this returns the result of the operation, \
    74                      without modifying the original"]
    75        #[inline(always)]
    76        pub const fn count_ones(self) -> u32 { (self as $UnsignedT).count_ones() }
    77
    78        /// Returns the number of zeros in the binary representation of `self`.
    79        ///
    80        /// # Examples
    81        ///
    82        /// ```
    83        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.count_zeros(), 1);")]
    84        /// ```
    85        #[stable(feature = "rust1", since = "1.0.0")]
    86        #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
    87        #[must_use = "this returns the result of the operation, \
    88                      without modifying the original"]
    89        #[inline(always)]
    90        pub const fn count_zeros(self) -> u32 {
    91            (!self).count_ones()
    92        }
    93
    94        /// Returns the number of leading zeros in the binary representation of `self`.
    95        ///
    96        /// Depending on what you're doing with the value, you might also be interested in the
    97        /// [`ilog2`] function which returns a consistent number, even if the type widens.
    98        ///
    99        /// # Examples
    100        ///
    101        /// ```
    102        #[doc = concat!("let n = -1", stringify!($SelfT), ";")]
    103        ///
    104        /// assert_eq!(n.leading_zeros(), 0);
    105        /// ```
    106        #[doc = concat!("[`ilog2`]: ", stringify!($SelfT), "::ilog2")]
    107        #[stable(feature = "rust1", since = "1.0.0")]
    108        #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
    109        #[must_use = "this returns the result of the operation, \
    110                      without modifying the original"]
    111        #[inline(always)]
    112        pub const fn leading_zeros(self) -> u32 {
    113            (self as $UnsignedT).leading_zeros()
    114        }
    115
    116        /// Returns the number of trailing zeros in the binary representation of `self`.
    117        ///
    118        /// # Examples
    119        ///
    120        /// ```
    121        #[doc = concat!("let n = -4", stringify!($SelfT), ";")]
    122        ///
    123        /// assert_eq!(n.trailing_zeros(), 2);
    124        /// ```
    125        #[stable(feature = "rust1", since = "1.0.0")]
    126        #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
    127        #[must_use = "this returns the result of the operation, \
    128                      without modifying the original"]
    129        #[inline(always)]
    130        pub const fn trailing_zeros(self) -> u32 {
    131            (self as $UnsignedT).trailing_zeros()
    132        }
    133
    134        /// Returns the number of leading ones in the binary representation of `self`.
    135        ///
    136        /// # Examples
    137        ///
    138        /// ```
    139        #[doc = concat!("let n = -1", stringify!($SelfT), ";")]
    140        ///
    141        #[doc = concat!("assert_eq!(n.leading_ones(), ", stringify!($BITS), ");")]
    142        /// ```
    143        #[stable(feature = "leading_trailing_ones", since = "1.46.0")]
    144        #[rustc_const_stable(feature = "leading_trailing_ones", since = "1.46.0")]
    145        #[must_use = "this returns the result of the operation, \
    146                      without modifying the original"]
    147        #[inline(always)]
    148        pub const fn leading_ones(self) -> u32 {
    149            (self as $UnsignedT).leading_ones()
    150        }
    151
    152        /// Returns the number of trailing ones in the binary representation of `self`.
    153        ///
    154        /// # Examples
    155        ///
    156        /// ```
    157        #[doc = concat!("let n = 3", stringify!($SelfT), ";")]
    158        ///
    159        /// assert_eq!(n.trailing_ones(), 2);
    160        /// ```
    161        #[stable(feature = "leading_trailing_ones", since = "1.46.0")]
    162        #[rustc_const_stable(feature = "leading_trailing_ones", since = "1.46.0")]
    163        #[must_use = "this returns the result of the operation, \
    164                      without modifying the original"]
    165        #[inline(always)]
    166        pub const fn trailing_ones(self) -> u32 {
    167            (self as $UnsignedT).trailing_ones()
    168        }
    169
    170        /// Returns `self` with only the most significant bit set, or `0` if
    171        /// the input is `0`.
    172        ///
    173        /// # Examples
    174        ///
    175        /// ```
    176        /// #![feature(isolate_most_least_significant_one)]
    177        ///
    178        #[doc = concat!("let n: ", stringify!($SelfT), " = 0b_01100100;")]
    179        ///
    180        /// assert_eq!(n.isolate_highest_one(), 0b_01000000);
    181        #[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".isolate_highest_one(), 0);")]
    182        /// ```
    183        #[unstable(feature = "isolate_most_least_significant_one", issue = "136909")]
    184        #[must_use = "this returns the result of the operation, \
    185                      without modifying the original"]
    186        #[inline(always)]
    187        pub const fn isolate_highest_one(self) -> Self {
    188            self & (((1 as $SelfT) << (<$SelfT>::BITS - 1)).wrapping_shr(self.leading_zeros()))
    189        }
    190
    191        /// Returns `self` with only the least significant bit set, or `0` if
    192        /// the input is `0`.
    193        ///
    194        /// # Examples
    195        ///
    196        /// ```
    197        /// #![feature(isolate_most_least_significant_one)]
    198        ///
    199        #[doc = concat!("let n: ", stringify!($SelfT), " = 0b_01100100;")]
    200        ///
    201        /// assert_eq!(n.isolate_lowest_one(), 0b_00000100);
    202        #[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".isolate_lowest_one(), 0);")]
    203        /// ```
    204        #[unstable(feature = "isolate_most_least_significant_one", issue = "136909")]
    205        #[must_use = "this returns the result of the operation, \
    206                      without modifying the original"]
    207        #[inline(always)]
    208        pub const fn isolate_lowest_one(self) -> Self {
    209            self & self.wrapping_neg()
    210        }
    211
    212        /// Returns the index of the highest bit set to one in `self`, or `None`
    213        /// if `self` is `0`.
    214        ///
    215        /// # Examples
    216        ///
    217        /// ```
    218        /// #![feature(int_lowest_highest_one)]
    219        ///
    220        #[doc = concat!("assert_eq!(0b0_", stringify!($SelfT), ".highest_one(), None);")]
    221        #[doc = concat!("assert_eq!(0b1_", stringify!($SelfT), ".highest_one(), Some(0));")]
    222        #[doc = concat!("assert_eq!(0b1_0000_", stringify!($SelfT), ".highest_one(), Some(4));")]
    223        #[doc = concat!("assert_eq!(0b1_1111_", stringify!($SelfT), ".highest_one(), Some(4));")]
    224        /// ```
    225        #[unstable(feature = "int_lowest_highest_one", issue = "145203")]
    226        #[must_use = "this returns the result of the operation, \
    227                      without modifying the original"]
    228        #[inline(always)]
    229        pub const fn highest_one(self) -> Option<u32> {
    230            (self as $UnsignedT).highest_one()
    231        }
    232
    233        /// Returns the index of the lowest bit set to one in `self`, or `None`
    234        /// if `self` is `0`.
    235        ///
    236        /// # Examples
    237        ///
    238        /// ```
    239        /// #![feature(int_lowest_highest_one)]
    240        ///
    241        #[doc = concat!("assert_eq!(0b0_", stringify!($SelfT), ".lowest_one(), None);")]
    242        #[doc = concat!("assert_eq!(0b1_", stringify!($SelfT), ".lowest_one(), Some(0));")]
    243        #[doc = concat!("assert_eq!(0b1_0000_", stringify!($SelfT), ".lowest_one(), Some(4));")]
    244        #[doc = concat!("assert_eq!(0b1_1111_", stringify!($SelfT), ".lowest_one(), Some(0));")]
    245        /// ```
    246        #[unstable(feature = "int_lowest_highest_one", issue = "145203")]
    247        #[must_use = "this returns the result of the operation, \
    248                      without modifying the original"]
    249        #[inline(always)]
    250        pub const fn lowest_one(self) -> Option<u32> {
    251            (self as $UnsignedT).lowest_one()
    252        }
    253
    254        /// Returns the bit pattern of `self` reinterpreted as an unsigned integer of the same size.
    255        ///
    256        /// This produces the same result as an `as` cast, but ensures that the bit-width remains
    257        /// the same.
    258        ///
    259        /// # Examples
    260        ///
    261        /// ```
    262        #[doc = concat!("let n = -1", stringify!($SelfT), ";")]
    263        ///
    264        #[doc = concat!("assert_eq!(n.cast_unsigned(), ", stringify!($UnsignedT), "::MAX);")]
    265        /// ```
    266        #[stable(feature = "integer_sign_cast", since = "1.87.0")]
    267        #[rustc_const_stable(feature = "integer_sign_cast", since = "1.87.0")]
    268        #[must_use = "this returns the result of the operation, \
    269                      without modifying the original"]
    270        #[inline(always)]
    271        pub const fn cast_unsigned(self) -> $UnsignedT {
    272            self as $UnsignedT
    273        }
    274
    275        /// Shifts the bits to the left by a specified amount, `n`,
    276        /// wrapping the truncated bits to the end of the resulting integer.
    277        ///
    278        /// `rotate_left(n)` is equivalent to applying `rotate_left(1)` a total of `n` times. In
    279        /// particular, a rotation by the number of bits in `self` returns the input value
    280        /// unchanged.
    281        ///
    282        /// Please note this isn't the same operation as the `<<` shifting operator!
    283        ///
    284        /// # Examples
    285        ///
    286        /// ```
    287        #[doc = concat!("let n = ", $rot_op, stringify!($SelfT), ";")]
    288        #[doc = concat!("let m = ", $rot_result, ";")]
    289        ///
    290        #[doc = concat!("assert_eq!(n.rotate_left(", $rot, "), m);")]
    291        #[doc = concat!("assert_eq!(n.rotate_left(1024), n);")]
    292        /// ```
    293        #[stable(feature = "rust1", since = "1.0.0")]
    294        #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
    295        #[must_use = "this returns the result of the operation, \
    296                      without modifying the original"]
    297        #[inline(always)]
    298        pub const fn rotate_left(self, n: u32) -> Self {
    299            (self as $UnsignedT).rotate_left(n) as Self
    300        }
    301
    302        /// Shifts the bits to the right by a specified amount, `n`,
    303        /// wrapping the truncated bits to the beginning of the resulting
    304        /// integer.
    305        ///
    306        /// `rotate_right(n)` is equivalent to applying `rotate_right(1)` a total of `n` times. In
    307        /// particular, a rotation by the number of bits in `self` returns the input value
    308        /// unchanged.
    309        ///
    310        /// Please note this isn't the same operation as the `>>` shifting operator!
    311        ///
    312        /// # Examples
    313        ///
    314        /// ```
    315        #[doc = concat!("let n = ", $rot_result, stringify!($SelfT), ";")]
    316        #[doc = concat!("let m = ", $rot_op, ";")]
    317        ///
    318        #[doc = concat!("assert_eq!(n.rotate_right(", $rot, "), m);")]
    319        #[doc = concat!("assert_eq!(n.rotate_right(1024), n);")]
    320        /// ```
    321        #[stable(feature = "rust1", since = "1.0.0")]
    322        #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
    323        #[must_use = "this returns the result of the operation, \
    324                      without modifying the original"]
    325        #[inline(always)]
    326        pub const fn rotate_right(self, n: u32) -> Self {
    327            (self as $UnsignedT).rotate_right(n) as Self
    328        }
    329
    330        /// Reverses the byte order of the integer.
    331        ///
    332        /// # Examples
    333        ///
    334        /// ```
    335        #[doc = concat!("let n = ", $swap_op, stringify!($SelfT), ";")]
    336        ///
    337        /// let m = n.swap_bytes();
    338        ///
    339        #[doc = concat!("assert_eq!(m, ", $swapped, ");")]
    340        /// ```
    341        #[stable(feature = "rust1", since = "1.0.0")]
    342        #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
    343        #[must_use = "this returns the result of the operation, \
    344                      without modifying the original"]
    345        #[inline(always)]
    346        pub const fn swap_bytes(self) -> Self {
    347            (self as $UnsignedT).swap_bytes() as Self
    348        }
    349
    350        /// Reverses the order of bits in the integer. The least significant bit becomes the most significant bit,
    351        ///                 second least-significant bit becomes second most-significant bit, etc.
    352        ///
    353        /// # Examples
    354        ///
    355        /// ```
    356        #[doc = concat!("let n = ", $swap_op, stringify!($SelfT), ";")]
    357        /// let m = n.reverse_bits();
    358        ///
    359        #[doc = concat!("assert_eq!(m, ", $reversed, ");")]
    360        #[doc = concat!("assert_eq!(0, 0", stringify!($SelfT), ".reverse_bits());")]
    361        /// ```
    362        #[stable(feature = "reverse_bits", since = "1.37.0")]
    363        #[rustc_const_stable(feature = "reverse_bits", since = "1.37.0")]
    364        #[must_use = "this returns the result of the operation, \
    365                      without modifying the original"]
    366        #[inline(always)]
    367        pub const fn reverse_bits(self) -> Self {
    368            (self as $UnsignedT).reverse_bits() as Self
    369        }
    370
    371        /// Converts an integer from big endian to the target's endianness.
    372        ///
    373        /// On big endian this is a no-op. On little endian the bytes are swapped.
    374        ///
    375        /// See also [from_be_bytes()](Self::from_be_bytes).
    376        ///
    377        /// # Examples
    378        ///
    379        /// ```
    380        #[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")]
    381        ///
    382        /// if cfg!(target_endian = "big") {
    383        #[doc = concat!("    assert_eq!(", stringify!($SelfT), "::from_be(n), n)")]
    384        /// } else {
    385        #[doc = concat!("    assert_eq!(", stringify!($SelfT), "::from_be(n), n.swap_bytes())")]
    386        /// }
    387        /// ```
    388        #[stable(feature = "rust1", since = "1.0.0")]
    389        #[rustc_const_stable(feature = "const_int_conversions", since = "1.32.0")]
    390        #[must_use]
    391        #[inline]
    392        pub const fn from_be(x: Self) -> Self {
    393            #[cfg(target_endian = "big")]
    394            {
    395                x
    396            }
    397            #[cfg(not(target_endian = "big"))]
    398            {
    399                x.swap_bytes()
    400            }
    401        }
    402
    403        /// Converts an integer from little endian to the target's endianness.
    404        ///
    405        /// On little endian this is a no-op. On big endian the bytes are swapped.
    406        ///
    407        /// See also [from_le_bytes()](Self::from_le_bytes).
    408        ///
    409        /// # Examples
    410        ///
    411        /// ```
    412        #[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")]
    413        ///
    414        /// if cfg!(target_endian = "little") {
    415        #[doc = concat!("    assert_eq!(", stringify!($SelfT), "::from_le(n), n)")]
    416        /// } else {
    417        #[doc = concat!("    assert_eq!(", stringify!($SelfT), "::from_le(n), n.swap_bytes())")]
    418        /// }
    419        /// ```
    420        #[stable(feature = "rust1", since = "1.0.0")]
    421        #[rustc_const_stable(feature = "const_int_conversions", since = "1.32.0")]
    422        #[must_use]
    423        #[inline]
    424        pub const fn from_le(x: Self) -> Self {
    425            #[cfg(target_endian = "little")]
    426            {
    427                x
    428            }
    429            #[cfg(not(target_endian = "little"))]
    430            {
    431                x.swap_bytes()
    432            }
    433        }
    434
    435        /// Swaps bytes of `self` on little endian targets.
    436        ///
    437        /// On big endian this is a no-op.
    438        ///
    439        /// The returned value has the same type as `self`, and will be interpreted
    440        /// as (a potentially different) value of a native-endian
    441        #[doc = concat!("`", stringify!($SelfT), "`.")]
    442        ///
    443        /// See [`to_be_bytes()`](Self::to_be_bytes) for a type-safe alternative.
    444        ///
    445        /// # Examples
    446        ///
    447        /// ```
    448        #[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")]
    449        ///
    450        /// if cfg!(target_endian = "big") {
    451        ///     assert_eq!(n.to_be(), n)
    452        /// } else {
    453        ///     assert_eq!(n.to_be(), n.swap_bytes())
    454        /// }
    455        /// ```
    456        #[stable(feature = "rust1", since = "1.0.0")]
    457        #[rustc_const_stable(feature = "const_int_conversions", since = "1.32.0")]
    458        #[must_use = "this returns the result of the operation, \
    459                      without modifying the original"]
    460        #[inline]
    461        pub const fn to_be(self) -> Self { // or not to be?
    462            #[cfg(target_endian = "big")]
    463            {
    464                self
    465            }
    466            #[cfg(not(target_endian = "big"))]
    467            {
    468                self.swap_bytes()
    469            }
    470        }
    471
    472        /// Swaps bytes of `self` on big endian targets.
    473        ///
    474        /// On little endian this is a no-op.
    475        ///
    476        /// The returned value has the same type as `self`, and will be interpreted
    477        /// as (a potentially different) value of a native-endian
    478        #[doc = concat!("`", stringify!($SelfT), "`.")]
    479        ///
    480        /// See [`to_le_bytes()`](Self::to_le_bytes) for a type-safe alternative.
    481        ///
    482        /// # Examples
    483        ///
    484        /// ```
    485        #[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")]
    486        ///
    487        /// if cfg!(target_endian = "little") {
    488        ///     assert_eq!(n.to_le(), n)
    489        /// } else {
    490        ///     assert_eq!(n.to_le(), n.swap_bytes())
    491        /// }
    492        /// ```
    493        #[stable(feature = "rust1", since = "1.0.0")]
    494        #[rustc_const_stable(feature = "const_int_conversions", since = "1.32.0")]
    495        #[must_use = "this returns the result of the operation, \
    496                      without modifying the original"]
    497        #[inline]
    498        pub const fn to_le(self) -> Self {
    499            #[cfg(target_endian = "little")]
    500            {
    501                self
    502            }
    503            #[cfg(not(target_endian = "little"))]
    504            {
    505                self.swap_bytes()
    506            }
    507        }
    508
    509        /// Checked integer addition. Computes `self + rhs`, returning `None`
    510        /// if overflow occurred.
    511        ///
    512        /// # Examples
    513        ///
    514        /// ```
    515        #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).checked_add(1), Some(", stringify!($SelfT), "::MAX - 1));")]
    516        #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).checked_add(3), None);")]
    517        /// ```
    518        #[stable(feature = "rust1", since = "1.0.0")]
    519        #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
    520        #[must_use = "this returns the result of the operation, \
    521                      without modifying the original"]
    522        #[inline]
    523        pub const fn checked_add(self, rhs: Self) -> Option<Self> {
    524            let (a, b) = self.overflowing_add(rhs);
    525            if intrinsics::unlikely(b) { None } else { Some(a) }
    526        }
    527
    528        /// Strict integer addition. Computes `self + rhs`, panicking
    529        /// if overflow occurred.
    530        ///
    531        /// # Panics
    532        ///
    533        /// ## Overflow behavior
    534        ///
    535        /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
    536        ///
    537        /// # Examples
    538        ///
    539        /// ```
    540        #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).strict_add(1), ", stringify!($SelfT), "::MAX - 1);")]
    541        /// ```
    542        ///
    543        /// The following panics because of overflow:
    544        ///
    545        /// ```should_panic
    546        #[doc = concat!("let _ = (", stringify!($SelfT), "::MAX - 2).strict_add(3);")]
    547        /// ```
    548        #[stable(feature = "strict_overflow_ops", since = "1.91.0")]
    549        #[rustc_const_stable(feature = "strict_overflow_ops", since = "1.91.0")]
    550        #[must_use = "this returns the result of the operation, \
    551                      without modifying the original"]
    552        #[inline]
    553        #[track_caller]
    554        pub const fn strict_add(self, rhs: Self) -> Self {
    555            let (a, b) = self.overflowing_add(rhs);
    556            if b { overflow_panic::add() } else { a }
    557        }
    558
    559        /// Unchecked integer addition. Computes `self + rhs`, assuming overflow
    560        /// cannot occur.
    561        ///
    562        /// Calling `x.unchecked_add(y)` is semantically equivalent to calling
    563        /// `x.`[`checked_add`]`(y).`[`unwrap_unchecked`]`()`.
    564        ///
    565        /// If you're just trying to avoid the panic in debug mode, then **do not**
    566        /// use this.  Instead, you're looking for [`wrapping_add`].
    567        ///
    568        /// # Safety
    569        ///
    570        /// This results in undefined behavior when
    571        #[doc = concat!("`self + rhs > ", stringify!($SelfT), "::MAX` or `self + rhs < ", stringify!($SelfT), "::MIN`,")]
    572        /// i.e. when [`checked_add`] would return `None`.
    573        ///
    574        /// [`unwrap_unchecked`]: option/enum.Option.html#method.unwrap_unchecked
    575        #[doc = concat!("[`checked_add`]: ", stringify!($SelfT), "::checked_add")]
    576        #[doc = concat!("[`wrapping_add`]: ", stringify!($SelfT), "::wrapping_add")]
    577        #[stable(feature = "unchecked_math", since = "1.79.0")]
    578        #[rustc_const_stable(feature = "unchecked_math", since = "1.79.0")]
    579        #[must_use = "this returns the result of the operation, \
    580                      without modifying the original"]
    581        #[inline(always)]
    582        #[track_caller]
    583        pub const unsafe fn unchecked_add(self, rhs: Self) -> Self {
    584            assert_unsafe_precondition!(
    585                check_language_ub,
    586                concat!(stringify!($SelfT), "::unchecked_add cannot overflow"),
    587                (
    588                    lhs: $SelfT = self,
    589                    rhs: $SelfT = rhs,
    590                ) => !lhs.overflowing_add(rhs).1,
    591            );
    592
    593            // SAFETY: this is guaranteed to be safe by the caller.
    594            unsafe {
    595                intrinsics::unchecked_add(self, rhs)
    596            }
    597        }
    598
    599        /// Checked addition with an unsigned integer. Computes `self + rhs`,
    600        /// returning `None` if overflow occurred.
    601        ///
    602        /// # Examples
    603        ///
    604        /// ```
    605        #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".checked_add_unsigned(2), Some(3));")]
    606        #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).checked_add_unsigned(3), None);")]
    607        /// ```
    608        #[stable(feature = "mixed_integer_ops", since = "1.66.0")]
    609        #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")]
    610        #[must_use = "this returns the result of the operation, \
    611                      without modifying the original"]
    612        #[inline]
    613        pub const fn checked_add_unsigned(self, rhs: $UnsignedT) -> Option<Self> {
    614            let (a, b) = self.overflowing_add_unsigned(rhs);
    615            if intrinsics::unlikely(b) { None } else { Some(a) }
    616        }
    617
    618        /// Strict addition with an unsigned integer. Computes `self + rhs`,
    619        /// panicking if overflow occurred.
    620        ///
    621        /// # Panics
    622        ///
    623        /// ## Overflow behavior
    624        ///
    625        /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
    626        ///
    627        /// # Examples
    628        ///
    629        /// ```
    630        #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".strict_add_unsigned(2), 3);")]
    631        /// ```
    632        ///
    633        /// The following panics because of overflow:
    634        ///
    635        /// ```should_panic
    636        #[doc = concat!("let _ = (", stringify!($SelfT), "::MAX - 2).strict_add_unsigned(3);")]
    637        /// ```
    638        #[stable(feature = "strict_overflow_ops", since = "1.91.0")]
    639        #[rustc_const_stable(feature = "strict_overflow_ops", since = "1.91.0")]
    640        #[must_use = "this returns the result of the operation, \
    641                      without modifying the original"]
    642        #[inline]
    643        #[track_caller]
    644        pub const fn strict_add_unsigned(self, rhs: $UnsignedT) -> Self {
    645            let (a, b) = self.overflowing_add_unsigned(rhs);
    646            if b { overflow_panic::add() } else { a }
    647        }
    648
    649        /// Checked integer subtraction. Computes `self - rhs`, returning `None` if
    650        /// overflow occurred.
    651        ///
    652        /// # Examples
    653        ///
    654        /// ```
    655        #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 2).checked_sub(1), Some(", stringify!($SelfT), "::MIN + 1));")]
    656        #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 2).checked_sub(3), None);")]
    657        /// ```
    658        #[stable(feature = "rust1", since = "1.0.0")]
    659        #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
    660        #[must_use = "this returns the result of the operation, \
    661                      without modifying the original"]
    662        #[inline]
    663        pub const fn checked_sub(self, rhs: Self) -> Option<Self> {
    664            let (a, b) = self.overflowing_sub(rhs);
    665            if intrinsics::unlikely(b) { None } else { Some(a) }
    666        }
    667
    668        /// Strict integer subtraction. Computes `self - rhs`, panicking if
    669        /// overflow occurred.
    670        ///
    671        /// # Panics
    672        ///
    673        /// ## Overflow behavior
    674        ///
    675        /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
    676        ///
    677        /// # Examples
    678        ///
    679        /// ```
    680        #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 2).strict_sub(1), ", stringify!($SelfT), "::MIN + 1);")]
    681        /// ```
    682        ///
    683        /// The following panics because of overflow:
    684        ///
    685        /// ```should_panic
    686        #[doc = concat!("let _ = (", stringify!($SelfT), "::MIN + 2).strict_sub(3);")]
    687        /// ```
    688        #[stable(feature = "strict_overflow_ops", since = "1.91.0")]
    689        #[rustc_const_stable(feature = "strict_overflow_ops", since = "1.91.0")]
    690        #[must_use = "this returns the result of the operation, \
    691                      without modifying the original"]
    692        #[inline]
    693        #[track_caller]
    694        pub const fn strict_sub(self, rhs: Self) -> Self {
    695            let (a, b) = self.overflowing_sub(rhs);
    696            if b { overflow_panic::sub() } else { a }
    697        }
    698
    699        /// Unchecked integer subtraction. Computes `self - rhs`, assuming overflow
    700        /// cannot occur.
    701        ///
    702        /// Calling `x.unchecked_sub(y)` is semantically equivalent to calling
    703        /// `x.`[`checked_sub`]`(y).`[`unwrap_unchecked`]`()`.
    704        ///
    705        /// If you're just trying to avoid the panic in debug mode, then **do not**
    706        /// use this.  Instead, you're looking for [`wrapping_sub`].
    707        ///
    708        /// # Safety
    709        ///
    710        /// This results in undefined behavior when
    711        #[doc = concat!("`self - rhs > ", stringify!($SelfT), "::MAX` or `self - rhs < ", stringify!($SelfT), "::MIN`,")]
    712        /// i.e. when [`checked_sub`] would return `None`.
    713        ///
    714        /// [`unwrap_unchecked`]: option/enum.Option.html#method.unwrap_unchecked
    715        #[doc = concat!("[`checked_sub`]: ", stringify!($SelfT), "::checked_sub")]
    716        #[doc = concat!("[`wrapping_sub`]: ", stringify!($SelfT), "::wrapping_sub")]
    717        #[stable(feature = "unchecked_math", since = "1.79.0")]
    718        #[rustc_const_stable(feature = "unchecked_math", since = "1.79.0")]
    719        #[must_use = "this returns the result of the operation, \
    720                      without modifying the original"]
    721        #[inline(always)]
    722        #[track_caller]
    723        pub const unsafe fn unchecked_sub(self, rhs: Self) -> Self {
    724            assert_unsafe_precondition!(
    725                check_language_ub,
    726                concat!(stringify!($SelfT), "::unchecked_sub cannot overflow"),
    727                (
    728                    lhs: $SelfT = self,
    729                    rhs: $SelfT = rhs,
    730                ) => !lhs.overflowing_sub(rhs).1,
    731            );
    732
    733            // SAFETY: this is guaranteed to be safe by the caller.
    734            unsafe {
    735                intrinsics::unchecked_sub(self, rhs)
    736            }
    737        }
    738
    739        /// Checked subtraction with an unsigned integer. Computes `self - rhs`,
    740        /// returning `None` if overflow occurred.
    741        ///
    742        /// # Examples
    743        ///
    744        /// ```
    745        #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".checked_sub_unsigned(2), Some(-1));")]
    746        #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 2).checked_sub_unsigned(3), None);")]
    747        /// ```
    748        #[stable(feature = "mixed_integer_ops", since = "1.66.0")]
    749        #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")]
    750        #[must_use = "this returns the result of the operation, \
    751                      without modifying the original"]
    752        #[inline]
    753        pub const fn checked_sub_unsigned(self, rhs: $UnsignedT) -> Option<Self> {
    754            let (a, b) = self.overflowing_sub_unsigned(rhs);
    755            if intrinsics::unlikely(b) { None } else { Some(a) }
    756        }
    757
    758        /// Strict subtraction with an unsigned integer. Computes `self - rhs`,
    759        /// panicking if overflow occurred.
    760        ///
    761        /// # Panics
    762        ///
    763        /// ## Overflow behavior
    764        ///
    765        /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
    766        ///
    767        /// # Examples
    768        ///
    769        /// ```
    770        #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".strict_sub_unsigned(2), -1);")]
    771        /// ```
    772        ///
    773        /// The following panics because of overflow:
    774        ///
    775        /// ```should_panic
    776        #[doc = concat!("let _ = (", stringify!($SelfT), "::MIN + 2).strict_sub_unsigned(3);")]
    777        /// ```
    778        #[stable(feature = "strict_overflow_ops", since = "1.91.0")]
    779        #[rustc_const_stable(feature = "strict_overflow_ops", since = "1.91.0")]
    780        #[must_use = "this returns the result of the operation, \
    781                      without modifying the original"]
    782        #[inline]
    783        #[track_caller]
    784        pub const fn strict_sub_unsigned(self, rhs: $UnsignedT) -> Self {
    785            let (a, b) = self.overflowing_sub_unsigned(rhs);
    786            if b { overflow_panic::sub() } else { a }
    787        }
    788
    789        /// Checked integer multiplication. Computes `self * rhs`, returning `None` if
    790        /// overflow occurred.
    791        ///
    792        /// # Examples
    793        ///
    794        /// ```
    795        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_mul(1), Some(", stringify!($SelfT), "::MAX));")]
    796        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_mul(2), None);")]
    797        /// ```
    798        #[stable(feature = "rust1", since = "1.0.0")]
    799        #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
    800        #[must_use = "this returns the result of the operation, \
    801                      without modifying the original"]
    802        #[inline]
    803        pub const fn checked_mul(self, rhs: Self) -> Option<Self> {
    804            let (a, b) = self.overflowing_mul(rhs);
    805            if intrinsics::unlikely(b) { None } else { Some(a) }
    806        }
    807
    808        /// Strict integer multiplication. Computes `self * rhs`, panicking if
    809        /// overflow occurred.
    810        ///
    811        /// # Panics
    812        ///
    813        /// ## Overflow behavior
    814        ///
    815        /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
    816        ///
    817        /// # Examples
    818        ///
    819        /// ```
    820        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.strict_mul(1), ", stringify!($SelfT), "::MAX);")]
    821        /// ```
    822        ///
    823        /// The following panics because of overflow:
    824        ///
    825        /// ``` should_panic
    826        #[doc = concat!("let _ = ", stringify!($SelfT), "::MAX.strict_mul(2);")]
    827        /// ```
    828        #[stable(feature = "strict_overflow_ops", since = "1.91.0")]
    829        #[rustc_const_stable(feature = "strict_overflow_ops", since = "1.91.0")]
    830        #[must_use = "this returns the result of the operation, \
    831                      without modifying the original"]
    832        #[inline]
    833        #[track_caller]
    834        pub const fn strict_mul(self, rhs: Self) -> Self {
    835            let (a, b) = self.overflowing_mul(rhs);
    836            if b { overflow_panic::mul() } else { a }
    837        }
    838
    839        /// Unchecked integer multiplication. Computes `self * rhs`, assuming overflow
    840        /// cannot occur.
    841        ///
    842        /// Calling `x.unchecked_mul(y)` is semantically equivalent to calling
    843        /// `x.`[`checked_mul`]`(y).`[`unwrap_unchecked`]`()`.
    844        ///
    845        /// If you're just trying to avoid the panic in debug mode, then **do not**
    846        /// use this.  Instead, you're looking for [`wrapping_mul`].
    847        ///
    848        /// # Safety
    849        ///
    850        /// This results in undefined behavior when
    851        #[doc = concat!("`self * rhs > ", stringify!($SelfT), "::MAX` or `self * rhs < ", stringify!($SelfT), "::MIN`,")]
    852        /// i.e. when [`checked_mul`] would return `None`.
    853        ///
    854        /// [`unwrap_unchecked`]: option/enum.Option.html#method.unwrap_unchecked
    855        #[doc = concat!("[`checked_mul`]: ", stringify!($SelfT), "::checked_mul")]
    856        #[doc = concat!("[`wrapping_mul`]: ", stringify!($SelfT), "::wrapping_mul")]
    857        #[stable(feature = "unchecked_math", since = "1.79.0")]
    858        #[rustc_const_stable(feature = "unchecked_math", since = "1.79.0")]
    859        #[must_use = "this returns the result of the operation, \
    860                      without modifying the original"]
    861        #[inline(always)]
    862        #[track_caller]
    863        pub const unsafe fn unchecked_mul(self, rhs: Self) -> Self {
    864            assert_unsafe_precondition!(
    865                check_language_ub,
    866                concat!(stringify!($SelfT), "::unchecked_mul cannot overflow"),
    867                (
    868                    lhs: $SelfT = self,
    869                    rhs: $SelfT = rhs,
    870                ) => !lhs.overflowing_mul(rhs).1,
    871            );
    872
    873            // SAFETY: this is guaranteed to be safe by the caller.
    874            unsafe {
    875                intrinsics::unchecked_mul(self, rhs)
    876            }
    877        }
    878
    879        /// Checked integer division. Computes `self / rhs`, returning `None` if `rhs == 0`
    880        /// or the division results in overflow.
    881        ///
    882        /// # Examples
    883        ///
    884        /// ```
    885        #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 1).checked_div(-1), Some(", stringify!($Max), "));")]
    886        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_div(-1), None);")]
    887        #[doc = concat!("assert_eq!((1", stringify!($SelfT), ").checked_div(0), None);")]
    888        /// ```
    889        #[stable(feature = "rust1", since = "1.0.0")]
    890        #[rustc_const_stable(feature = "const_checked_int_div", since = "1.52.0")]
    891        #[must_use = "this returns the result of the operation, \
    892                      without modifying the original"]
    893        #[inline]
    894        pub const fn checked_div(self, rhs: Self) -> Option<Self> {
    895            if intrinsics::unlikely(rhs == 0 || ((self == Self::MIN) && (rhs == -1))) {
    896                None
    897            } else {
    898                // SAFETY: div by zero and by INT_MIN have been checked above
    899                Some(unsafe { intrinsics::unchecked_div(self, rhs) })
    900            }
    901        }
    902
    903        /// Strict integer division. Computes `self / rhs`, panicking
    904        /// if overflow occurred.
    905        ///
    906        /// # Panics
    907        ///
    908        /// This function will panic if `rhs` is zero.
    909        ///
    910        /// ## Overflow behavior
    911        ///
    912        /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
    913        ///
    914        /// The only case where such an overflow can occur is when one divides `MIN / -1` on a signed type (where
    915        /// `MIN` is the negative minimal value for the type); this is equivalent to `-MIN`, a positive value
    916        /// that is too large to represent in the type.
    917        ///
    918        /// # Examples
    919        ///
    920        /// ```
    921        #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 1).strict_div(-1), ", stringify!($Max), ");")]
    922        /// ```
    923        ///
    924        /// The following panics because of overflow:
    925        ///
    926        /// ```should_panic
    927        #[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.strict_div(-1);")]
    928        /// ```
    929        ///
    930        /// The following panics because of division by zero:
    931        ///
    932        /// ```should_panic
    933        #[doc = concat!("let _ = (1", stringify!($SelfT), ").strict_div(0);")]
    934        /// ```
    935        #[stable(feature = "strict_overflow_ops", since = "1.91.0")]
    936        #[rustc_const_stable(feature = "strict_overflow_ops", since = "1.91.0")]
    937        #[must_use = "this returns the result of the operation, \
    938                      without modifying the original"]
    939        #[inline]
    940        #[track_caller]
    941        pub const fn strict_div(self, rhs: Self) -> Self {
    942            let (a, b) = self.overflowing_div(rhs);
    943            if b { overflow_panic::div() } else { a }
    944        }
    945
    946        /// Checked Euclidean division. Computes `self.div_euclid(rhs)`,
    947        /// returning `None` if `rhs == 0` or the division results in overflow.
    948        ///
    949        /// # Examples
    950        ///
    951        /// ```
    952        #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 1).checked_div_euclid(-1), Some(", stringify!($Max), "));")]
    953        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_div_euclid(-1), None);")]
    954        #[doc = concat!("assert_eq!((1", stringify!($SelfT), ").checked_div_euclid(0), None);")]
    955        /// ```
    956        #[stable(feature = "euclidean_division", since = "1.38.0")]
    957        #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
    958        #[must_use = "this returns the result of the operation, \
    959                      without modifying the original"]
    960        #[inline]
    961        pub const fn checked_div_euclid(self, rhs: Self) -> Option<Self> {
    962            // Using `&` helps LLVM see that it is the same check made in division.
    963            if intrinsics::unlikely(rhs == 0 || ((self == Self::MIN) & (rhs == -1))) {
    964                None
    965            } else {
    966                Some(self.div_euclid(rhs))
    967            }
    968        }
    969
    970        /// Strict Euclidean division. Computes `self.div_euclid(rhs)`, panicking
    971        /// if overflow occurred.
    972        ///
    973        /// # Panics
    974        ///
    975        /// This function will panic if `rhs` is zero.
    976        ///
    977        /// ## Overflow behavior
    978        ///
    979        /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
    980        ///
    981        /// The only case where such an overflow can occur is when one divides `MIN / -1` on a signed type (where
    982        /// `MIN` is the negative minimal value for the type); this is equivalent to `-MIN`, a positive value
    983        /// that is too large to represent in the type.
    984        ///
    985        /// # Examples
    986        ///
    987        /// ```
    988        #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 1).strict_div_euclid(-1), ", stringify!($Max), ");")]
    989        /// ```
    990        ///
    991        /// The following panics because of overflow:
    992        ///
    993        /// ```should_panic
    994        #[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.strict_div_euclid(-1);")]
    995        /// ```
    996        ///
    997        /// The following panics because of division by zero:
    998        ///
    999        /// ```should_panic
    1000        #[doc = concat!("let _ = (1", stringify!($SelfT), ").strict_div_euclid(0);")]
    1001        /// ```
    1002        #[stable(feature = "strict_overflow_ops", since = "1.91.0")]
    1003        #[rustc_const_stable(feature = "strict_overflow_ops", since = "1.91.0")]
    1004        #[must_use = "this returns the result of the operation, \
    1005                      without modifying the original"]
    1006        #[inline]
    1007        #[track_caller]
    1008        pub const fn strict_div_euclid(self, rhs: Self) -> Self {
    1009            let (a, b) = self.overflowing_div_euclid(rhs);
    1010            if b { overflow_panic::div() } else { a }
    1011        }
    1012
    1013        /// Checked integer division without remainder. Computes `self / rhs`,
    1014        /// returning `None` if `rhs == 0`, the division results in overflow,
    1015        /// or `self % rhs != 0`.
    1016        ///
    1017        /// # Examples
    1018        ///
    1019        /// ```
    1020        /// #![feature(exact_div)]
    1021        #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 1).checked_div_exact(-1), Some(", stringify!($Max), "));")]
    1022        #[doc = concat!("assert_eq!((-5", stringify!($SelfT), ").checked_div_exact(2), None);")]
    1023        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_div_exact(-1), None);")]
    1024        #[doc = concat!("assert_eq!((1", stringify!($SelfT), ").checked_div_exact(0), None);")]
    1025        /// ```
    1026        #[unstable(
    1027            feature = "exact_div",
    1028            issue = "139911",
    1029        )]
    1030        #[must_use = "this returns the result of the operation, \
    1031                      without modifying the original"]
    1032        #[inline]
    1033        pub const fn checked_div_exact(self, rhs: Self) -> Option<Self> {
    1034            if intrinsics::unlikely(rhs == 0 || ((self == Self::MIN) && (rhs == -1))) {
    1035                None
    1036            } else {
    1037                // SAFETY: division by zero and overflow are checked above
    1038                unsafe {
    1039                    if intrinsics::unlikely(intrinsics::unchecked_rem(self, rhs) != 0) {
    1040                        None
    1041                    } else {
    1042                        Some(intrinsics::exact_div(self, rhs))
    1043                    }
    1044                }
    1045            }
    1046        }
    1047
    1048        /// Integer division without remainder. Computes `self / rhs`, returning `None` if `self % rhs != 0`.
    1049        ///
    1050        /// # Panics
    1051        ///
    1052        /// This function will panic  if `rhs == 0`.
    1053        ///
    1054        /// ## Overflow behavior
    1055        ///
    1056        /// On overflow, this function will panic if overflow checks are enabled (default in debug
    1057        /// mode) and wrap if overflow checks are disabled (default in release mode).
    1058        ///
    1059        /// # Examples
    1060        ///
    1061        /// ```
    1062        /// #![feature(exact_div)]
    1063        #[doc = concat!("assert_eq!(64", stringify!($SelfT), ".div_exact(2), Some(32));")]
    1064        #[doc = concat!("assert_eq!(64", stringify!($SelfT), ".div_exact(32), Some(2));")]
    1065        #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 1).div_exact(-1), Some(", stringify!($Max), "));")]
    1066        #[doc = concat!("assert_eq!(65", stringify!($SelfT), ".div_exact(2), None);")]
    1067        /// ```
    1068        /// ```should_panic
    1069        /// #![feature(exact_div)]
    1070        #[doc = concat!("let _ = 64", stringify!($SelfT),".div_exact(0);")]
    1071        /// ```
    1072        /// ```should_panic
    1073        /// #![feature(exact_div)]
    1074        #[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.div_exact(-1);")]
    1075        /// ```
    1076        #[unstable(
    1077            feature = "exact_div",
    1078            issue = "139911",
    1079        )]
    1080        #[must_use = "this returns the result of the operation, \
    1081                      without modifying the original"]
    1082        #[inline]
    1083        #[rustc_inherit_overflow_checks]
    1084        pub const fn div_exact(self, rhs: Self) -> Option<Self> {
    1085            if self % rhs != 0 {
    1086                None
    1087            } else {
    1088                Some(self / rhs)
    1089            }
    1090        }
    1091
    1092        /// Unchecked integer division without remainder. Computes `self / rhs`.
    1093        ///
    1094        /// # Safety
    1095        ///
    1096        /// This results in undefined behavior when `rhs == 0`, `self % rhs != 0`, or
    1097        #[doc = concat!("`self == ", stringify!($SelfT), "::MIN && rhs == -1`,")]
    1098        /// i.e. when [`checked_div_exact`](Self::checked_div_exact) would return `None`.
    1099        #[unstable(
    1100            feature = "exact_div",
    1101            issue = "139911",
    1102        )]
    1103        #[must_use = "this returns the result of the operation, \
    1104                      without modifying the original"]
    1105        #[inline]
    1106        pub const unsafe fn unchecked_div_exact(self, rhs: Self) -> Self {
    1107            assert_unsafe_precondition!(
    1108                check_language_ub,
    1109                concat!(stringify!($SelfT), "::unchecked_div_exact cannot overflow, divide by zero, or leave a remainder"),
    1110                (
    1111                    lhs: $SelfT = self,
    1112                    rhs: $SelfT = rhs,
    1113                ) => rhs > 0 && lhs % rhs == 0 && (lhs != <$SelfT>::MIN || rhs != -1),
    1114            );
    1115            // SAFETY: Same precondition
    1116            unsafe { intrinsics::exact_div(self, rhs) }
    1117        }
    1118
    1119        /// Checked integer remainder. Computes `self % rhs`, returning `None` if
    1120        /// `rhs == 0` or the division results in overflow.
    1121        ///
    1122        /// # Examples
    1123        ///
    1124        /// ```
    1125        #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem(2), Some(1));")]
    1126        #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem(0), None);")]
    1127        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_rem(-1), None);")]
    1128        /// ```
    1129        #[stable(feature = "wrapping", since = "1.7.0")]
    1130        #[rustc_const_stable(feature = "const_checked_int_div", since = "1.52.0")]
    1131        #[must_use = "this returns the result of the operation, \
    1132                      without modifying the original"]
    1133        #[inline]
    1134        pub const fn checked_rem(self, rhs: Self) -> Option<Self> {
    1135            if intrinsics::unlikely(rhs == 0 || ((self == Self::MIN) && (rhs == -1))) {
    1136                None
    1137            } else {
    1138                // SAFETY: div by zero and by INT_MIN have been checked above
    1139                Some(unsafe { intrinsics::unchecked_rem(self, rhs) })
    1140            }
    1141        }
    1142
    1143        /// Strict integer remainder. Computes `self % rhs`, panicking if
    1144        /// the division results in overflow.
    1145        ///
    1146        /// # Panics
    1147        ///
    1148        /// This function will panic if `rhs` is zero.
    1149        ///
    1150        /// ## Overflow behavior
    1151        ///
    1152        /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
    1153        ///
    1154        /// The only case where such an overflow can occur is `x % y` for `MIN / -1` on a
    1155        /// signed type (where `MIN` is the negative minimal value), which is invalid due to implementation artifacts.
    1156        ///
    1157        /// # Examples
    1158        ///
    1159        /// ```
    1160        #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".strict_rem(2), 1);")]
    1161        /// ```
    1162        ///
    1163        /// The following panics because of division by zero:
    1164        ///
    1165        /// ```should_panic
    1166        #[doc = concat!("let _ = 5", stringify!($SelfT), ".strict_rem(0);")]
    1167        /// ```
    1168        ///
    1169        /// The following panics because of overflow:
    1170        ///
    1171        /// ```should_panic
    1172        #[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.strict_rem(-1);")]
    1173        /// ```
    1174        #[stable(feature = "strict_overflow_ops", since = "1.91.0")]
    1175        #[rustc_const_stable(feature = "strict_overflow_ops", since = "1.91.0")]
    1176        #[must_use = "this returns the result of the operation, \
    1177                      without modifying the original"]
    1178        #[inline]
    1179        #[track_caller]
    1180        pub const fn strict_rem(self, rhs: Self) -> Self {
    1181            let (a, b) = self.overflowing_rem(rhs);
    1182            if b { overflow_panic::rem() } else { a }
    1183        }
    1184
    1185        /// Checked Euclidean remainder. Computes `self.rem_euclid(rhs)`, returning `None`
    1186        /// if `rhs == 0` or the division results in overflow.
    1187        ///
    1188        /// # Examples
    1189        ///
    1190        /// ```
    1191        #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem_euclid(2), Some(1));")]
    1192        #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem_euclid(0), None);")]
    1193        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_rem_euclid(-1), None);")]
    1194        /// ```
    1195        #[stable(feature = "euclidean_division", since = "1.38.0")]
    1196        #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
    1197        #[must_use = "this returns the result of the operation, \
    1198                      without modifying the original"]
    1199        #[inline]
    1200        pub const fn checked_rem_euclid(self, rhs: Self) -> Option<Self> {
    1201            // Using `&` helps LLVM see that it is the same check made in division.
    1202            if intrinsics::unlikely(rhs == 0 || ((self == Self::MIN) & (rhs == -1))) {
    1203                None
    1204            } else {
    1205                Some(self.rem_euclid(rhs))
    1206            }
    1207        }
    1208
    1209        /// Strict Euclidean remainder. Computes `self.rem_euclid(rhs)`, panicking if
    1210        /// the division results in overflow.
    1211        ///
    1212        /// # Panics
    1213        ///
    1214        /// This function will panic if `rhs` is zero.
    1215        ///
    1216        /// ## Overflow behavior
    1217        ///
    1218        /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
    1219        ///
    1220        /// The only case where such an overflow can occur is `x % y` for `MIN / -1` on a
    1221        /// signed type (where `MIN` is the negative minimal value), which is invalid due to implementation artifacts.
    1222        ///
    1223        /// # Examples
    1224        ///
    1225        /// ```
    1226        #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".strict_rem_euclid(2), 1);")]
    1227        /// ```
    1228        ///
    1229        /// The following panics because of division by zero:
    1230        ///
    1231        /// ```should_panic
    1232        #[doc = concat!("let _ = 5", stringify!($SelfT), ".strict_rem_euclid(0);")]
    1233        /// ```
    1234        ///
    1235        /// The following panics because of overflow:
    1236        ///
    1237        /// ```should_panic
    1238        #[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.strict_rem_euclid(-1);")]
    1239        /// ```
    1240        #[stable(feature = "strict_overflow_ops", since = "1.91.0")]
    1241        #[rustc_const_stable(feature = "strict_overflow_ops", since = "1.91.0")]
    1242        #[must_use = "this returns the result of the operation, \
    1243                      without modifying the original"]
    1244        #[inline]
    1245        #[track_caller]
    1246        pub const fn strict_rem_euclid(self, rhs: Self) -> Self {
    1247            let (a, b) = self.overflowing_rem_euclid(rhs);
    1248            if b { overflow_panic::rem() } else { a }
    1249        }
    1250
    1251        /// Checked negation. Computes `-self`, returning `None` if `self == MIN`.
    1252        ///
    1253        /// # Examples
    1254        ///
    1255        /// ```
    1256        #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_neg(), Some(-5));")]
    1257        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_neg(), None);")]
    1258        /// ```
    1259        #[stable(feature = "wrapping", since = "1.7.0")]
    1260        #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
    1261        #[must_use = "this returns the result of the operation, \
    1262                      without modifying the original"]
    1263        #[inline]
    1264        pub const fn checked_neg(self) -> Option<Self> {
    1265            let (a, b) = self.overflowing_neg();
    1266            if intrinsics::unlikely(b) { None } else { Some(a) }
    1267        }
    1268
    1269        /// Unchecked negation. Computes `-self`, assuming overflow cannot occur.
    1270        ///
    1271        /// # Safety
    1272        ///
    1273        /// This results in undefined behavior when
    1274        #[doc = concat!("`self == ", stringify!($SelfT), "::MIN`,")]
    1275        /// i.e. when [`checked_neg`] would return `None`.
    1276        ///
    1277        #[doc = concat!("[`checked_neg`]: ", stringify!($SelfT), "::checked_neg")]
    1278        #[stable(feature = "unchecked_neg", since = "1.93.0")]
    1279        #[rustc_const_stable(feature = "unchecked_neg", since = "1.93.0")]
    1280        #[must_use = "this returns the result of the operation, \
    1281                      without modifying the original"]
    1282        #[inline(always)]
    1283        #[track_caller]
    1284        pub const unsafe fn unchecked_neg(self) -> Self {
    1285            assert_unsafe_precondition!(
    1286                check_language_ub,
    1287                concat!(stringify!($SelfT), "::unchecked_neg cannot overflow"),
    1288                (
    1289                    lhs: $SelfT = self,
    1290                ) => !lhs.overflowing_neg().1,
    1291            );
    1292
    1293            // SAFETY: this is guaranteed to be safe by the caller.
    1294            unsafe {
    1295                intrinsics::unchecked_sub(0, self)
    1296            }
    1297        }
    1298
    1299        /// Strict negation. Computes `-self`, panicking if `self == MIN`.
    1300        ///
    1301        /// # Panics
    1302        ///
    1303        /// ## Overflow behavior
    1304        ///
    1305        /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
    1306        ///
    1307        /// # Examples
    1308        ///
    1309        /// ```
    1310        #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".strict_neg(), -5);")]
    1311        /// ```
    1312        ///
    1313        /// The following panics because of overflow:
    1314        ///
    1315        /// ```should_panic
    1316        #[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.strict_neg();")]
    1317        /// ```
    1318        #[stable(feature = "strict_overflow_ops", since = "1.91.0")]
    1319        #[rustc_const_stable(feature = "strict_overflow_ops", since = "1.91.0")]
    1320        #[must_use = "this returns the result of the operation, \
    1321                      without modifying the original"]
    1322        #[inline]
    1323        #[track_caller]
    1324        pub const fn strict_neg(self) -> Self {
    1325            let (a, b) = self.overflowing_neg();
    1326            if b { overflow_panic::neg() } else { a }
    1327        }
    1328
    1329        /// Checked shift left. Computes `self << rhs`, returning `None` if `rhs` is larger
    1330        /// than or equal to the number of bits in `self`.
    1331        ///
    1332        /// # Examples
    1333        ///
    1334        /// ```
    1335        #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".checked_shl(4), Some(0x10));")]
    1336        #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".checked_shl(129), None);")]
    1337        #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".checked_shl(", stringify!($BITS_MINUS_ONE), "), Some(0));")]
    1338        /// ```
    1339        #[stable(feature = "wrapping", since = "1.7.0")]
    1340        #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
    1341        #[must_use = "this returns the result of the operation, \
    1342                      without modifying the original"]
    1343        #[inline]
    1344        pub const fn checked_shl(self, rhs: u32) -> Option<Self> {
    1345            // Not using overflowing_shl as that's a wrapping shift
    1346            if rhs < Self::BITS {
    1347                // SAFETY: just checked the RHS is in-range
    1348                Some(unsafe { self.unchecked_shl(rhs) })
    1349            } else {
    1350                None
    1351            }
    1352        }
    1353
    1354        /// Strict shift left. Computes `self << rhs`, panicking if `rhs` is larger
    1355        /// than or equal to the number of bits in `self`.
    1356        ///
    1357        /// # Panics
    1358        ///
    1359        /// ## Overflow behavior
    1360        ///
    1361        /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
    1362        ///
    1363        /// # Examples
    1364        ///
    1365        /// ```
    1366        #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".strict_shl(4), 0x10);")]
    1367        /// ```
    1368        ///
    1369        /// The following panics because of overflow:
    1370        ///
    1371        /// ```should_panic
    1372        #[doc = concat!("let _ = 0x1", stringify!($SelfT), ".strict_shl(129);")]
    1373        /// ```
    1374        #[stable(feature = "strict_overflow_ops", since = "1.91.0")]
    1375        #[rustc_const_stable(feature = "strict_overflow_ops", since = "1.91.0")]
    1376        #[must_use = "this returns the result of the operation, \
    1377                      without modifying the original"]
    1378        #[inline]
    1379        #[track_caller]
    1380        pub const fn strict_shl(self, rhs: u32) -> Self {
    1381            let (a, b) = self.overflowing_shl(rhs);
    1382            if b { overflow_panic::shl() } else { a }
    1383        }
    1384
    1385        /// Unchecked shift left. Computes `self << rhs`, assuming that
    1386        /// `rhs` is less than the number of bits in `self`.
    1387        ///
    1388        /// # Safety
    1389        ///
    1390        /// This results in undefined behavior if `rhs` is larger than
    1391        /// or equal to the number of bits in `self`,
    1392        /// i.e. when [`checked_shl`] would return `None`.
    1393        ///
    1394        #[doc = concat!("[`checked_shl`]: ", stringify!($SelfT), "::checked_shl")]
    1395        #[stable(feature = "unchecked_shifts", since = "1.93.0")]
    1396        #[rustc_const_stable(feature = "unchecked_shifts", since = "1.93.0")]
    1397        #[must_use = "this returns the result of the operation, \
    1398                      without modifying the original"]
    1399        #[inline(always)]
    1400        #[track_caller]
    1401        pub const unsafe fn unchecked_shl(self, rhs: u32) -> Self {
    1402            assert_unsafe_precondition!(
    1403                check_language_ub,
    1404                concat!(stringify!($SelfT), "::unchecked_shl cannot overflow"),
    1405                (
    1406                    rhs: u32 = rhs,
    1407                ) => rhs < <$ActualT>::BITS,
    1408            );
    1409
    1410            // SAFETY: this is guaranteed to be safe by the caller.
    1411            unsafe {
    1412                intrinsics::unchecked_shl(self, rhs)
    1413            }
    1414        }
    1415
    1416        /// Unbounded shift left. Computes `self << rhs`, without bounding the value of `rhs`.
    1417        ///
    1418        /// If `rhs` is larger or equal to the number of bits in `self`,
    1419        /// the entire value is shifted out, and `0` is returned.
    1420        ///
    1421        /// # Examples
    1422        ///
    1423        /// ```
    1424        #[doc = concat!("assert_eq!(0x1_", stringify!($SelfT), ".unbounded_shl(4), 0x10);")]
    1425        #[doc = concat!("assert_eq!(0x1_", stringify!($SelfT), ".unbounded_shl(129), 0);")]
    1426        #[doc = concat!("assert_eq!(0b101_", stringify!($SelfT), ".unbounded_shl(0), 0b101);")]
    1427        #[doc = concat!("assert_eq!(0b101_", stringify!($SelfT), ".unbounded_shl(1), 0b1010);")]
    1428        #[doc = concat!("assert_eq!(0b101_", stringify!($SelfT), ".unbounded_shl(2), 0b10100);")]
    1429        #[doc = concat!("assert_eq!(42_", stringify!($SelfT), ".unbounded_shl(", stringify!($BITS), "), 0);")]
    1430        #[doc = concat!("assert_eq!(42_", stringify!($SelfT), ".unbounded_shl(1).unbounded_shl(", stringify!($BITS_MINUS_ONE), "), 0);")]
    1431        #[doc = concat!("assert_eq!((-13_", stringify!($SelfT), ").unbounded_shl(", stringify!($BITS), "), 0);")]
    1432        #[doc = concat!("assert_eq!((-13_", stringify!($SelfT), ").unbounded_shl(1).unbounded_shl(", stringify!($BITS_MINUS_ONE), "), 0);")]
    1433        /// ```
    1434        #[stable(feature = "unbounded_shifts", since = "1.87.0")]
    1435        #[rustc_const_stable(feature = "unbounded_shifts", since = "1.87.0")]
    1436        #[must_use = "this returns the result of the operation, \
    1437                      without modifying the original"]
    1438        #[inline]
    1439        pub const fn unbounded_shl(self, rhs: u32) -> $SelfT{
    1440            if rhs < Self::BITS {
    1441                // SAFETY:
    1442                // rhs is just checked to be in-range above
    1443                unsafe { self.unchecked_shl(rhs) }
    1444            } else {
    1445                0
    1446            }
    1447        }
    1448
    1449        /// Exact shift left. Computes `self << rhs` as long as it can be reversed losslessly.
    1450        ///
    1451        /// Returns `None` if any bits that would be shifted out differ from the resulting sign bit
    1452        /// or if `rhs` >=
    1453        #[doc = concat!("`", stringify!($SelfT), "::BITS`.")]
    1454        /// Otherwise, returns `Some(self << rhs)`.
    1455        ///
    1456        /// # Examples
    1457        ///
    1458        /// ```
    1459        /// #![feature(exact_bitshifts)]
    1460        ///
    1461        #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".shl_exact(4), Some(0x10));")]
    1462        #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".shl_exact(", stringify!($SelfT), "::BITS - 2), Some(1 << ", stringify!($SelfT), "::BITS - 2));")]
    1463        #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".shl_exact(", stringify!($SelfT), "::BITS - 1), None);")]
    1464        #[doc = concat!("assert_eq!((-0x2", stringify!($SelfT), ").shl_exact(", stringify!($SelfT), "::BITS - 2), Some(-0x2 << ", stringify!($SelfT), "::BITS - 2));")]
    1465        #[doc = concat!("assert_eq!((-0x2", stringify!($SelfT), ").shl_exact(", stringify!($SelfT), "::BITS - 1), None);")]
    1466        /// ```
    1467        #[unstable(feature = "exact_bitshifts", issue = "144336")]
    1468        #[must_use = "this returns the result of the operation, \
    1469                      without modifying the original"]
    1470        #[inline]
    1471        pub const fn shl_exact(self, rhs: u32) -> Option<$SelfT> {
    1472            if rhs < self.leading_zeros() || rhs < self.leading_ones() {
    1473                // SAFETY: rhs is checked above
    1474                Some(unsafe { self.unchecked_shl(rhs) })
    1475            } else {
    1476                None
    1477            }
    1478        }
    1479
    1480        /// Unchecked exact shift left. Computes `self << rhs`, assuming the operation can be
    1481        /// losslessly reversed and `rhs` cannot be larger than
    1482        #[doc = concat!("`", stringify!($SelfT), "::BITS`.")]
    1483        ///
    1484        /// # Safety
    1485        ///
    1486        /// This results in undefined behavior when `rhs >= self.leading_zeros() && rhs >=
    1487        /// self.leading_ones()` i.e. when
    1488        #[doc = concat!("[`", stringify!($SelfT), "::shl_exact`]")]
    1489        /// would return `None`.
    1490        #[unstable(feature = "exact_bitshifts", issue = "144336")]
    1491        #[must_use = "this returns the result of the operation, \
    1492                      without modifying the original"]
    1493        #[inline]
    1494        pub const unsafe fn unchecked_shl_exact(self, rhs: u32) -> $SelfT {
    1495            assert_unsafe_precondition!(
    1496                check_library_ub,
    1497                concat!(stringify!($SelfT), "::unchecked_shl_exact cannot shift out bits that would change the value of the first bit"),
    1498                (
    1499                    zeros: u32 = self.leading_zeros(),
    1500                    ones: u32 = self.leading_ones(),
    1501                    rhs: u32 = rhs,
    1502                ) => rhs < zeros || rhs < ones,
    1503            );
    1504
    1505            // SAFETY: this is guaranteed to be safe by the caller
    1506            unsafe { self.unchecked_shl(rhs) }
    1507        }
    1508
    1509        /// Checked shift right. Computes `self >> rhs`, returning `None` if `rhs` is
    1510        /// larger than or equal to the number of bits in `self`.
    1511        ///
    1512        /// # Examples
    1513        ///
    1514        /// ```
    1515        #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".checked_shr(4), Some(0x1));")]
    1516        #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".checked_shr(128), None);")]
    1517        /// ```
    1518        #[stable(feature = "wrapping", since = "1.7.0")]
    1519        #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
    1520        #[must_use = "this returns the result of the operation, \
    1521                      without modifying the original"]
    1522        #[inline]
    1523        pub const fn checked_shr(self, rhs: u32) -> Option<Self> {
    1524            // Not using overflowing_shr as that's a wrapping shift
    1525            if rhs < Self::BITS {
    1526                // SAFETY: just checked the RHS is in-range
    1527                Some(unsafe { self.unchecked_shr(rhs) })
    1528            } else {
    1529                None
    1530            }
    1531        }
    1532
    1533        /// Strict shift right. Computes `self >> rhs`, panicking if `rhs` is
    1534        /// larger than or equal to the number of bits in `self`.
    1535        ///
    1536        /// # Panics
    1537        ///
    1538        /// ## Overflow behavior
    1539        ///
    1540        /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
    1541        ///
    1542        /// # Examples
    1543        ///
    1544        /// ```
    1545        #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".strict_shr(4), 0x1);")]
    1546        /// ```
    1547        ///
    1548        /// The following panics because of overflow:
    1549        ///
    1550        /// ```should_panic
    1551        #[doc = concat!("let _ = 0x10", stringify!($SelfT), ".strict_shr(128);")]
    1552        /// ```
    1553        #[stable(feature = "strict_overflow_ops", since = "1.91.0")]
    1554        #[rustc_const_stable(feature = "strict_overflow_ops", since = "1.91.0")]
    1555        #[must_use = "this returns the result of the operation, \
    1556                      without modifying the original"]
    1557        #[inline]
    1558        #[track_caller]
    1559        pub const fn strict_shr(self, rhs: u32) -> Self {
    1560            let (a, b) = self.overflowing_shr(rhs);
    1561            if b { overflow_panic::shr() } else { a }
    1562        }
    1563
    1564        /// Unchecked shift right. Computes `self >> rhs`, assuming that
    1565        /// `rhs` is less than the number of bits in `self`.
    1566        ///
    1567        /// # Safety
    1568        ///
    1569        /// This results in undefined behavior if `rhs` is larger than
    1570        /// or equal to the number of bits in `self`,
    1571        /// i.e. when [`checked_shr`] would return `None`.
    1572        ///
    1573        #[doc = concat!("[`checked_shr`]: ", stringify!($SelfT), "::checked_shr")]
    1574        #[stable(feature = "unchecked_shifts", since = "1.93.0")]
    1575        #[rustc_const_stable(feature = "unchecked_shifts", since = "1.93.0")]
    1576        #[must_use = "this returns the result of the operation, \
    1577                      without modifying the original"]
    1578        #[inline(always)]
    1579        #[track_caller]
    1580        pub const unsafe fn unchecked_shr(self, rhs: u32) -> Self {
    1581            assert_unsafe_precondition!(
    1582                check_language_ub,
    1583                concat!(stringify!($SelfT), "::unchecked_shr cannot overflow"),
    1584                (
    1585                    rhs: u32 = rhs,
    1586                ) => rhs < <$ActualT>::BITS,
    1587            );
    1588
    1589            // SAFETY: this is guaranteed to be safe by the caller.
    1590            unsafe {
    1591                intrinsics::unchecked_shr(self, rhs)
    1592            }
    1593        }
    1594
    1595        /// Unbounded shift right. Computes `self >> rhs`, without bounding the value of `rhs`.
    1596        ///
    1597        /// If `rhs` is larger or equal to the number of bits in `self`,
    1598        /// the entire value is shifted out, which yields `0` for a positive number,
    1599        /// and `-1` for a negative number.
    1600        ///
    1601        /// # Examples
    1602        ///
    1603        /// ```
    1604        #[doc = concat!("assert_eq!(0x10_", stringify!($SelfT), ".unbounded_shr(4), 0x1);")]
    1605        #[doc = concat!("assert_eq!(0x10_", stringify!($SelfT), ".unbounded_shr(129), 0);")]
    1606        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.unbounded_shr(129), -1);")]
    1607        #[doc = concat!("assert_eq!(0b1010_", stringify!($SelfT), ".unbounded_shr(0), 0b1010);")]
    1608        #[doc = concat!("assert_eq!(0b1010_", stringify!($SelfT), ".unbounded_shr(1), 0b101);")]
    1609        #[doc = concat!("assert_eq!(0b1010_", stringify!($SelfT), ".unbounded_shr(2), 0b10);")]
    1610        #[doc = concat!("assert_eq!(42_", stringify!($SelfT), ".unbounded_shr(", stringify!($BITS), "), 0);")]
    1611        #[doc = concat!("assert_eq!(42_", stringify!($SelfT), ".unbounded_shr(1).unbounded_shr(", stringify!($BITS_MINUS_ONE), "), 0);")]
    1612        #[doc = concat!("assert_eq!((-13_", stringify!($SelfT), ").unbounded_shr(", stringify!($BITS), "), -1);")]
    1613        #[doc = concat!("assert_eq!((-13_", stringify!($SelfT), ").unbounded_shr(1).unbounded_shr(", stringify!($BITS_MINUS_ONE), "), -1);")]
    1614        /// ```
    1615        #[stable(feature = "unbounded_shifts", since = "1.87.0")]
    1616        #[rustc_const_stable(feature = "unbounded_shifts", since = "1.87.0")]
    1617        #[must_use = "this returns the result of the operation, \
    1618                      without modifying the original"]
    1619        #[inline]
    1620        pub const fn unbounded_shr(self, rhs: u32) -> $SelfT{
    1621            if rhs < Self::BITS {
    1622                // SAFETY:
    1623                // rhs is just checked to be in-range above
    1624                unsafe { self.unchecked_shr(rhs) }
    1625            } else {
    1626                // A shift by `Self::BITS-1` suffices for signed integers, because the sign bit is copied for each of the shifted bits.
    1627
    1628                // SAFETY:
    1629                // `Self::BITS-1` is guaranteed to be less than `Self::BITS`
    1630                unsafe { self.unchecked_shr(Self::BITS - 1) }
    1631            }
    1632        }
    1633
    1634        /// Exact shift right. Computes `self >> rhs` as long as it can be reversed losslessly.
    1635        ///
    1636        /// Returns `None` if any non-zero bits would be shifted out or if `rhs` >=
    1637        #[doc = concat!("`", stringify!($SelfT), "::BITS`.")]
    1638        /// Otherwise, returns `Some(self >> rhs)`.
    1639        ///
    1640        /// # Examples
    1641        ///
    1642        /// ```
    1643        /// #![feature(exact_bitshifts)]
    1644        ///
    1645        #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".shr_exact(4), Some(0x1));")]
    1646        #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".shr_exact(5), None);")]
    1647        /// ```
    1648        #[unstable(feature = "exact_bitshifts", issue = "144336")]
    1649        #[must_use = "this returns the result of the operation, \
    1650                      without modifying the original"]
    1651        #[inline]
    1652        pub const fn shr_exact(self, rhs: u32) -> Option<$SelfT> {
    1653            if rhs <= self.trailing_zeros() && rhs < <$SelfT>::BITS {
    1654                // SAFETY: rhs is checked above
    1655                Some(unsafe { self.unchecked_shr(rhs) })
    1656            } else {
    1657                None
    1658            }
    1659        }
    1660
    1661        /// Unchecked exact shift right. Computes `self >> rhs`, assuming the operation can be
    1662        /// losslessly reversed and `rhs` cannot be larger than
    1663        #[doc = concat!("`", stringify!($SelfT), "::BITS`.")]
    1664        ///
    1665        /// # Safety
    1666        ///
    1667        /// This results in undefined behavior when `rhs > self.trailing_zeros() || rhs >=
    1668        #[doc = concat!(stringify!($SelfT), "::BITS`")]
    1669        /// i.e. when
    1670        #[doc = concat!("[`", stringify!($SelfT), "::shr_exact`]")]
    1671        /// would return `None`.
    1672        #[unstable(feature = "exact_bitshifts", issue = "144336")]
    1673        #[must_use = "this returns the result of the operation, \
    1674                      without modifying the original"]
    1675        #[inline]
    1676        pub const unsafe fn unchecked_shr_exact(self, rhs: u32) -> $SelfT {
    1677            assert_unsafe_precondition!(
    1678                check_library_ub,
    1679                concat!(stringify!($SelfT), "::unchecked_shr_exact cannot shift out non-zero bits"),
    1680                (
    1681                    zeros: u32 = self.trailing_zeros(),
    1682                    bits: u32 =  <$SelfT>::BITS,
    1683                    rhs: u32 = rhs,
    1684                ) => rhs <= zeros && rhs < bits,
    1685            );
    1686
    1687            // SAFETY: this is guaranteed to be safe by the caller
    1688            unsafe { self.unchecked_shr(rhs) }
    1689        }
    1690
    1691        /// Checked absolute value. Computes `self.abs()`, returning `None` if
    1692        /// `self == MIN`.
    1693        ///
    1694        /// # Examples
    1695        ///
    1696        /// ```
    1697        #[doc = concat!("assert_eq!((-5", stringify!($SelfT), ").checked_abs(), Some(5));")]
    1698        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_abs(), None);")]
    1699        /// ```
    1700        #[stable(feature = "no_panic_abs", since = "1.13.0")]
    1701        #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
    1702        #[must_use = "this returns the result of the operation, \
    1703                      without modifying the original"]
    1704        #[inline]
    1705        pub const fn checked_abs(self) -> Option<Self> {
    1706            if self.is_negative() {
    1707                self.checked_neg()
    1708            } else {
    1709                Some(self)
    1710            }
    1711        }
    1712
    1713        /// Strict absolute value. Computes `self.abs()`, panicking if
    1714        /// `self == MIN`.
    1715        ///
    1716        /// # Panics
    1717        ///
    1718        /// ## Overflow behavior
    1719        ///
    1720        /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
    1721        ///
    1722        /// # Examples
    1723        ///
    1724        /// ```
    1725        #[doc = concat!("assert_eq!((-5", stringify!($SelfT), ").strict_abs(), 5);")]
    1726        /// ```
    1727        ///
    1728        /// The following panics because of overflow:
    1729        ///
    1730        /// ```should_panic
    1731        #[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.strict_abs();")]
    1732        /// ```
    1733        #[stable(feature = "strict_overflow_ops", since = "1.91.0")]
    1734        #[rustc_const_stable(feature = "strict_overflow_ops", since = "1.91.0")]
    1735        #[must_use = "this returns the result of the operation, \
    1736                      without modifying the original"]
    1737        #[inline]
    1738        #[track_caller]
    1739        pub const fn strict_abs(self) -> Self {
    1740            if self.is_negative() {
    1741                self.strict_neg()
    1742            } else {
    1743                self
    1744            }
    1745        }
    1746
    1747        /// Checked exponentiation. Computes `self.pow(exp)`, returning `None` if
    1748        /// overflow occurred.
    1749        ///
    1750        /// # Examples
    1751        ///
    1752        /// ```
    1753        #[doc = concat!("assert_eq!(8", stringify!($SelfT), ".checked_pow(2), Some(64));")]
    1754        #[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".checked_pow(0), Some(1));")]
    1755        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_pow(2), None);")]
    1756        /// ```
    1757
    1758        #[stable(feature = "no_panic_pow", since = "1.34.0")]
    1759        #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
    1760        #[must_use = "this returns the result of the operation, \
    1761                      without modifying the original"]
    1762        #[inline]
    1763        pub const fn checked_pow(self, mut exp: u32) -> Option<Self> {
    1764            if exp == 0 {
    1765                return Some(1);
    1766            }
    1767            let mut base = self;
    1768            let mut acc: Self = 1;
    1769
    1770            loop {
    1771                if (exp & 1) == 1 {
    1772                    acc = try_opt!(acc.checked_mul(base));
    1773                    // since exp!=0, finally the exp must be 1.
    1774                    if exp == 1 {
    1775                        return Some(acc);
    1776                    }
    1777                }
    1778                exp /= 2;
    1779                base = try_opt!(base.checked_mul(base));
    1780            }
    1781        }
    1782
    1783        /// Strict exponentiation. Computes `self.pow(exp)`, panicking if
    1784        /// overflow occurred.
    1785        ///
    1786        /// # Panics
    1787        ///
    1788        /// ## Overflow behavior
    1789        ///
    1790        /// This function will always panic on overflow, regardless of whether overflow checks are enabled.
    1791        ///
    1792        /// # Examples
    1793        ///
    1794        /// ```
    1795        #[doc = concat!("assert_eq!(8", stringify!($SelfT), ".strict_pow(2), 64);")]
    1796        #[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".strict_pow(0), 1);")]
    1797        /// ```
    1798        ///
    1799        /// The following panics because of overflow:
    1800        ///
    1801        /// ```should_panic
    1802        #[doc = concat!("let _ = ", stringify!($SelfT), "::MAX.strict_pow(2);")]
    1803        /// ```
    1804        #[stable(feature = "strict_overflow_ops", since = "1.91.0")]
    1805        #[rustc_const_stable(feature = "strict_overflow_ops", since = "1.91.0")]
    1806        #[must_use = "this returns the result of the operation, \
    1807                      without modifying the original"]
    1808        #[inline]
    1809        #[track_caller]
    1810        pub const fn strict_pow(self, mut exp: u32) -> Self {
    1811            if exp == 0 {
    1812                return 1;
    1813            }
    1814            let mut base = self;
    1815            let mut acc: Self = 1;
    1816
    1817            loop {
    1818                if (exp & 1) == 1 {
    1819                    acc = acc.strict_mul(base);
    1820                    // since exp!=0, finally the exp must be 1.
    1821                    if exp == 1 {
    1822                        return acc;
    1823                    }
    1824                }
    1825                exp /= 2;
    1826                base = base.strict_mul(base);
    1827            }
    1828        }
    1829
    1830        /// Returns the square root of the number, rounded down.
    1831        ///
    1832        /// Returns `None` if `self` is negative.
    1833        ///
    1834        /// # Examples
    1835        ///
    1836        /// ```
    1837        #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".checked_isqrt(), Some(3));")]
    1838        /// ```
    1839        #[stable(feature = "isqrt", since = "1.84.0")]
    1840        #[rustc_const_stable(feature = "isqrt", since = "1.84.0")]
    1841        #[must_use = "this returns the result of the operation, \
    1842                      without modifying the original"]
    1843        #[inline]
    1844        pub const fn checked_isqrt(self) -> Option<Self> {
    1845            if self < 0 {
    1846                None
    1847            } else {
    1848                // SAFETY: Input is nonnegative in this `else` branch.
    1849                let result = unsafe {
    1850                    crate::num::int_sqrt::$ActualT(self as $ActualT) as $SelfT
    1851                };
    1852
    1853                // Inform the optimizer what the range of outputs is. If
    1854                // testing `core` crashes with no panic message and a
    1855                // `num::int_sqrt::i*` test failed, it's because your edits
    1856                // caused these assertions to become false.
    1857                //
    1858                // SAFETY: Integer square root is a monotonically nondecreasing
    1859                // function, which means that increasing the input will never
    1860                // cause the output to decrease. Thus, since the input for
    1861                // nonnegative signed integers is bounded by
    1862                // `[0, <$ActualT>::MAX]`, sqrt(n) will be bounded by
    1863                // `[sqrt(0), sqrt(<$ActualT>::MAX)]`.
    1864                unsafe {
    1865                    // SAFETY: `<$ActualT>::MAX` is nonnegative.
    1866                    const MAX_RESULT: $SelfT = unsafe {
    1867                        crate::num::int_sqrt::$ActualT(<$ActualT>::MAX) as $SelfT
    1868                    };
    1869
    1870                    crate::hint::assert_unchecked(result >= 0);
    1871                    crate::hint::assert_unchecked(result <= MAX_RESULT);
    1872                }
    1873
    1874                Some(result)
    1875            }
    1876        }
    1877
    1878        /// Saturating integer addition. Computes `self + rhs`, saturating at the numeric
    1879        /// bounds instead of overflowing.
    1880        ///
    1881        /// # Examples
    1882        ///
    1883        /// ```
    1884        #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_add(1), 101);")]
    1885        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_add(100), ", stringify!($SelfT), "::MAX);")]
    1886        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_add(-1), ", stringify!($SelfT), "::MIN);")]
    1887        /// ```
    1888
    1889        #[stable(feature = "rust1", since = "1.0.0")]
    1890        #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")]
    1891        #[must_use = "this returns the result of the operation, \
    1892                      without modifying the original"]
    1893        #[inline(always)]
    1894        pub const fn saturating_add(self, rhs: Self) -> Self {
    1895            intrinsics::saturating_add(self, rhs)
    1896        }
    1897
    1898        /// Saturating addition with an unsigned integer. Computes `self + rhs`,
    1899        /// saturating at the numeric bounds instead of overflowing.
    1900        ///
    1901        /// # Examples
    1902        ///
    1903        /// ```
    1904        #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".saturating_add_unsigned(2), 3);")]
    1905        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_add_unsigned(100), ", stringify!($SelfT), "::MAX);")]
    1906        /// ```
    1907        #[stable(feature = "mixed_integer_ops", since = "1.66.0")]
    1908        #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")]
    1909        #[must_use = "this returns the result of the operation, \
    1910                      without modifying the original"]
    1911        #[inline]
    1912        pub const fn saturating_add_unsigned(self, rhs: $UnsignedT) -> Self {
    1913            // Overflow can only happen at the upper bound
    1914            // We cannot use `unwrap_or` here because it is not `const`
    1915            match self.checked_add_unsigned(rhs) {
    1916                Some(x) => x,
    1917                None => Self::MAX,
    1918            }
    1919        }
    1920
    1921        /// Saturating integer subtraction. Computes `self - rhs`, saturating at the
    1922        /// numeric bounds instead of overflowing.
    1923        ///
    1924        /// # Examples
    1925        ///
    1926        /// ```
    1927        #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_sub(127), -27);")]
    1928        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_sub(100), ", stringify!($SelfT), "::MIN);")]
    1929        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_sub(-1), ", stringify!($SelfT), "::MAX);")]
    1930        /// ```
    1931        #[stable(feature = "rust1", since = "1.0.0")]
    1932        #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")]
    1933        #[must_use = "this returns the result of the operation, \
    1934                      without modifying the original"]
    1935        #[inline(always)]
    1936        pub const fn saturating_sub(self, rhs: Self) -> Self {
    1937            intrinsics::saturating_sub(self, rhs)
    1938        }
    1939
    1940        /// Saturating subtraction with an unsigned integer. Computes `self - rhs`,
    1941        /// saturating at the numeric bounds instead of overflowing.
    1942        ///
    1943        /// # Examples
    1944        ///
    1945        /// ```
    1946        #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_sub_unsigned(127), -27);")]
    1947        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_sub_unsigned(100), ", stringify!($SelfT), "::MIN);")]
    1948        /// ```
    1949        #[stable(feature = "mixed_integer_ops", since = "1.66.0")]
    1950        #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")]
    1951        #[must_use = "this returns the result of the operation, \
    1952                      without modifying the original"]
    1953        #[inline]
    1954        pub const fn saturating_sub_unsigned(self, rhs: $UnsignedT) -> Self {
    1955            // Overflow can only happen at the lower bound
    1956            // We cannot use `unwrap_or` here because it is not `const`
    1957            match self.checked_sub_unsigned(rhs) {
    1958                Some(x) => x,
    1959                None => Self::MIN,
    1960            }
    1961        }
    1962
    1963        /// Saturating integer negation. Computes `-self`, returning `MAX` if `self == MIN`
    1964        /// instead of overflowing.
    1965        ///
    1966        /// # Examples
    1967        ///
    1968        /// ```
    1969        #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_neg(), -100);")]
    1970        #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").saturating_neg(), 100);")]
    1971        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_neg(), ", stringify!($SelfT), "::MAX);")]
    1972        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_neg(), ", stringify!($SelfT), "::MIN + 1);")]
    1973        /// ```
    1974
    1975        #[stable(feature = "saturating_neg", since = "1.45.0")]
    1976        #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")]
    1977        #[must_use = "this returns the result of the operation, \
    1978                      without modifying the original"]
    1979        #[inline(always)]
    1980        pub const fn saturating_neg(self) -> Self {
    1981            intrinsics::saturating_sub(0, self)
    1982        }
    1983
    1984        /// Saturating absolute value. Computes `self.abs()`, returning `MAX` if `self ==
    1985        /// MIN` instead of overflowing.
    1986        ///
    1987        /// # Examples
    1988        ///
    1989        /// ```
    1990        #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_abs(), 100);")]
    1991        #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").saturating_abs(), 100);")]
    1992        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_abs(), ", stringify!($SelfT), "::MAX);")]
    1993        #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 1).saturating_abs(), ", stringify!($SelfT), "::MAX);")]
    1994        /// ```
    1995
    1996        #[stable(feature = "saturating_neg", since = "1.45.0")]
    1997        #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")]
    1998        #[must_use = "this returns the result of the operation, \
    1999                      without modifying the original"]
    2000        #[inline]
    2001        pub const fn saturating_abs(self) -> Self {
    2002            if self.is_negative() {
    2003                self.saturating_neg()
    2004            } else {
    2005                self
    2006            }
    2007        }
    2008
    2009        /// Saturating integer multiplication. Computes `self * rhs`, saturating at the
    2010        /// numeric bounds instead of overflowing.
    2011        ///
    2012        /// # Examples
    2013        ///
    2014        /// ```
    2015        #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".saturating_mul(12), 120);")]
    2016        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_mul(10), ", stringify!($SelfT), "::MAX);")]
    2017        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_mul(10), ", stringify!($SelfT), "::MIN);")]
    2018        /// ```
    2019        #[stable(feature = "wrapping", since = "1.7.0")]
    2020        #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")]
    2021        #[must_use = "this returns the result of the operation, \
    2022                      without modifying the original"]
    2023        #[inline]
    2024        pub const fn saturating_mul(self, rhs: Self) -> Self {
    2025            match self.checked_mul(rhs) {
    2026                Some(x) => x,
    2027                None => if (self < 0) == (rhs < 0) {
    2028                    Self::MAX
    2029                } else {
    2030                    Self::MIN
    2031                }
    2032            }
    2033        }
    2034
    2035        /// Saturating integer division. Computes `self / rhs`, saturating at the
    2036        /// numeric bounds instead of overflowing.
    2037        ///
    2038        /// # Panics
    2039        ///
    2040        /// This function will panic if `rhs` is zero.
    2041        ///
    2042        /// # Examples
    2043        ///
    2044        /// ```
    2045        #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".saturating_div(2), 2);")]
    2046        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_div(-1), ", stringify!($SelfT), "::MIN + 1);")]
    2047        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_div(-1), ", stringify!($SelfT), "::MAX);")]
    2048        ///
    2049        /// ```
    2050        #[stable(feature = "saturating_div", since = "1.58.0")]
    2051        #[rustc_const_stable(feature = "saturating_div", since = "1.58.0")]
    2052        #[must_use = "this returns the result of the operation, \
    2053                      without modifying the original"]
    2054        #[inline]
    2055        pub const fn saturating_div(self, rhs: Self) -> Self {
    2056            match self.overflowing_div(rhs) {
    2057                (result, false) => result,
    2058                (_result, true) => Self::MAX, // MIN / -1 is the only possible saturating overflow
    2059            }
    2060        }
    2061
    2062        /// Saturating integer exponentiation. Computes `self.pow(exp)`,
    2063        /// saturating at the numeric bounds instead of overflowing.
    2064        ///
    2065        /// # Examples
    2066        ///
    2067        /// ```
    2068        #[doc = concat!("assert_eq!((-4", stringify!($SelfT), ").saturating_pow(3), -64);")]
    2069        #[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".saturating_pow(0), 1);")]
    2070        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_pow(2), ", stringify!($SelfT), "::MAX);")]
    2071        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_pow(3), ", stringify!($SelfT), "::MIN);")]
    2072        /// ```
    2073        #[stable(feature = "no_panic_pow", since = "1.34.0")]
    2074        #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
    2075        #[must_use = "this returns the result of the operation, \
    2076                      without modifying the original"]
    2077        #[inline]
    2078        pub const fn saturating_pow(self, exp: u32) -> Self {
    2079            match self.checked_pow(exp) {
    2080                Some(x) => x,
    2081                None if self < 0 && exp % 2 == 1 => Self::MIN,
    2082                None => Self::MAX,
    2083            }
    2084        }
    2085
    2086        /// Wrapping (modular) addition. Computes `self + rhs`, wrapping around at the
    2087        /// boundary of the type.
    2088        ///
    2089        /// # Examples
    2090        ///
    2091        /// ```
    2092        #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_add(27), 127);")]
    2093        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.wrapping_add(2), ", stringify!($SelfT), "::MIN + 1);")]
    2094        /// ```
    2095        #[stable(feature = "rust1", since = "1.0.0")]
    2096        #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
    2097        #[must_use = "this returns the result of the operation, \
    2098                      without modifying the original"]
    2099        #[inline(always)]
    2100        pub const fn wrapping_add(self, rhs: Self) -> Self {
    2101            intrinsics::wrapping_add(self, rhs)
    2102        }
    2103
    2104        /// Wrapping (modular) addition with an unsigned integer. Computes
    2105        /// `self + rhs`, wrapping around at the boundary of the type.
    2106        ///
    2107        /// # Examples
    2108        ///
    2109        /// ```
    2110        #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_add_unsigned(27), 127);")]
    2111        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.wrapping_add_unsigned(2), ", stringify!($SelfT), "::MIN + 1);")]
    2112        /// ```
    2113        #[stable(feature = "mixed_integer_ops", since = "1.66.0")]
    2114        #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")]
    2115        #[must_use = "this returns the result of the operation, \
    2116                      without modifying the original"]
    2117        #[inline(always)]
    2118        pub const fn wrapping_add_unsigned(self, rhs: $UnsignedT) -> Self {
    2119            self.wrapping_add(rhs as Self)
    2120        }
    2121
    2122        /// Wrapping (modular) subtraction. Computes `self - rhs`, wrapping around at the
    2123        /// boundary of the type.
    2124        ///
    2125        /// # Examples
    2126        ///
    2127        /// ```
    2128        #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".wrapping_sub(127), -127);")]
    2129        #[doc = concat!("assert_eq!((-2", stringify!($SelfT), ").wrapping_sub(", stringify!($SelfT), "::MAX), ", stringify!($SelfT), "::MAX);")]
    2130        /// ```
    2131        #[stable(feature = "rust1", since = "1.0.0")]
    2132        #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
    2133        #[must_use = "this returns the result of the operation, \
    2134                      without modifying the original"]
    2135        #[inline(always)]
    2136        pub const fn wrapping_sub(self, rhs: Self) -> Self {
    2137            intrinsics::wrapping_sub(self, rhs)
    2138        }
    2139
    2140        /// Wrapping (modular) subtraction with an unsigned integer. Computes
    2141        /// `self - rhs`, wrapping around at the boundary of the type.
    2142        ///
    2143        /// # Examples
    2144        ///
    2145        /// ```
    2146        #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".wrapping_sub_unsigned(127), -127);")]
    2147        #[doc = concat!("assert_eq!((-2", stringify!($SelfT), ").wrapping_sub_unsigned(", stringify!($UnsignedT), "::MAX), -1);")]
    2148        /// ```
    2149        #[stable(feature = "mixed_integer_ops", since = "1.66.0")]
    2150        #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")]
    2151        #[must_use = "this returns the result of the operation, \
    2152                      without modifying the original"]
    2153        #[inline(always)]
    2154        pub const fn wrapping_sub_unsigned(self, rhs: $UnsignedT) -> Self {
    2155            self.wrapping_sub(rhs as Self)
    2156        }
    2157
    2158        /// Wrapping (modular) multiplication. Computes `self * rhs`, wrapping around at
    2159        /// the boundary of the type.
    2160        ///
    2161        /// # Examples
    2162        ///
    2163        /// ```
    2164        #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".wrapping_mul(12), 120);")]
    2165        /// assert_eq!(11i8.wrapping_mul(12), -124);
    2166        /// ```
    2167        #[stable(feature = "rust1", since = "1.0.0")]
    2168        #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
    2169        #[must_use = "this returns the result of the operation, \
    2170                      without modifying the original"]
    2171        #[inline(always)]
    2172        pub const fn wrapping_mul(self, rhs: Self) -> Self {
    2173            intrinsics::wrapping_mul(self, rhs)
    2174        }
    2175
    2176        /// Wrapping (modular) division. Computes `self / rhs`, wrapping around at the
    2177        /// boundary of the type.
    2178        ///
    2179        /// The only case where such wrapping can occur is when one divides `MIN / -1` on a signed type (where
    2180        /// `MIN` is the negative minimal value for the type); this is equivalent to `-MIN`, a positive value
    2181        /// that is too large to represent in the type. In such a case, this function returns `MIN` itself.
    2182        ///
    2183        /// # Panics
    2184        ///
    2185        /// This function will panic if `rhs` is zero.
    2186        ///
    2187        /// # Examples
    2188        ///
    2189        /// ```
    2190        #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_div(10), 10);")]
    2191        /// assert_eq!((-128i8).wrapping_div(-1), -128);
    2192        /// ```
    2193        #[stable(feature = "num_wrapping", since = "1.2.0")]
    2194        #[rustc_const_stable(feature = "const_wrapping_int_methods", since = "1.52.0")]
    2195        #[must_use = "this returns the result of the operation, \
    2196                      without modifying the original"]
    2197        #[inline]
    2198        pub const fn wrapping_div(self, rhs: Self) -> Self {
    2199            self.overflowing_div(rhs).0
    2200        }
    2201
    2202        /// Wrapping Euclidean division. Computes `self.div_euclid(rhs)`,
    2203        /// wrapping around at the boundary of the type.
    2204        ///
    2205        /// Wrapping will only occur in `MIN / -1` on a signed type (where `MIN` is the negative minimal value
    2206        /// for the type). This is equivalent to `-MIN`, a positive value that is too large to represent in the
    2207        /// type. In this case, this method returns `MIN` itself.
    2208        ///
    2209        /// # Panics
    2210        ///
    2211        /// This function will panic if `rhs` is zero.
    2212        ///
    2213        /// # Examples
    2214        ///
    2215        /// ```
    2216        #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_div_euclid(10), 10);")]
    2217        /// assert_eq!((-128i8).wrapping_div_euclid(-1), -128);
    2218        /// ```
    2219        #[stable(feature = "euclidean_division", since = "1.38.0")]
    2220        #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
    2221        #[must_use = "this returns the result of the operation, \
    2222                      without modifying the original"]
    2223        #[inline]
    2224        pub const fn wrapping_div_euclid(self, rhs: Self) -> Self {
    2225            self.overflowing_div_euclid(rhs).0
    2226        }
    2227
    2228        /// Wrapping (modular) remainder. Computes `self % rhs`, wrapping around at the
    2229        /// boundary of the type.
    2230        ///
    2231        /// Such wrap-around never actually occurs mathematically; implementation artifacts make `x % y`
    2232        /// invalid for `MIN / -1` on a signed type (where `MIN` is the negative minimal value). In such a case,
    2233        /// this function returns `0`.
    2234        ///
    2235        /// # Panics
    2236        ///
    2237        /// This function will panic if `rhs` is zero.
    2238        ///
    2239        /// # Examples
    2240        ///
    2241        /// ```
    2242        #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_rem(10), 0);")]
    2243        /// assert_eq!((-128i8).wrapping_rem(-1), 0);
    2244        /// ```
    2245        #[stable(feature = "num_wrapping", since = "1.2.0")]
    2246        #[rustc_const_stable(feature = "const_wrapping_int_methods", since = "1.52.0")]
    2247        #[must_use = "this returns the result of the operation, \
    2248                      without modifying the original"]
    2249        #[inline]
    2250        pub const fn wrapping_rem(self, rhs: Self) -> Self {
    2251            self.overflowing_rem(rhs).0
    2252        }
    2253
    2254        /// Wrapping Euclidean remainder. Computes `self.rem_euclid(rhs)`, wrapping around
    2255        /// at the boundary of the type.
    2256        ///
    2257        /// Wrapping will only occur in `MIN % -1` on a signed type (where `MIN` is the negative minimal value
    2258        /// for the type). In this case, this method returns 0.
    2259        ///
    2260        /// # Panics
    2261        ///
    2262        /// This function will panic if `rhs` is zero.
    2263        ///
    2264        /// # Examples
    2265        ///
    2266        /// ```
    2267        #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_rem_euclid(10), 0);")]
    2268        /// assert_eq!((-128i8).wrapping_rem_euclid(-1), 0);
    2269        /// ```
    2270        #[stable(feature = "euclidean_division", since = "1.38.0")]
    2271        #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
    2272        #[must_use = "this returns the result of the operation, \
    2273                      without modifying the original"]
    2274        #[inline]
    2275        pub const fn wrapping_rem_euclid(self, rhs: Self) -> Self {
    2276            self.overflowing_rem_euclid(rhs).0
    2277        }
    2278
    2279        /// Wrapping (modular) negation. Computes `-self`, wrapping around at the boundary
    2280        /// of the type.
    2281        ///
    2282        /// The only case where such wrapping can occur is when one negates `MIN` on a signed type (where `MIN`
    2283        /// is the negative minimal value for the type); this is a positive value that is too large to represent
    2284        /// in the type. In such a case, this function returns `MIN` itself.
    2285        ///
    2286        /// # Examples
    2287        ///
    2288        /// ```
    2289        #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_neg(), -100);")]
    2290        #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").wrapping_neg(), 100);")]
    2291        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.wrapping_neg(), ", stringify!($SelfT), "::MIN);")]
    2292        /// ```
    2293        #[stable(feature = "num_wrapping", since = "1.2.0")]
    2294        #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
    2295        #[must_use = "this returns the result of the operation, \
    2296                      without modifying the original"]
    2297        #[inline(always)]
    2298        pub const fn wrapping_neg(self) -> Self {
    2299            (0 as $SelfT).wrapping_sub(self)
    2300        }
    2301
    2302        /// Panic-free bitwise shift-left; yields `self << mask(rhs)`, where `mask` removes
    2303        /// any high-order bits of `rhs` that would cause the shift to exceed the bitwidth of the type.
    2304        ///
    2305        /// Beware that, unlike most other `wrapping_*` methods on integers, this
    2306        /// does *not* give the same result as doing the shift in infinite precision
    2307        /// then truncating as needed.  The behaviour matches what shift instructions
    2308        /// do on many processors, and is what the `<<` operator does when overflow
    2309        /// checks are disabled, but numerically it's weird.  Consider, instead,
    2310        /// using [`Self::unbounded_shl`] which has nicer behaviour.
    2311        ///
    2312        /// Note that this is *not* the same as a rotate-left; the RHS of a wrapping shift-left is restricted to
    2313        /// the range of the type, rather than the bits shifted out of the LHS being returned to the other end.
    2314        /// The primitive integer types all implement a [`rotate_left`](Self::rotate_left) function,
    2315        /// which may be what you want instead.
    2316        ///
    2317        /// # Examples
    2318        ///
    2319        /// ```
    2320        #[doc = concat!("assert_eq!((-1_", stringify!($SelfT), ").wrapping_shl(7), -128);")]
    2321        #[doc = concat!("assert_eq!(42_", stringify!($SelfT), ".wrapping_shl(", stringify!($BITS), "), 42);")]
    2322        #[doc = concat!("assert_eq!(42_", stringify!($SelfT), ".wrapping_shl(1).wrapping_shl(", stringify!($BITS_MINUS_ONE), "), 0);")]
    2323        #[doc = concat!("assert_eq!((-1_", stringify!($SelfT), ").wrapping_shl(128), -1);")]
    2324        #[doc = concat!("assert_eq!(5_", stringify!($SelfT), ".wrapping_shl(1025), 10);")]
    2325        /// ```
    2326        #[stable(feature = "num_wrapping", since = "1.2.0")]
    2327        #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
    2328        #[must_use = "this returns the result of the operation, \
    2329                      without modifying the original"]
    2330        #[inline(always)]
    2331        pub const fn wrapping_shl(self, rhs: u32) -> Self {
    2332            // SAFETY: the masking by the bitsize of the type ensures that we do not shift
    2333            // out of bounds
    2334            unsafe {
    2335                self.unchecked_shl(rhs & (Self::BITS - 1))
    2336            }
    2337        }
    2338
    2339        /// Panic-free bitwise shift-right; yields `self >> mask(rhs)`, where `mask`
    2340        /// removes any high-order bits of `rhs` that would cause the shift to exceed the bitwidth of the type.
    2341        ///
    2342        /// Beware that, unlike most other `wrapping_*` methods on integers, this
    2343        /// does *not* give the same result as doing the shift in infinite precision
    2344        /// then truncating as needed.  The behaviour matches what shift instructions
    2345        /// do on many processors, and is what the `>>` operator does when overflow
    2346        /// checks are disabled, but numerically it's weird.  Consider, instead,
    2347        /// using [`Self::unbounded_shr`] which has nicer behaviour.
    2348        ///
    2349        /// Note that this is *not* the same as a rotate-right; the RHS of a wrapping shift-right is restricted
    2350        /// to the range of the type, rather than the bits shifted out of the LHS being returned to the other
    2351        /// end. The primitive integer types all implement a [`rotate_right`](Self::rotate_right) function,
    2352        /// which may be what you want instead.
    2353        ///
    2354        /// # Examples
    2355        ///
    2356        /// ```
    2357        #[doc = concat!("assert_eq!((-128_", stringify!($SelfT), ").wrapping_shr(7), -1);")]
    2358        #[doc = concat!("assert_eq!(42_", stringify!($SelfT), ".wrapping_shr(", stringify!($BITS), "), 42);")]
    2359        #[doc = concat!("assert_eq!(42_", stringify!($SelfT), ".wrapping_shr(1).wrapping_shr(", stringify!($BITS_MINUS_ONE), "), 0);")]
    2360        /// assert_eq!((-128_i16).wrapping_shr(64), -128);
    2361        #[doc = concat!("assert_eq!(10_", stringify!($SelfT), ".wrapping_shr(1025), 5);")]
    2362        /// ```
    2363        #[stable(feature = "num_wrapping", since = "1.2.0")]
    2364        #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
    2365        #[must_use = "this returns the result of the operation, \
    2366                      without modifying the original"]
    2367        #[inline(always)]
    2368        pub const fn wrapping_shr(self, rhs: u32) -> Self {
    2369            // SAFETY: the masking by the bitsize of the type ensures that we do not shift
    2370            // out of bounds
    2371            unsafe {
    2372                self.unchecked_shr(rhs & (Self::BITS - 1))
    2373            }
    2374        }
    2375
    2376        /// Wrapping (modular) absolute value. Computes `self.abs()`, wrapping around at
    2377        /// the boundary of the type.
    2378        ///
    2379        /// The only case where such wrapping can occur is when one takes the absolute value of the negative
    2380        /// minimal value for the type; this is a positive value that is too large to represent in the type. In
    2381        /// such a case, this function returns `MIN` itself.
    2382        ///
    2383        /// # Examples
    2384        ///
    2385        /// ```
    2386        #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_abs(), 100);")]
    2387        #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").wrapping_abs(), 100);")]
    2388        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.wrapping_abs(), ", stringify!($SelfT), "::MIN);")]
    2389        /// assert_eq!((-128i8).wrapping_abs() as u8, 128);
    2390        /// ```
    2391        #[stable(feature = "no_panic_abs", since = "1.13.0")]
    2392        #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
    2393        #[must_use = "this returns the result of the operation, \
    2394                      without modifying the original"]
    2395        #[allow(unused_attributes)]
    2396        #[inline]
    2397        pub const fn wrapping_abs(self) -> Self {
    2398             if self.is_negative() {
    2399                 self.wrapping_neg()
    2400             } else {
    2401                 self
    2402             }
    2403        }
    2404
    2405        /// Computes the absolute value of `self` without any wrapping
    2406        /// or panicking.
    2407        ///
    2408        ///
    2409        /// # Examples
    2410        ///
    2411        /// ```
    2412        #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".unsigned_abs(), 100", stringify!($UnsignedT), ");")]
    2413        #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").unsigned_abs(), 100", stringify!($UnsignedT), ");")]
    2414        /// assert_eq!((-128i8).unsigned_abs(), 128u8);
    2415        /// ```
    2416        #[stable(feature = "unsigned_abs", since = "1.51.0")]
    2417        #[rustc_const_stable(feature = "unsigned_abs", since = "1.51.0")]
    2418        #[must_use = "this returns the result of the operation, \
    2419                      without modifying the original"]
    2420        #[inline]
    2421        pub const fn unsigned_abs(self) -> $UnsignedT {
    2422             self.wrapping_abs() as $UnsignedT
    2423        }
    2424
    2425        /// Wrapping (modular) exponentiation. Computes `self.pow(exp)`,
    2426        /// wrapping around at the boundary of the type.
    2427        ///
    2428        /// # Examples
    2429        ///
    2430        /// ```
    2431        #[doc = concat!("assert_eq!(3", stringify!($SelfT), ".wrapping_pow(4), 81);")]
    2432        /// assert_eq!(3i8.wrapping_pow(5), -13);
    2433        /// assert_eq!(3i8.wrapping_pow(6), -39);
    2434        #[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".wrapping_pow(0), 1);")]
    2435        /// ```
    2436        #[stable(feature = "no_panic_pow", since = "1.34.0")]
    2437        #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
    2438        #[must_use = "this returns the result of the operation, \
    2439                      without modifying the original"]
    2440        #[inline]
    2441        pub const fn wrapping_pow(self, mut exp: u32) -> Self {
    2442            if exp == 0 {
    2443                return 1;
    2444            }
    2445            let mut base = self;
    2446            let mut acc: Self = 1;
    2447
    2448            if intrinsics::is_val_statically_known(exp) {
    2449                while exp > 1 {
    2450                    if (exp & 1) == 1 {
    2451                        acc = acc.wrapping_mul(base);
    2452                    }
    2453                    exp /= 2;
    2454                    base = base.wrapping_mul(base);
    2455                }
    2456
    2457                // since exp!=0, finally the exp must be 1.
    2458                // Deal with the final bit of the exponent separately, since
    2459                // squaring the base afterwards is not necessary.
    2460                acc.wrapping_mul(base)
    2461            } else {
    2462                // This is faster than the above when the exponent is not known
    2463                // at compile time. We can't use the same code for the constant
    2464                // exponent case because LLVM is currently unable to unroll
    2465                // this loop.
    2466                loop {
    2467                    if (exp & 1) == 1 {
    2468                        acc = acc.wrapping_mul(base);
    2469                        // since exp!=0, finally the exp must be 1.
    2470                        if exp == 1 {
    2471                            return acc;
    2472                        }
    2473                    }
    2474                    exp /= 2;
    2475                    base = base.wrapping_mul(base);
    2476                }
    2477            }
    2478        }
    2479
    2480        /// Calculates `self` + `rhs`.
    2481        ///
    2482        /// Returns a tuple of the addition along with a boolean indicating
    2483        /// whether an arithmetic overflow would occur. If an overflow would have
    2484        /// occurred then the wrapped value is returned.
    2485        ///
    2486        /// # Examples
    2487        ///
    2488        /// ```
    2489        #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_add(2), (7, false));")]
    2490        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.overflowing_add(1), (", stringify!($SelfT), "::MIN, true));")]
    2491        /// ```
    2492        #[stable(feature = "wrapping", since = "1.7.0")]
    2493        #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
    2494        #[must_use = "this returns the result of the operation, \
    2495                      without modifying the original"]
    2496        #[inline(always)]
    2497        pub const fn overflowing_add(self, rhs: Self) -> (Self, bool) {
    2498            let (a, b) = intrinsics::add_with_overflow(self as $ActualT, rhs as $ActualT);
    2499            (a as Self, b)
    2500        }
    2501
    2502        /// Calculates `self` + `rhs` + `carry` and checks for overflow.
    2503        ///
    2504        /// Performs "ternary addition" of two integer operands and a carry-in
    2505        /// bit, and returns a tuple of the sum along with a boolean indicating
    2506        /// whether an arithmetic overflow would occur. On overflow, the wrapped
    2507        /// value is returned.
    2508        ///
    2509        /// This allows chaining together multiple additions to create a wider
    2510        /// addition, and can be useful for bignum addition. This method should
    2511        /// only be used for the most significant word; for the less significant
    2512        /// words the unsigned method
    2513        #[doc = concat!("[`", stringify!($UnsignedT), "::carrying_add`]")]
    2514        /// should be used.
    2515        ///
    2516        /// The output boolean returned by this method is *not* a carry flag,
    2517        /// and should *not* be added to a more significant word.
    2518        ///
    2519        /// If the input carry is false, this method is equivalent to
    2520        /// [`overflowing_add`](Self::overflowing_add).
    2521        ///
    2522        /// # Examples
    2523        ///
    2524        /// ```
    2525        /// #![feature(bigint_helper_methods)]
    2526        /// // Only the most significant word is signed.
    2527        /// //
    2528        #[doc = concat!("//   10  MAX    (a = 10 × 2^", stringify!($BITS), " + 2^", stringify!($BITS), " - 1)")]
    2529        #[doc = concat!("// + -5    9    (b = -5 × 2^", stringify!($BITS), " + 9)")]
    2530        /// // ---------
    2531        #[doc = concat!("//    6    8    (sum = 6 × 2^", stringify!($BITS), " + 8)")]
    2532        ///
    2533        #[doc = concat!("let (a1, a0): (", stringify!($SelfT), ", ", stringify!($UnsignedT), ") = (10, ", stringify!($UnsignedT), "::MAX);")]
    2534        #[doc = concat!("let (b1, b0): (", stringify!($SelfT), ", ", stringify!($UnsignedT), ") = (-5, 9);")]
    2535        /// let carry0 = false;
    2536        ///
    2537        #[doc = concat!("// ", stringify!($UnsignedT), "::carrying_add for the less significant words")]
    2538        /// let (sum0, carry1) = a0.carrying_add(b0, carry0);
    2539        /// assert_eq!(carry1, true);
    2540        ///
    2541        #[doc = concat!("// ", stringify!($SelfT), "::carrying_add for the most significant word")]
    2542        /// let (sum1, overflow) = a1.carrying_add(b1, carry1);
    2543        /// assert_eq!(overflow, false);
    2544        ///
    2545        /// assert_eq!((sum1, sum0), (6, 8));
    2546        /// ```
    2547        #[unstable(feature = "bigint_helper_methods", issue = "85532")]
    2548        #[must_use = "this returns the result of the operation, \
    2549                      without modifying the original"]
    2550        #[inline]
    2551        pub const fn carrying_add(self, rhs: Self, carry: bool) -> (Self, bool) {
    2552            // note: longer-term this should be done via an intrinsic.
    2553            // note: no intermediate overflow is required (https://github.com/rust-lang/rust/issues/85532#issuecomment-1032214946).
    2554            let (a, b) = self.overflowing_add(rhs);
    2555            let (c, d) = a.overflowing_add(carry as $SelfT);
    2556            (c, b != d)
    2557        }
    2558
    2559        /// Calculates `self` + `rhs` with an unsigned `rhs`.
    2560        ///
    2561        /// Returns a tuple of the addition along with a boolean indicating
    2562        /// whether an arithmetic overflow would occur. If an overflow would
    2563        /// have occurred then the wrapped value is returned.
    2564        ///
    2565        /// # Examples
    2566        ///
    2567        /// ```
    2568        #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".overflowing_add_unsigned(2), (3, false));")]
    2569        #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN).overflowing_add_unsigned(", stringify!($UnsignedT), "::MAX), (", stringify!($SelfT), "::MAX, false));")]
    2570        #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).overflowing_add_unsigned(3), (", stringify!($SelfT), "::MIN, true));")]
    2571        /// ```
    2572        #[stable(feature = "mixed_integer_ops", since = "1.66.0")]
    2573        #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")]
    2574        #[must_use = "this returns the result of the operation, \
    2575                      without modifying the original"]
    2576        #[inline]
    2577        pub const fn overflowing_add_unsigned(self, rhs: $UnsignedT) -> (Self, bool) {
    2578            let rhs = rhs as Self;
    2579            let (res, overflowed) = self.overflowing_add(rhs);
    2580            (res, overflowed ^ (rhs < 0))
    2581        }
    2582
    2583        /// Calculates `self` - `rhs`.
    2584        ///
    2585        /// Returns a tuple of the subtraction along with a boolean indicating whether an arithmetic overflow
    2586        /// would occur. If an overflow would have occurred then the wrapped value is returned.
    2587        ///
    2588        /// # Examples
    2589        ///
    2590        /// ```
    2591        #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_sub(2), (3, false));")]
    2592        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_sub(1), (", stringify!($SelfT), "::MAX, true));")]
    2593        /// ```
    2594        #[stable(feature = "wrapping", since = "1.7.0")]
    2595        #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
    2596        #[must_use = "this returns the result of the operation, \
    2597                      without modifying the original"]
    2598        #[inline(always)]
    2599        pub const fn overflowing_sub(self, rhs: Self) -> (Self, bool) {
    2600            let (a, b) = intrinsics::sub_with_overflow(self as $ActualT, rhs as $ActualT);
    2601            (a as Self, b)
    2602        }
    2603
    2604        /// Calculates `self` &minus; `rhs` &minus; `borrow` and checks for
    2605        /// overflow.
    2606        ///
    2607        /// Performs "ternary subtraction" by subtracting both an integer
    2608        /// operand and a borrow-in bit from `self`, and returns a tuple of the
    2609        /// difference along with a boolean indicating whether an arithmetic
    2610        /// overflow would occur. On overflow, the wrapped value is returned.
    2611        ///
    2612        /// This allows chaining together multiple subtractions to create a
    2613        /// wider subtraction, and can be useful for bignum subtraction. This
    2614        /// method should only be used for the most significant word; for the
    2615        /// less significant words the unsigned method
    2616        #[doc = concat!("[`", stringify!($UnsignedT), "::borrowing_sub`]")]
    2617        /// should be used.
    2618        ///
    2619        /// The output boolean returned by this method is *not* a borrow flag,
    2620        /// and should *not* be subtracted from a more significant word.
    2621        ///
    2622        /// If the input borrow is false, this method is equivalent to
    2623        /// [`overflowing_sub`](Self::overflowing_sub).
    2624        ///
    2625        /// # Examples
    2626        ///
    2627        /// ```
    2628        /// #![feature(bigint_helper_methods)]
    2629        /// // Only the most significant word is signed.
    2630        /// //
    2631        #[doc = concat!("//    6    8    (a = 6 × 2^", stringify!($BITS), " + 8)")]
    2632        #[doc = concat!("// - -5    9    (b = -5 × 2^", stringify!($BITS), " + 9)")]
    2633        /// // ---------
    2634        #[doc = concat!("//   10  MAX    (diff = 10 × 2^", stringify!($BITS), " + 2^", stringify!($BITS), " - 1)")]
    2635        ///
    2636        #[doc = concat!("let (a1, a0): (", stringify!($SelfT), ", ", stringify!($UnsignedT), ") = (6, 8);")]
    2637        #[doc = concat!("let (b1, b0): (", stringify!($SelfT), ", ", stringify!($UnsignedT), ") = (-5, 9);")]
    2638        /// let borrow0 = false;
    2639        ///
    2640        #[doc = concat!("// ", stringify!($UnsignedT), "::borrowing_sub for the less significant words")]
    2641        /// let (diff0, borrow1) = a0.borrowing_sub(b0, borrow0);
    2642        /// assert_eq!(borrow1, true);
    2643        ///
    2644        #[doc = concat!("// ", stringify!($SelfT), "::borrowing_sub for the most significant word")]
    2645        /// let (diff1, overflow) = a1.borrowing_sub(b1, borrow1);
    2646        /// assert_eq!(overflow, false);
    2647        ///
    2648        #[doc = concat!("assert_eq!((diff1, diff0), (10, ", stringify!($UnsignedT), "::MAX));")]
    2649        /// ```
    2650        #[unstable(feature = "bigint_helper_methods", issue = "85532")]
    2651        #[must_use = "this returns the result of the operation, \
    2652                      without modifying the original"]
    2653        #[inline]
    2654        pub const fn borrowing_sub(self, rhs: Self, borrow: bool) -> (Self, bool) {
    2655            // note: longer-term this should be done via an intrinsic.
    2656            // note: no intermediate overflow is required (https://github.com/rust-lang/rust/issues/85532#issuecomment-1032214946).
    2657            let (a, b) = self.overflowing_sub(rhs);
    2658            let (c, d) = a.overflowing_sub(borrow as $SelfT);
    2659            (c, b != d)
    2660        }
    2661
    2662        /// Calculates `self` - `rhs` with an unsigned `rhs`.
    2663        ///
    2664        /// Returns a tuple of the subtraction along with a boolean indicating
    2665        /// whether an arithmetic overflow would occur. If an overflow would
    2666        /// have occurred then the wrapped value is returned.
    2667        ///
    2668        /// # Examples
    2669        ///
    2670        /// ```
    2671        #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".overflowing_sub_unsigned(2), (-1, false));")]
    2672        #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX).overflowing_sub_unsigned(", stringify!($UnsignedT), "::MAX), (", stringify!($SelfT), "::MIN, false));")]
    2673        #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 2).overflowing_sub_unsigned(3), (", stringify!($SelfT), "::MAX, true));")]
    2674        /// ```
    2675        #[stable(feature = "mixed_integer_ops", since = "1.66.0")]
    2676        #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")]
    2677        #[must_use = "this returns the result of the operation, \
    2678                      without modifying the original"]
    2679        #[inline]
    2680        pub const fn overflowing_sub_unsigned(self, rhs: $UnsignedT) -> (Self, bool) {
    2681            let rhs = rhs as Self;
    2682            let (res, overflowed) = self.overflowing_sub(rhs);
    2683            (res, overflowed ^ (rhs < 0))
    2684        }
    2685
    2686        /// Calculates the multiplication of `self` and `rhs`.
    2687        ///
    2688        /// Returns a tuple of the multiplication along with a boolean indicating whether an arithmetic overflow
    2689        /// would occur. If an overflow would have occurred then the wrapped value is returned.
    2690        ///
    2691        /// # Examples
    2692        ///
    2693        /// ```
    2694        #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_mul(2), (10, false));")]
    2695        /// assert_eq!(1_000_000_000i32.overflowing_mul(10), (1410065408, true));
    2696        /// ```
    2697        #[stable(feature = "wrapping", since = "1.7.0")]
    2698        #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
    2699        #[must_use = "this returns the result of the operation, \
    2700                      without modifying the original"]
    2701        #[inline(always)]
    2702        pub const fn overflowing_mul(self, rhs: Self) -> (Self, bool) {
    2703            let (a, b) = intrinsics::mul_with_overflow(self as $ActualT, rhs as $ActualT);
    2704            (a as Self, b)
    2705        }
    2706
    2707        /// Calculates the complete product `self * rhs` without the possibility to overflow.
    2708        ///
    2709        /// This returns the low-order (wrapping) bits and the high-order (overflow) bits
    2710        /// of the result as two separate values, in that order.
    2711        ///
    2712        /// If you also need to add a carry to the wide result, then you want
    2713        /// [`Self::carrying_mul`] instead.
    2714        ///
    2715        /// # Examples
    2716        ///
    2717        /// Please note that this example is shared among integer types, which is why `i32` is used.
    2718        ///
    2719        /// ```
    2720        /// #![feature(bigint_helper_methods)]
    2721        /// assert_eq!(5i32.widening_mul(-2), (4294967286, -1));
    2722        /// assert_eq!(1_000_000_000i32.widening_mul(-10), (2884901888, -3));
    2723        /// ```
    2724        #[unstable(feature = "bigint_helper_methods", issue = "85532")]
    2725        #[rustc_const_unstable(feature = "bigint_helper_methods", issue = "85532")]
    2726        #[must_use = "this returns the result of the operation, \
    2727                      without modifying the original"]
    2728        #[inline]
    2729        pub const fn widening_mul(self, rhs: Self) -> ($UnsignedT, Self) {
    2730            Self::carrying_mul_add(self, rhs, 0, 0)
    2731        }
    2732
    2733        /// Calculates the "full multiplication" `self * rhs + carry`
    2734        /// without the possibility to overflow.
    2735        ///
    2736        /// This returns the low-order (wrapping) bits and the high-order (overflow) bits
    2737        /// of the result as two separate values, in that order.
    2738        ///
    2739        /// Performs "long multiplication" which takes in an extra amount to add, and may return an
    2740        /// additional amount of overflow. This allows for chaining together multiple
    2741        /// multiplications to create "big integers" which represent larger values.
    2742        ///
    2743        /// If you don't need the `carry`, then you can use [`Self::widening_mul`] instead.
    2744        ///
    2745        /// # Examples
    2746        ///
    2747        /// Please note that this example is shared among integer types, which is why `i32` is used.
    2748        ///
    2749        /// ```
    2750        /// #![feature(bigint_helper_methods)]
    2751        /// assert_eq!(5i32.carrying_mul(-2, 0), (4294967286, -1));
    2752        /// assert_eq!(5i32.carrying_mul(-2, 10), (0, 0));
    2753        /// assert_eq!(1_000_000_000i32.carrying_mul(-10, 0), (2884901888, -3));
    2754        /// assert_eq!(1_000_000_000i32.carrying_mul(-10, 10), (2884901898, -3));
    2755        #[doc = concat!("assert_eq!(",
    2756            stringify!($SelfT), "::MAX.carrying_mul(", stringify!($SelfT), "::MAX, ", stringify!($SelfT), "::MAX), ",
    2757            "(", stringify!($SelfT), "::MAX.unsigned_abs() + 1, ", stringify!($SelfT), "::MAX / 2));"
    2758        )]
    2759        /// ```
    2760        #[unstable(feature = "bigint_helper_methods", issue = "85532")]
    2761        #[rustc_const_unstable(feature = "bigint_helper_methods", issue = "85532")]
    2762        #[must_use = "this returns the result of the operation, \
    2763                      without modifying the original"]
    2764        #[inline]
    2765        pub const fn carrying_mul(self, rhs: Self, carry: Self) -> ($UnsignedT, Self) {
    2766            Self::carrying_mul_add(self, rhs, carry, 0)
    2767        }
    2768
    2769        /// Calculates the "full multiplication" `self * rhs + carry + add`
    2770        /// without the possibility to overflow.
    2771        ///
    2772        /// This returns the low-order (wrapping) bits and the high-order (overflow) bits
    2773        /// of the result as two separate values, in that order.
    2774        ///
    2775        /// Performs "long multiplication" which takes in an extra amount to add, and may return an
    2776        /// additional amount of overflow. This allows for chaining together multiple
    2777        /// multiplications to create "big integers" which represent larger values.
    2778        ///
    2779        /// If you don't need either `carry`, then you can use [`Self::widening_mul`] instead,
    2780        /// and if you only need one `carry`, then you can use [`Self::carrying_mul`] instead.
    2781        ///
    2782        /// # Examples
    2783        ///
    2784        /// Please note that this example is shared among integer types, which is why `i32` is used.
    2785        ///
    2786        /// ```
    2787        /// #![feature(bigint_helper_methods)]
    2788        /// assert_eq!(5i32.carrying_mul_add(-2, 0, 0), (4294967286, -1));
    2789        /// assert_eq!(5i32.carrying_mul_add(-2, 10, 10), (10, 0));
    2790        /// assert_eq!(1_000_000_000i32.carrying_mul_add(-10, 0, 0), (2884901888, -3));
    2791        /// assert_eq!(1_000_000_000i32.carrying_mul_add(-10, 10, 10), (2884901908, -3));
    2792        #[doc = concat!("assert_eq!(",
    2793            stringify!($SelfT), "::MAX.carrying_mul_add(", stringify!($SelfT), "::MAX, ", stringify!($SelfT), "::MAX, ", stringify!($SelfT), "::MAX), ",
    2794            "(", stringify!($UnsignedT), "::MAX, ", stringify!($SelfT), "::MAX / 2));"
    2795        )]
    2796        /// ```
    2797        #[unstable(feature = "bigint_helper_methods", issue = "85532")]
    2798        #[rustc_const_unstable(feature = "bigint_helper_methods", issue = "85532")]
    2799        #[must_use = "this returns the result of the operation, \
    2800                      without modifying the original"]
    2801        #[inline]
    2802        pub const fn carrying_mul_add(self, rhs: Self, carry: Self, add: Self) -> ($UnsignedT, Self) {
    2803            intrinsics::carrying_mul_add(self, rhs, carry, add)
    2804        }
    2805
    2806        /// Calculates the divisor when `self` is divided by `rhs`.
    2807        ///
    2808        /// Returns a tuple of the divisor along with a boolean indicating whether an arithmetic overflow would
    2809        /// occur. If an overflow would occur then self is returned.
    2810        ///
    2811        /// # Panics
    2812        ///
    2813        /// This function will panic if `rhs` is zero.
    2814        ///
    2815        /// # Examples
    2816        ///
    2817        /// ```
    2818        #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_div(2), (2, false));")]
    2819        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_div(-1), (", stringify!($SelfT), "::MIN, true));")]
    2820        /// ```
    2821        #[inline]
    2822        #[stable(feature = "wrapping", since = "1.7.0")]
    2823        #[rustc_const_stable(feature = "const_overflowing_int_methods", since = "1.52.0")]
    2824        #[must_use = "this returns the result of the operation, \
    2825                      without modifying the original"]
    2826        pub const fn overflowing_div(self, rhs: Self) -> (Self, bool) {
    2827            // Using `&` helps LLVM see that it is the same check made in division.
    2828            if intrinsics::unlikely((self == Self::MIN) & (rhs == -1)) {
    2829                (self, true)
    2830            } else {
    2831                (self / rhs, false)
    2832            }
    2833        }
    2834
    2835        /// Calculates the quotient of Euclidean division `self.div_euclid(rhs)`.
    2836        ///
    2837        /// Returns a tuple of the divisor along with a boolean indicating whether an arithmetic overflow would
    2838        /// occur. If an overflow would occur then `self` is returned.
    2839        ///
    2840        /// # Panics
    2841        ///
    2842        /// This function will panic if `rhs` is zero.
    2843        ///
    2844        /// # Examples
    2845        ///
    2846        /// ```
    2847        #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_div_euclid(2), (2, false));")]
    2848        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_div_euclid(-1), (", stringify!($SelfT), "::MIN, true));")]
    2849        /// ```
    2850        #[inline]
    2851        #[stable(feature = "euclidean_division", since = "1.38.0")]
    2852        #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
    2853        #[must_use = "this returns the result of the operation, \
    2854                      without modifying the original"]
    2855        pub const fn overflowing_div_euclid(self, rhs: Self) -> (Self, bool) {
    2856            // Using `&` helps LLVM see that it is the same check made in division.
    2857            if intrinsics::unlikely((self == Self::MIN) & (rhs == -1)) {
    2858                (self, true)
    2859            } else {
    2860                (self.div_euclid(rhs), false)
    2861            }
    2862        }
    2863
    2864        /// Calculates the remainder when `self` is divided by `rhs`.
    2865        ///
    2866        /// Returns a tuple of the remainder after dividing along with a boolean indicating whether an
    2867        /// arithmetic overflow would occur. If an overflow would occur then 0 is returned.
    2868        ///
    2869        /// # Panics
    2870        ///
    2871        /// This function will panic if `rhs` is zero.
    2872        ///
    2873        /// # Examples
    2874        ///
    2875        /// ```
    2876        #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_rem(2), (1, false));")]
    2877        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_rem(-1), (0, true));")]
    2878        /// ```
    2879        #[inline]
    2880        #[stable(feature = "wrapping", since = "1.7.0")]
    2881        #[rustc_const_stable(feature = "const_overflowing_int_methods", since = "1.52.0")]
    2882        #[must_use = "this returns the result of the operation, \
    2883                      without modifying the original"]
    2884        pub const fn overflowing_rem(self, rhs: Self) -> (Self, bool) {
    2885            if intrinsics::unlikely(rhs == -1) {
    2886                (0, self == Self::MIN)
    2887            } else {
    2888                (self % rhs, false)
    2889            }
    2890        }
    2891
    2892
    2893        /// Overflowing Euclidean remainder. Calculates `self.rem_euclid(rhs)`.
    2894        ///
    2895        /// Returns a tuple of the remainder after dividing along with a boolean indicating whether an
    2896        /// arithmetic overflow would occur. If an overflow would occur then 0 is returned.
    2897        ///
    2898        /// # Panics
    2899        ///
    2900        /// This function will panic if `rhs` is zero.
    2901        ///
    2902        /// # Examples
    2903        ///
    2904        /// ```
    2905        #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_rem_euclid(2), (1, false));")]
    2906        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_rem_euclid(-1), (0, true));")]
    2907        /// ```
    2908        #[stable(feature = "euclidean_division", since = "1.38.0")]
    2909        #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
    2910        #[must_use = "this returns the result of the operation, \
    2911                      without modifying the original"]
    2912        #[inline]
    2913        #[track_caller]
    2914        pub const fn overflowing_rem_euclid(self, rhs: Self) -> (Self, bool) {
    2915            if intrinsics::unlikely(rhs == -1) {
    2916                (0, self == Self::MIN)
    2917            } else {
    2918                (self.rem_euclid(rhs), false)
    2919            }
    2920        }
    2921
    2922
    2923        /// Negates self, overflowing if this is equal to the minimum value.
    2924        ///
    2925        /// Returns a tuple of the negated version of self along with a boolean indicating whether an overflow
    2926        /// happened. If `self` is the minimum value (e.g., `i32::MIN` for values of type `i32`), then the
    2927        /// minimum value will be returned again and `true` will be returned for an overflow happening.
    2928        ///
    2929        /// # Examples
    2930        ///
    2931        /// ```
    2932        #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".overflowing_neg(), (-2, false));")]
    2933        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_neg(), (", stringify!($SelfT), "::MIN, true));")]
    2934        /// ```
    2935        #[inline]
    2936        #[stable(feature = "wrapping", since = "1.7.0")]
    2937        #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
    2938        #[must_use = "this returns the result of the operation, \
    2939                      without modifying the original"]
    2940        #[allow(unused_attributes)]
    2941        pub const fn overflowing_neg(self) -> (Self, bool) {
    2942            if intrinsics::unlikely(self == Self::MIN) {
    2943                (Self::MIN, true)
    2944            } else {
    2945                (-self, false)
    2946            }
    2947        }
    2948
    2949        /// Shifts self left by `rhs` bits.
    2950        ///
    2951        /// Returns a tuple of the shifted version of self along with a boolean indicating whether the shift
    2952        /// value was larger than or equal to the number of bits. If the shift value is too large, then value is
    2953        /// masked (N-1) where N is the number of bits, and this value is then used to perform the shift.
    2954        ///
    2955        /// # Examples
    2956        ///
    2957        /// ```
    2958        #[doc = concat!("assert_eq!(0x1", stringify!($SelfT),".overflowing_shl(4), (0x10, false));")]
    2959        /// assert_eq!(0x1i32.overflowing_shl(36), (0x10, true));
    2960        #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".overflowing_shl(", stringify!($BITS_MINUS_ONE), "), (0, false));")]
    2961        /// ```
    2962        #[stable(feature = "wrapping", since = "1.7.0")]
    2963        #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
    2964        #[must_use = "this returns the result of the operation, \
    2965                      without modifying the original"]
    2966        #[inline]
    2967        pub const fn overflowing_shl(self, rhs: u32) -> (Self, bool) {
    2968            (self.wrapping_shl(rhs), rhs >= Self::BITS)
    2969        }
    2970
    2971        /// Shifts self right by `rhs` bits.
    2972        ///
    2973        /// Returns a tuple of the shifted version of self along with a boolean indicating whether the shift
    2974        /// value was larger than or equal to the number of bits. If the shift value is too large, then value is
    2975        /// masked (N-1) where N is the number of bits, and this value is then used to perform the shift.
    2976        ///
    2977        /// # Examples
    2978        ///
    2979        /// ```
    2980        #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".overflowing_shr(4), (0x1, false));")]
    2981        /// assert_eq!(0x10i32.overflowing_shr(36), (0x1, true));
    2982        /// ```
    2983        #[stable(feature = "wrapping", since = "1.7.0")]
    2984        #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
    2985        #[must_use = "this returns the result of the operation, \
    2986                      without modifying the original"]
    2987        #[inline]
    2988        pub const fn overflowing_shr(self, rhs: u32) -> (Self, bool) {
    2989            (self.wrapping_shr(rhs), rhs >= Self::BITS)
    2990        }
    2991
    2992        /// Computes the absolute value of `self`.
    2993        ///
    2994        /// Returns a tuple of the absolute version of self along with a boolean indicating whether an overflow
    2995        /// happened. If self is the minimum value
    2996        #[doc = concat!("(e.g., ", stringify!($SelfT), "::MIN for values of type ", stringify!($SelfT), "),")]
    2997        /// then the minimum value will be returned again and true will be returned
    2998        /// for an overflow happening.
    2999        ///
    3000        /// # Examples
    3001        ///
    3002        /// ```
    3003        #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".overflowing_abs(), (10, false));")]
    3004        #[doc = concat!("assert_eq!((-10", stringify!($SelfT), ").overflowing_abs(), (10, false));")]
    3005        #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN).overflowing_abs(), (", stringify!($SelfT), "::MIN, true));")]
    3006        /// ```
    3007        #[stable(feature = "no_panic_abs", since = "1.13.0")]
    3008        #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
    3009        #[must_use = "this returns the result of the operation, \
    3010                      without modifying the original"]
    3011        #[inline]
    3012        pub const fn overflowing_abs(self) -> (Self, bool) {
    3013            (self.wrapping_abs(), self == Self::MIN)
    3014        }
    3015
    3016        /// Raises self to the power of `exp`, using exponentiation by squaring.
    3017        ///
    3018        /// Returns a tuple of the exponentiation along with a bool indicating
    3019        /// whether an overflow happened.
    3020        ///
    3021        /// # Examples
    3022        ///
    3023        /// ```
    3024        #[doc = concat!("assert_eq!(3", stringify!($SelfT), ".overflowing_pow(4), (81, false));")]
    3025        #[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".overflowing_pow(0), (1, false));")]
    3026        /// assert_eq!(3i8.overflowing_pow(5), (-13, true));
    3027        /// ```
    3028        #[stable(feature = "no_panic_pow", since = "1.34.0")]
    3029        #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
    3030        #[must_use = "this returns the result of the operation, \
    3031                      without modifying the original"]
    3032        #[inline]
    3033        pub const fn overflowing_pow(self, mut exp: u32) -> (Self, bool) {
    3034            if exp == 0 {
    3035                return (1,false);
    3036            }
    3037            let mut base = self;
    3038            let mut acc: Self = 1;
    3039            let mut overflown = false;
    3040            // Scratch space for storing results of overflowing_mul.
    3041            let mut r;
    3042
    3043            loop {
    3044                if (exp & 1) == 1 {
    3045                    r = acc.overflowing_mul(base);
    3046                    // since exp!=0, finally the exp must be 1.
    3047                    if exp == 1 {
    3048                        r.1 |= overflown;
    3049                        return r;
    3050                    }
    3051                    acc = r.0;
    3052                    overflown |= r.1;
    3053                }
    3054                exp /= 2;
    3055                r = base.overflowing_mul(base);
    3056                base = r.0;
    3057                overflown |= r.1;
    3058            }
    3059        }
    3060
    3061        /// Raises self to the power of `exp`, using exponentiation by squaring.
    3062        ///
    3063        /// # Examples
    3064        ///
    3065        /// ```
    3066        #[doc = concat!("let x: ", stringify!($SelfT), " = 2; // or any other integer type")]
    3067        ///
    3068        /// assert_eq!(x.pow(5), 32);
    3069        #[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".pow(0), 1);")]
    3070        /// ```
    3071        #[stable(feature = "rust1", since = "1.0.0")]
    3072        #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
    3073        #[must_use = "this returns the result of the operation, \
    3074                      without modifying the original"]
    3075        #[inline]
    3076        #[rustc_inherit_overflow_checks]
    3077        pub const fn pow(self, mut exp: u32) -> Self {
    3078            if exp == 0 {
    3079                return 1;
    3080            }
    3081            let mut base = self;
    3082            let mut acc = 1;
    3083
    3084            if intrinsics::is_val_statically_known(exp) {
    3085                while exp > 1 {
    3086                    if (exp & 1) == 1 {
    3087                        acc = acc * base;
    3088                    }
    3089                    exp /= 2;
    3090                    base = base * base;
    3091                }
    3092
    3093                // since exp!=0, finally the exp must be 1.
    3094                // Deal with the final bit of the exponent separately, since
    3095                // squaring the base afterwards is not necessary and may cause a
    3096                // needless overflow.
    3097                acc * base
    3098            } else {
    3099                // This is faster than the above when the exponent is not known
    3100                // at compile time. We can't use the same code for the constant
    3101                // exponent case because LLVM is currently unable to unroll
    3102                // this loop.
    3103                loop {
    3104                    if (exp & 1) == 1 {
    3105                        acc = acc * base;
    3106                        // since exp!=0, finally the exp must be 1.
    3107                        if exp == 1 {
    3108                            return acc;
    3109                        }
    3110                    }
    3111                    exp /= 2;
    3112                    base = base * base;
    3113                }
    3114            }
    3115        }
    3116
    3117        /// Returns the square root of the number, rounded down.
    3118        ///
    3119        /// # Panics
    3120        ///
    3121        /// This function will panic if `self` is negative.
    3122        ///
    3123        /// # Examples
    3124        ///
    3125        /// ```
    3126        #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".isqrt(), 3);")]
    3127        /// ```
    3128        #[stable(feature = "isqrt", since = "1.84.0")]
    3129        #[rustc_const_stable(feature = "isqrt", since = "1.84.0")]
    3130        #[must_use = "this returns the result of the operation, \
    3131                      without modifying the original"]
    3132        #[inline]
    3133        #[track_caller]
    3134        pub const fn isqrt(self) -> Self {
    3135            match self.checked_isqrt() {
    3136                Some(sqrt) => sqrt,
    3137                None => crate::num::int_sqrt::panic_for_negative_argument(),
    3138            }
    3139        }
    3140
    3141        /// Calculates the quotient of Euclidean division of `self` by `rhs`.
    3142        ///
    3143        /// This computes the integer `q` such that `self = q * rhs + r`, with
    3144        /// `r = self.rem_euclid(rhs)` and `0 <= r < abs(rhs)`.
    3145        ///
    3146        /// In other words, the result is `self / rhs` rounded to the integer `q`
    3147        /// such that `self >= q * rhs`.
    3148        /// If `self > 0`, this is equal to rounding towards zero (the default in Rust);
    3149        /// if `self < 0`, this is equal to rounding away from zero (towards +/- infinity).
    3150        /// If `rhs > 0`, this is equal to rounding towards -infinity;
    3151        /// if `rhs < 0`, this is equal to rounding towards +infinity.
    3152        ///
    3153        /// # Panics
    3154        ///
    3155        /// This function will panic if `rhs` is zero or if `self` is `Self::MIN`
    3156        /// and `rhs` is -1. This behavior is not affected by the `overflow-checks` flag.
    3157        ///
    3158        /// # Examples
    3159        ///
    3160        /// ```
    3161        #[doc = concat!("let a: ", stringify!($SelfT), " = 7; // or any other integer type")]
    3162        /// let b = 4;
    3163        ///
    3164        /// assert_eq!(a.div_euclid(b), 1); // 7 >= 4 * 1
    3165        /// assert_eq!(a.div_euclid(-b), -1); // 7 >= -4 * -1
    3166        /// assert_eq!((-a).div_euclid(b), -2); // -7 >= 4 * -2
    3167        /// assert_eq!((-a).div_euclid(-b), 2); // -7 >= -4 * 2
    3168        /// ```
    3169        #[stable(feature = "euclidean_division", since = "1.38.0")]
    3170        #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
    3171        #[must_use = "this returns the result of the operation, \
    3172                      without modifying the original"]
    3173        #[inline]
    3174        #[track_caller]
    3175        pub const fn div_euclid(self, rhs: Self) -> Self {
    3176            let q = self / rhs;
    3177            if self % rhs < 0 {
    3178                return if rhs > 0 { q - 1 } else { q + 1 }
    3179            }
    3180            q
    3181        }
    3182
    3183
    3184        /// Calculates the least nonnegative remainder of `self` when
    3185        /// divided by `rhs`.
    3186        ///
    3187        /// This is done as if by the Euclidean division algorithm -- given
    3188        /// `r = self.rem_euclid(rhs)`, the result satisfies
    3189        /// `self = rhs * self.div_euclid(rhs) + r` and `0 <= r < abs(rhs)`.
    3190        ///
    3191        /// # Panics
    3192        ///
    3193        /// This function will panic if `rhs` is zero or if `self` is `Self::MIN` and
    3194        /// `rhs` is -1. This behavior is not affected by the `overflow-checks` flag.
    3195        ///
    3196        /// # Examples
    3197        ///
    3198        /// ```
    3199        #[doc = concat!("let a: ", stringify!($SelfT), " = 7; // or any other integer type")]
    3200        /// let b = 4;
    3201        ///
    3202        /// assert_eq!(a.rem_euclid(b), 3);
    3203        /// assert_eq!((-a).rem_euclid(b), 1);
    3204        /// assert_eq!(a.rem_euclid(-b), 3);
    3205        /// assert_eq!((-a).rem_euclid(-b), 1);
    3206        /// ```
    3207        ///
    3208        /// This will panic:
    3209        /// ```should_panic
    3210        #[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.rem_euclid(-1);")]
    3211        /// ```
    3212        #[doc(alias = "modulo", alias = "mod")]
    3213        #[stable(feature = "euclidean_division", since = "1.38.0")]
    3214        #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
    3215        #[must_use = "this returns the result of the operation, \
    3216                      without modifying the original"]
    3217        #[inline]
    3218        #[track_caller]
    3219        pub const fn rem_euclid(self, rhs: Self) -> Self {
    3220            let r = self % rhs;
    3221            if r < 0 {
    3222                // Semantically equivalent to `if rhs < 0 { r - rhs } else { r + rhs }`.
    3223                // If `rhs` is not `Self::MIN`, then `r + abs(rhs)` will not overflow
    3224                // and is clearly equivalent, because `r` is negative.
    3225                // Otherwise, `rhs` is `Self::MIN`, then we have
    3226                // `r.wrapping_add(Self::MIN.wrapping_abs())`, which evaluates
    3227                // to `r.wrapping_add(Self::MIN)`, which is equivalent to
    3228                // `r - Self::MIN`, which is what we wanted (and will not overflow
    3229                // for negative `r`).
    3230                r.wrapping_add(rhs.wrapping_abs())
    3231            } else {
    3232                r
    3233            }
    3234        }
    3235
    3236        /// Calculates the quotient of `self` and `rhs`, rounding the result towards negative infinity.
    3237        ///
    3238        /// # Panics
    3239        ///
    3240        /// This function will panic if `rhs` is zero or if `self` is `Self::MIN`
    3241        /// and `rhs` is -1. This behavior is not affected by the `overflow-checks` flag.
    3242        ///
    3243        /// # Examples
    3244        ///
    3245        /// ```
    3246        /// #![feature(int_roundings)]
    3247        #[doc = concat!("let a: ", stringify!($SelfT)," = 8;")]
    3248        /// let b = 3;
    3249        ///
    3250        /// assert_eq!(a.div_floor(b), 2);
    3251        /// assert_eq!(a.div_floor(-b), -3);
    3252        /// assert_eq!((-a).div_floor(b), -3);
    3253        /// assert_eq!((-a).div_floor(-b), 2);
    3254        /// ```
    3255        #[unstable(feature = "int_roundings", issue = "88581")]
    3256        #[must_use = "this returns the result of the operation, \
    3257                      without modifying the original"]
    3258        #[inline]
    3259        #[track_caller]
    3260        pub const fn div_floor(self, rhs: Self) -> Self {
    3261            let d = self / rhs;
    3262            let r = self % rhs;
    3263
    3264            // If the remainder is non-zero, we need to subtract one if the
    3265            // signs of self and rhs differ, as this means we rounded upwards
    3266            // instead of downwards. We do this branchlessly by creating a mask
    3267            // which is all-ones iff the signs differ, and 0 otherwise. Then by
    3268            // adding this mask (which corresponds to the signed value -1), we
    3269            // get our correction.
    3270            let correction = (self ^ rhs) >> (Self::BITS - 1);
    3271            if r != 0 {
    3272                d + correction
    3273            } else {
    3274                d
    3275            }
    3276        }
    3277
    3278        /// Calculates the quotient of `self` and `rhs`, rounding the result towards positive infinity.
    3279        ///
    3280        /// # Panics
    3281        ///
    3282        /// This function will panic if `rhs` is zero or if `self` is `Self::MIN`
    3283        /// and `rhs` is -1. This behavior is not affected by the `overflow-checks` flag.
    3284        ///
    3285        /// # Examples
    3286        ///
    3287        /// ```
    3288        /// #![feature(int_roundings)]
    3289        #[doc = concat!("let a: ", stringify!($SelfT)," = 8;")]
    3290        /// let b = 3;
    3291        ///
    3292        /// assert_eq!(a.div_ceil(b), 3);
    3293        /// assert_eq!(a.div_ceil(-b), -2);
    3294        /// assert_eq!((-a).div_ceil(b), -2);
    3295        /// assert_eq!((-a).div_ceil(-b), 3);
    3296        /// ```
    3297        #[unstable(feature = "int_roundings", issue = "88581")]
    3298        #[must_use = "this returns the result of the operation, \
    3299                      without modifying the original"]
    3300        #[inline]
    3301        #[track_caller]
    3302        pub const fn div_ceil(self, rhs: Self) -> Self {
    3303            let d = self / rhs;
    3304            let r = self % rhs;
    3305
    3306            // When remainder is non-zero we have a.div_ceil(b) == 1 + a.div_floor(b),
    3307            // so we can re-use the algorithm from div_floor, just adding 1.
    3308            let correction = 1 + ((self ^ rhs) >> (Self::BITS - 1));
    3309            if r != 0 {
    3310                d + correction
    3311            } else {
    3312                d
    3313            }
    3314        }
    3315
    3316        /// If `rhs` is positive, calculates the smallest value greater than or
    3317        /// equal to `self` that is a multiple of `rhs`. If `rhs` is negative,
    3318        /// calculates the largest value less than or equal to `self` that is a
    3319        /// multiple of `rhs`.
    3320        ///
    3321        /// # Panics
    3322        ///
    3323        /// This function will panic if `rhs` is zero.
    3324        ///
    3325        /// ## Overflow behavior
    3326        ///
    3327        /// On overflow, this function will panic if overflow checks are enabled (default in debug
    3328        /// mode) and wrap if overflow checks are disabled (default in release mode).
    3329        ///
    3330        /// # Examples
    3331        ///
    3332        /// ```
    3333        /// #![feature(int_roundings)]
    3334        #[doc = concat!("assert_eq!(16_", stringify!($SelfT), ".next_multiple_of(8), 16);")]
    3335        #[doc = concat!("assert_eq!(23_", stringify!($SelfT), ".next_multiple_of(8), 24);")]
    3336        #[doc = concat!("assert_eq!(16_", stringify!($SelfT), ".next_multiple_of(-8), 16);")]
    3337        #[doc = concat!("assert_eq!(23_", stringify!($SelfT), ".next_multiple_of(-8), 16);")]
    3338        #[doc = concat!("assert_eq!((-16_", stringify!($SelfT), ").next_multiple_of(8), -16);")]
    3339        #[doc = concat!("assert_eq!((-23_", stringify!($SelfT), ").next_multiple_of(8), -16);")]
    3340        #[doc = concat!("assert_eq!((-16_", stringify!($SelfT), ").next_multiple_of(-8), -16);")]
    3341        #[doc = concat!("assert_eq!((-23_", stringify!($SelfT), ").next_multiple_of(-8), -24);")]
    3342        /// ```
    3343        #[unstable(feature = "int_roundings", issue = "88581")]
    3344        #[must_use = "this returns the result of the operation, \
    3345                      without modifying the original"]
    3346        #[inline]
    3347        #[rustc_inherit_overflow_checks]
    3348        pub const fn next_multiple_of(self, rhs: Self) -> Self {
    3349            // This would otherwise fail when calculating `r` when self == T::MIN.
    3350            if rhs == -1 {
    3351                return self;
    3352            }
    3353
    3354            let r = self % rhs;
    3355            let m = if (r > 0 && rhs < 0) || (r < 0 && rhs > 0) {
    3356                r + rhs
    3357            } else {
    3358                r
    3359            };
    3360
    3361            if m == 0 {
    3362                self
    3363            } else {
    3364                self + (rhs - m)
    3365            }
    3366        }
    3367
    3368        /// If `rhs` is positive, calculates the smallest value greater than or
    3369        /// equal to `self` that is a multiple of `rhs`. If `rhs` is negative,
    3370        /// calculates the largest value less than or equal to `self` that is a
    3371        /// multiple of `rhs`. Returns `None` if `rhs` is zero or the operation
    3372        /// would result in overflow.
    3373        ///
    3374        /// # Examples
    3375        ///
    3376        /// ```
    3377        /// #![feature(int_roundings)]
    3378        #[doc = concat!("assert_eq!(16_", stringify!($SelfT), ".checked_next_multiple_of(8), Some(16));")]
    3379        #[doc = concat!("assert_eq!(23_", stringify!($SelfT), ".checked_next_multiple_of(8), Some(24));")]
    3380        #[doc = concat!("assert_eq!(16_", stringify!($SelfT), ".checked_next_multiple_of(-8), Some(16));")]
    3381        #[doc = concat!("assert_eq!(23_", stringify!($SelfT), ".checked_next_multiple_of(-8), Some(16));")]
    3382        #[doc = concat!("assert_eq!((-16_", stringify!($SelfT), ").checked_next_multiple_of(8), Some(-16));")]
    3383        #[doc = concat!("assert_eq!((-23_", stringify!($SelfT), ").checked_next_multiple_of(8), Some(-16));")]
    3384        #[doc = concat!("assert_eq!((-16_", stringify!($SelfT), ").checked_next_multiple_of(-8), Some(-16));")]
    3385        #[doc = concat!("assert_eq!((-23_", stringify!($SelfT), ").checked_next_multiple_of(-8), Some(-24));")]
    3386        #[doc = concat!("assert_eq!(1_", stringify!($SelfT), ".checked_next_multiple_of(0), None);")]
    3387        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_next_multiple_of(2), None);")]
    3388        /// ```
    3389        #[unstable(feature = "int_roundings", issue = "88581")]
    3390        #[must_use = "this returns the result of the operation, \
    3391                      without modifying the original"]
    3392        #[inline]
    3393        pub const fn checked_next_multiple_of(self, rhs: Self) -> Option<Self> {
    3394            // This would otherwise fail when calculating `r` when self == T::MIN.
    3395            if rhs == -1 {
    3396                return Some(self);
    3397            }
    3398
    3399            let r = try_opt!(self.checked_rem(rhs));
    3400            let m = if (r > 0 && rhs < 0) || (r < 0 && rhs > 0) {
    3401                // r + rhs cannot overflow because they have opposite signs
    3402                r + rhs
    3403            } else {
    3404                r
    3405            };
    3406
    3407            if m == 0 {
    3408                Some(self)
    3409            } else {
    3410                // rhs - m cannot overflow because m has the same sign as rhs
    3411                self.checked_add(rhs - m)
    3412            }
    3413        }
    3414
    3415        /// Returns the logarithm of the number with respect to an arbitrary base,
    3416        /// rounded down.
    3417        ///
    3418        /// This method might not be optimized owing to implementation details;
    3419        /// `ilog2` can produce results more efficiently for base 2, and `ilog10`
    3420        /// can produce results more efficiently for base 10.
    3421        ///
    3422        /// # Panics
    3423        ///
    3424        /// This function will panic if `self` is less than or equal to zero,
    3425        /// or if `base` is less than 2.
    3426        ///
    3427        /// # Examples
    3428        ///
    3429        /// ```
    3430        #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".ilog(5), 1);")]
    3431        /// ```
    3432        #[stable(feature = "int_log", since = "1.67.0")]
    3433        #[rustc_const_stable(feature = "int_log", since = "1.67.0")]
    3434        #[must_use = "this returns the result of the operation, \
    3435                      without modifying the original"]
    3436        #[inline]
    3437        #[track_caller]
    3438        pub const fn ilog(self, base: Self) -> u32 {
    3439            assert!(base >= 2, "base of integer logarithm must be at least 2");
    3440            if let Some(log) = self.checked_ilog(base) {
    3441                log
    3442            } else {
    3443                int_log10::panic_for_nonpositive_argument()
    3444            }
    3445        }
    3446
    3447        /// Returns the base 2 logarithm of the number, rounded down.
    3448        ///
    3449        /// # Panics
    3450        ///
    3451        /// This function will panic if `self` is less than or equal to zero.
    3452        ///
    3453        /// # Examples
    3454        ///
    3455        /// ```
    3456        #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".ilog2(), 1);")]
    3457        /// ```
    3458        #[stable(feature = "int_log", since = "1.67.0")]
    3459        #[rustc_const_stable(feature = "int_log", since = "1.67.0")]
    3460        #[must_use = "this returns the result of the operation, \
    3461                      without modifying the original"]
    3462        #[inline]
    3463        #[track_caller]
    3464        pub const fn ilog2(self) -> u32 {
    3465            if let Some(log) = self.checked_ilog2() {
    3466                log
    3467            } else {
    3468                int_log10::panic_for_nonpositive_argument()
    3469            }
    3470        }
    3471
    3472        /// Returns the base 10 logarithm of the number, rounded down.
    3473        ///
    3474        /// # Panics
    3475        ///
    3476        /// This function will panic if `self` is less than or equal to zero.
    3477        ///
    3478        /// # Example
    3479        ///
    3480        /// ```
    3481        #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".ilog10(), 1);")]
    3482        /// ```
    3483        #[stable(feature = "int_log", since = "1.67.0")]
    3484        #[rustc_const_stable(feature = "int_log", since = "1.67.0")]
    3485        #[must_use = "this returns the result of the operation, \
    3486                      without modifying the original"]
    3487        #[inline]
    3488        #[track_caller]
    3489        pub const fn ilog10(self) -> u32 {
    3490            if let Some(log) = self.checked_ilog10() {
    3491                log
    3492            } else {
    3493                int_log10::panic_for_nonpositive_argument()
    3494            }
    3495        }
    3496
    3497        /// Returns the logarithm of the number with respect to an arbitrary base,
    3498        /// rounded down.
    3499        ///
    3500        /// Returns `None` if the number is negative or zero, or if the base is not at least 2.
    3501        ///
    3502        /// This method might not be optimized owing to implementation details;
    3503        /// `checked_ilog2` can produce results more efficiently for base 2, and
    3504        /// `checked_ilog10` can produce results more efficiently for base 10.
    3505        ///
    3506        /// # Examples
    3507        ///
    3508        /// ```
    3509        #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_ilog(5), Some(1));")]
    3510        /// ```
    3511        #[stable(feature = "int_log", since = "1.67.0")]
    3512        #[rustc_const_stable(feature = "int_log", since = "1.67.0")]
    3513        #[must_use = "this returns the result of the operation, \
    3514                      without modifying the original"]
    3515        #[inline]
    3516        pub const fn checked_ilog(self, base: Self) -> Option<u32> {
    3517            if self <= 0 || base <= 1 {
    3518                None
    3519            } else {
    3520                // Delegate to the unsigned implementation.
    3521                // The condition makes sure that both casts are exact.
    3522                (self as $UnsignedT).checked_ilog(base as $UnsignedT)
    3523            }
    3524        }
    3525
    3526        /// Returns the base 2 logarithm of the number, rounded down.
    3527        ///
    3528        /// Returns `None` if the number is negative or zero.
    3529        ///
    3530        /// # Examples
    3531        ///
    3532        /// ```
    3533        #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".checked_ilog2(), Some(1));")]
    3534        /// ```
    3535        #[stable(feature = "int_log", since = "1.67.0")]
    3536        #[rustc_const_stable(feature = "int_log", since = "1.67.0")]
    3537        #[must_use = "this returns the result of the operation, \
    3538                      without modifying the original"]
    3539        #[inline]
    3540        pub const fn checked_ilog2(self) -> Option<u32> {
    3541            if self <= 0 {
    3542                None
    3543            } else {
    3544                // SAFETY: We just checked that this number is positive
    3545                let log = (Self::BITS - 1) - unsafe { intrinsics::ctlz_nonzero(self) as u32 };
    3546                Some(log)
    3547            }
    3548        }
    3549
    3550        /// Returns the base 10 logarithm of the number, rounded down.
    3551        ///
    3552        /// Returns `None` if the number is negative or zero.
    3553        ///
    3554        /// # Example
    3555        ///
    3556        /// ```
    3557        #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".checked_ilog10(), Some(1));")]
    3558        /// ```
    3559        #[stable(feature = "int_log", since = "1.67.0")]
    3560        #[rustc_const_stable(feature = "int_log", since = "1.67.0")]
    3561        #[must_use = "this returns the result of the operation, \
    3562                      without modifying the original"]
    3563        #[inline]
    3564        pub const fn checked_ilog10(self) -> Option<u32> {
    3565            int_log10::$ActualT(self as $ActualT)
    3566        }
    3567
    3568        /// Computes the absolute value of `self`.
    3569        ///
    3570        /// # Overflow behavior
    3571        ///
    3572        /// The absolute value of
    3573        #[doc = concat!("`", stringify!($SelfT), "::MIN`")]
    3574        /// cannot be represented as an
    3575        #[doc = concat!("`", stringify!($SelfT), "`,")]
    3576        /// and attempting to calculate it will cause an overflow. This means
    3577        /// that code in debug mode will trigger a panic on this case and
    3578        /// optimized code will return
    3579        #[doc = concat!("`", stringify!($SelfT), "::MIN`")]
    3580        /// without a panic. If you do not want this behavior, consider
    3581        /// using [`unsigned_abs`](Self::unsigned_abs) instead.
    3582        ///
    3583        /// # Examples
    3584        ///
    3585        /// ```
    3586        #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".abs(), 10);")]
    3587        #[doc = concat!("assert_eq!((-10", stringify!($SelfT), ").abs(), 10);")]
    3588        /// ```
    3589        #[stable(feature = "rust1", since = "1.0.0")]
    3590        #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
    3591        #[allow(unused_attributes)]
    3592        #[must_use = "this returns the result of the operation, \
    3593                      without modifying the original"]
    3594        #[inline]
    3595        #[rustc_inherit_overflow_checks]
    3596        pub const fn abs(self) -> Self {
    3597            // Note that the #[rustc_inherit_overflow_checks] and #[inline]
    3598            // above mean that the overflow semantics of the subtraction
    3599            // depend on the crate we're being called from.
    3600            if self.is_negative() {
    3601                -self
    3602            } else {
    3603                self
    3604            }
    3605        }
    3606
    3607        /// Computes the absolute difference between `self` and `other`.
    3608        ///
    3609        /// This function always returns the correct answer without overflow or
    3610        /// panics by returning an unsigned integer.
    3611        ///
    3612        /// # Examples
    3613        ///
    3614        /// ```
    3615        #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".abs_diff(80), 20", stringify!($UnsignedT), ");")]
    3616        #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".abs_diff(110), 10", stringify!($UnsignedT), ");")]
    3617        #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").abs_diff(80), 180", stringify!($UnsignedT), ");")]
    3618        #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").abs_diff(-120), 20", stringify!($UnsignedT), ");")]
    3619        #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.abs_diff(", stringify!($SelfT), "::MAX), ", stringify!($UnsignedT), "::MAX);")]
    3620        /// ```
    3621        #[stable(feature = "int_abs_diff", since = "1.60.0")]
    3622        #[rustc_const_stable(feature = "int_abs_diff", since = "1.60.0")]
    3623        #[must_use = "this returns the result of the operation, \
    3624                      without modifying the original"]
    3625        #[inline]
    3626        pub const fn abs_diff(self, other: Self) -> $UnsignedT {
    3627            if self < other {
    3628                // Converting a non-negative x from signed to unsigned by using
    3629                // `x as U` is left unchanged, but a negative x is converted
    3630                // to value x + 2^N. Thus if `s` and `o` are binary variables
    3631                // respectively indicating whether `self` and `other` are
    3632                // negative, we are computing the mathematical value:
    3633                //
    3634                //    (other + o*2^N) - (self + s*2^N)    mod  2^N
    3635                //    other - self + (o-s)*2^N            mod  2^N
    3636                //    other - self                        mod  2^N
    3637                //
    3638                // Finally, taking the mod 2^N of the mathematical value of
    3639                // `other - self` does not change it as it already is
    3640                // in the range [0, 2^N).
    3641                (other as $UnsignedT).wrapping_sub(self as $UnsignedT)
    3642            } else {
    3643                (self as $UnsignedT).wrapping_sub(other as $UnsignedT)
    3644            }
    3645        }
    3646
    3647        /// Returns a number representing sign of `self`.
    3648        ///
    3649        ///  - `0` if the number is zero
    3650        ///  - `1` if the number is positive
    3651        ///  - `-1` if the number is negative
    3652        ///
    3653        /// # Examples
    3654        ///
    3655        /// ```
    3656        #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".signum(), 1);")]
    3657        #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".signum(), 0);")]
    3658        #[doc = concat!("assert_eq!((-10", stringify!($SelfT), ").signum(), -1);")]
    3659        /// ```
    3660        #[stable(feature = "rust1", since = "1.0.0")]
    3661        #[rustc_const_stable(feature = "const_int_sign", since = "1.47.0")]
    3662        #[must_use = "this returns the result of the operation, \
    3663                      without modifying the original"]
    3664        #[inline(always)]
    3665        pub const fn signum(self) -> Self {
    3666            // Picking the right way to phrase this is complicated
    3667            // (<https://graphics.stanford.edu/~seander/bithacks.html#CopyIntegerSign>)
    3668            // so delegate it to `Ord` which is already producing -1/0/+1
    3669            // exactly like we need and can be the place to deal with the complexity.
    3670
    3671            crate::intrinsics::three_way_compare(self, 0) as Self
    3672        }
    3673
    3674        /// Returns `true` if `self` is positive and `false` if the number is zero or
    3675        /// negative.
    3676        ///
    3677        /// # Examples
    3678        ///
    3679        /// ```
    3680        #[doc = concat!("assert!(10", stringify!($SelfT), ".is_positive());")]
    3681        #[doc = concat!("assert!(!(-10", stringify!($SelfT), ").is_positive());")]
    3682        /// ```
    3683        #[must_use]
    3684        #[stable(feature = "rust1", since = "1.0.0")]
    3685        #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
    3686        #[inline(always)]
    3687        pub const fn is_positive(self) -> bool { self > 0 }
    3688
    3689        /// Returns `true` if `self` is negative and `false` if the number is zero or
    3690        /// positive.
    3691        ///
    3692        /// # Examples
    3693        ///
    3694        /// ```
    3695        #[doc = concat!("assert!((-10", stringify!($SelfT), ").is_negative());")]
    3696        #[doc = concat!("assert!(!10", stringify!($SelfT), ".is_negative());")]
    3697        /// ```
    3698        #[must_use]
    3699        #[stable(feature = "rust1", since = "1.0.0")]
    3700        #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
    3701        #[inline(always)]
    3702        pub const fn is_negative(self) -> bool { self < 0 }
    3703
    3704        /// Returns the memory representation of this integer as a byte array in
    3705        /// big-endian (network) byte order.
    3706        ///
    3707        #[doc = $to_xe_bytes_doc]
    3708        ///
    3709        /// # Examples
    3710        ///
    3711        /// ```
    3712        #[doc = concat!("let bytes = ", $swap_op, stringify!($SelfT), ".to_be_bytes();")]
    3713        #[doc = concat!("assert_eq!(bytes, ", $be_bytes, ");")]
    3714        /// ```
    3715        #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
    3716        #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
    3717        #[must_use = "this returns the result of the operation, \
    3718                      without modifying the original"]
    3719        #[inline]
    3720        pub const fn to_be_bytes(self) -> [u8; size_of::<Self>()] {
    3721            self.to_be().to_ne_bytes()
    3722        }
    3723
    3724        /// Returns the memory representation of this integer as a byte array in
    3725        /// little-endian byte order.
    3726        ///
    3727        #[doc = $to_xe_bytes_doc]
    3728        ///
    3729        /// # Examples
    3730        ///
    3731        /// ```
    3732        #[doc = concat!("let bytes = ", $swap_op, stringify!($SelfT), ".to_le_bytes();")]
    3733        #[doc = concat!("assert_eq!(bytes, ", $le_bytes, ");")]
    3734        /// ```
    3735        #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
    3736        #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
    3737        #[must_use = "this returns the result of the operation, \
    3738                      without modifying the original"]
    3739        #[inline]
    3740        pub const fn to_le_bytes(self) -> [u8; size_of::<Self>()] {
    3741            self.to_le().to_ne_bytes()
    3742        }
    3743
    3744        /// Returns the memory representation of this integer as a byte array in
    3745        /// native byte order.
    3746        ///
    3747        /// As the target platform's native endianness is used, portable code
    3748        /// should use [`to_be_bytes`] or [`to_le_bytes`], as appropriate,
    3749        /// instead.
    3750        ///
    3751        #[doc = $to_xe_bytes_doc]
    3752        ///
    3753        /// [`to_be_bytes`]: Self::to_be_bytes
    3754        /// [`to_le_bytes`]: Self::to_le_bytes
    3755        ///
    3756        /// # Examples
    3757        ///
    3758        /// ```
    3759        #[doc = concat!("let bytes = ", $swap_op, stringify!($SelfT), ".to_ne_bytes();")]
    3760        /// assert_eq!(
    3761        ///     bytes,
    3762        ///     if cfg!(target_endian = "big") {
    3763        #[doc = concat!("        ", $be_bytes)]
    3764        ///     } else {
    3765        #[doc = concat!("        ", $le_bytes)]
    3766        ///     }
    3767        /// );
    3768        /// ```
    3769        #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
    3770        #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
    3771        #[allow(unnecessary_transmutes)]
    3772        // SAFETY: const sound because integers are plain old datatypes so we can always
    3773        // transmute them to arrays of bytes
    3774        #[must_use = "this returns the result of the operation, \
    3775                      without modifying the original"]
    3776        #[inline]
    3777        pub const fn to_ne_bytes(self) -> [u8; size_of::<Self>()] {
    3778            // SAFETY: integers are plain old datatypes so we can always transmute them to
    3779            // arrays of bytes
    3780            unsafe { mem::transmute(self) }
    3781        }
    3782
    3783        /// Creates an integer value from its representation as a byte array in
    3784        /// big endian.
    3785        ///
    3786        #[doc = $from_xe_bytes_doc]
    3787        ///
    3788        /// # Examples
    3789        ///
    3790        /// ```
    3791        #[doc = concat!("let value = ", stringify!($SelfT), "::from_be_bytes(", $be_bytes, ");")]
    3792        #[doc = concat!("assert_eq!(value, ", $swap_op, ");")]
    3793        /// ```
    3794        ///
    3795        /// When starting from a slice rather than an array, fallible conversion APIs can be used:
    3796        ///
    3797        /// ```
    3798        #[doc = concat!("fn read_be_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {")]
    3799        #[doc = concat!("    let (int_bytes, rest) = input.split_at(size_of::<", stringify!($SelfT), ">());")]
    3800        ///     *input = rest;
    3801        #[doc = concat!("    ", stringify!($SelfT), "::from_be_bytes(int_bytes.try_into().unwrap())")]
    3802        /// }
    3803        /// ```
    3804        #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
    3805        #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
    3806        #[must_use]
    3807        #[inline]
    3808        pub const fn from_be_bytes(bytes: [u8; size_of::<Self>()]) -> Self {
    3809            Self::from_be(Self::from_ne_bytes(bytes))
    3810        }
    3811
    3812        /// Creates an integer value from its representation as a byte array in
    3813        /// little endian.
    3814        ///
    3815        #[doc = $from_xe_bytes_doc]
    3816        ///
    3817        /// # Examples
    3818        ///
    3819        /// ```
    3820        #[doc = concat!("let value = ", stringify!($SelfT), "::from_le_bytes(", $le_bytes, ");")]
    3821        #[doc = concat!("assert_eq!(value, ", $swap_op, ");")]
    3822        /// ```
    3823        ///
    3824        /// When starting from a slice rather than an array, fallible conversion APIs can be used:
    3825        ///
    3826        /// ```
    3827        #[doc = concat!("fn read_le_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {")]
    3828        #[doc = concat!("    let (int_bytes, rest) = input.split_at(size_of::<", stringify!($SelfT), ">());")]
    3829        ///     *input = rest;
    3830        #[doc = concat!("    ", stringify!($SelfT), "::from_le_bytes(int_bytes.try_into().unwrap())")]
    3831        /// }
    3832        /// ```
    3833        #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
    3834        #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
    3835        #[must_use]
    3836        #[inline]
    3837        pub const fn from_le_bytes(bytes: [u8; size_of::<Self>()]) -> Self {
    3838            Self::from_le(Self::from_ne_bytes(bytes))
    3839        }
    3840
    3841        /// Creates an integer value from its memory representation as a byte
    3842        /// array in native endianness.
    3843        ///
    3844        /// As the target platform's native endianness is used, portable code
    3845        /// likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as
    3846        /// appropriate instead.
    3847        ///
    3848        /// [`from_be_bytes`]: Self::from_be_bytes
    3849        /// [`from_le_bytes`]: Self::from_le_bytes
    3850        ///
    3851        #[doc = $from_xe_bytes_doc]
    3852        ///
    3853        /// # Examples
    3854        ///
    3855        /// ```
    3856        #[doc = concat!("let value = ", stringify!($SelfT), "::from_ne_bytes(if cfg!(target_endian = \"big\") {")]
    3857        #[doc = concat!("    ", $be_bytes)]
    3858        /// } else {
    3859        #[doc = concat!("    ", $le_bytes)]
    3860        /// });
    3861        #[doc = concat!("assert_eq!(value, ", $swap_op, ");")]
    3862        /// ```
    3863        ///
    3864        /// When starting from a slice rather than an array, fallible conversion APIs can be used:
    3865        ///
    3866        /// ```
    3867        #[doc = concat!("fn read_ne_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {")]
    3868        #[doc = concat!("    let (int_bytes, rest) = input.split_at(size_of::<", stringify!($SelfT), ">());")]
    3869        ///     *input = rest;
    3870        #[doc = concat!("    ", stringify!($SelfT), "::from_ne_bytes(int_bytes.try_into().unwrap())")]
    3871        /// }
    3872        /// ```
    3873        #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
    3874        #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
    3875        #[allow(unnecessary_transmutes)]
    3876        #[must_use]
    3877        // SAFETY: const sound because integers are plain old datatypes so we can always
    3878        // transmute to them
    3879        #[inline]
    3880        pub const fn from_ne_bytes(bytes: [u8; size_of::<Self>()]) -> Self {
    3881            // SAFETY: integers are plain old datatypes so we can always transmute to them
    3882            unsafe { mem::transmute(bytes) }
    3883        }
    3884
    3885        /// New code should prefer to use
    3886        #[doc = concat!("[`", stringify!($SelfT), "::MIN", "`] instead.")]
    3887        ///
    3888        /// Returns the smallest value that can be represented by this integer type.
    3889        #[stable(feature = "rust1", since = "1.0.0")]
    3890        #[inline(always)]
    3891        #[rustc_promotable]
    3892        #[rustc_const_stable(feature = "const_min_value", since = "1.32.0")]
    3893        #[deprecated(since = "TBD", note = "replaced by the `MIN` associated constant on this type")]
    3894        #[rustc_diagnostic_item = concat!(stringify!($SelfT), "_legacy_fn_min_value")]
    3895        pub const fn min_value() -> Self {
    3896            Self::MIN
    3897        }
    3898
    3899        /// New code should prefer to use
    3900        #[doc = concat!("[`", stringify!($SelfT), "::MAX", "`] instead.")]
    3901        ///
    3902        /// Returns the largest value that can be represented by this integer type.
    3903        #[stable(feature = "rust1", since = "1.0.0")]
    3904        #[inline(always)]
    3905        #[rustc_promotable]
    3906        #[rustc_const_stable(feature = "const_max_value", since = "1.32.0")]
    3907        #[deprecated(since = "TBD", note = "replaced by the `MAX` associated constant on this type")]
    3908        #[rustc_diagnostic_item = concat!(stringify!($SelfT), "_legacy_fn_max_value")]
    3909        pub const fn max_value() -> Self {
    3910            Self::MAX
    3911        }
    3912
    3913        /// Clamps this number to a symmetric range centred around zero.
    3914        ///
    3915        /// The method clamps the number's magnitude (absolute value) to be at most `limit`.
    3916        ///
    3917        /// This is functionally equivalent to `self.clamp(-limit, limit)`, but is more
    3918        /// explicit about the intent.
    3919        ///
    3920        /// # Examples
    3921        ///
    3922        /// ```
    3923        /// #![feature(clamp_magnitude)]
    3924        #[doc = concat!("assert_eq!(120", stringify!($SelfT), ".clamp_magnitude(100), 100);")]
    3925        #[doc = concat!("assert_eq!(-120", stringify!($SelfT), ".clamp_magnitude(100), -100);")]
    3926        #[doc = concat!("assert_eq!(80", stringify!($SelfT), ".clamp_magnitude(100), 80);")]
    3927        #[doc = concat!("assert_eq!(-80", stringify!($SelfT), ".clamp_magnitude(100), -80);")]
    3928        /// ```
    3929        #[must_use = "this returns the clamped value and does not modify the original"]
    3930        #[unstable(feature = "clamp_magnitude", issue = "148519")]
    3931        #[inline]
    3932        pub fn clamp_magnitude(self, limit: $UnsignedT) -> Self {
    3933            if let Ok(limit) = core::convert::TryInto::<$SelfT>::try_into(limit) {
    3934                self.clamp(-limit, limit)
    3935            } else {
    3936                self
    3937            }
    3938        }
    3939    }
    3940}