library/core/src/num/int_macros.rs

   1 macro_rules! int_impl {
   2     ($SelfT:ty, $ActualT:ident, $UnsignedT:ty, $BITS:expr, $BITS_MINUS_ONE:expr, $Min:expr, $Max:expr,
   3      $rot:expr, $rot_op:expr, $rot_result:expr, $swap_op:expr, $swapped:expr,
   4      $reversed:expr, $le_bytes:expr, $be_bytes:expr,
   5      $to_xe_bytes_doc:expr, $from_xe_bytes_doc:expr,
   6      $bound_condition:expr) => {
   7         /// The smallest value that can be represented by this integer type
   8         #[doc = concat!("(&minus;2<sup>", $BITS_MINUS_ONE, "</sup>", $bound_condition, ")")]
   9         ///
  10         /// # Examples
  11         ///
  12         /// Basic usage:
  13         ///
  14         /// ```
  15         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN, ", stringify!($Min), ");")]
  16         /// ```
  17         #[stable(feature = "assoc_int_consts", since = "1.43.0")]
  18         pub const MIN: Self = !0 ^ ((!0 as $UnsignedT) >> 1) as Self;
  19
  20         /// The largest value that can be represented by this integer type
  21         #[doc = concat!("(2<sup>", $BITS_MINUS_ONE, "</sup> &minus; 1", $bound_condition, ")")]
  22         ///
  23         /// # Examples
  24         ///
  25         /// Basic usage:
  26         ///
  27         /// ```
  28         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX, ", stringify!($Max), ");")]
  29         /// ```
  30         #[stable(feature = "assoc_int_consts", since = "1.43.0")]
  31         pub const MAX: Self = !Self::MIN;
  32
  33         /// The size of this integer type in bits.
  34         ///
  35         /// # Examples
  36         ///
  37         /// ```
  38         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::BITS, ", stringify!($BITS), ");")]
  39         /// ```
  40         #[stable(feature = "int_bits_const", since = "1.53.0")]
  41         pub const BITS: u32 = $BITS;
  42
  43         /// Converts a string slice in a given base to an integer.
  44         ///
  45         /// The string is expected to be an optional `+` or `-` sign followed by digits.
  46         /// Leading and trailing whitespace represent an error. Digits are a subset of these characters,
  47         /// depending on `radix`:
  48         ///
  49         ///  * `0-9`
  50         ///  * `a-z`
  51         ///  * `A-Z`
  52         ///
  53         /// # Panics
  54         ///
  55         /// This function panics if `radix` is not in the range from 2 to 36.
  56         ///
  57         /// # Examples
  58         ///
  59         /// Basic usage:
  60         ///
  61         /// ```
  62         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::from_str_radix(\"A\", 16), Ok(10));")]
  63         /// ```
  64         #[stable(feature = "rust1", since = "1.0.0")]
  65         pub fn from_str_radix(src: &str, radix: u32) -> Result<Self, ParseIntError> {
  66             from_str_radix(src, radix)
  67         }
  68
  69         /// Returns the number of ones in the binary representation of `self`.
  70         ///
  71         /// # Examples
  72         ///
  73         /// Basic usage:
  74         ///
  75         /// ```
  76         #[doc = concat!("let n = 0b100_0000", stringify!($SelfT), ";")]
  77         ///
  78         /// assert_eq!(n.count_ones(), 1);
  79         /// ```
  80         ///
  81         #[stable(feature = "rust1", since = "1.0.0")]
  82         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
  83         #[doc(alias = "popcount")]
  84         #[doc(alias = "popcnt")]
  85         #[must_use = "this returns the result of the operation, \
  86                       without modifying the original"]
  87         #[inline(always)]
  88         pub const fn count_ones(self) -> u32 { (self as $UnsignedT).count_ones() }
  89
  90         /// Returns the number of zeros in the binary representation of `self`.
  91         ///
  92         /// # Examples
  93         ///
  94         /// Basic usage:
  95         ///
  96         /// ```
  97         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.count_zeros(), 1);")]
  98         /// ```
  99         #[stable(feature = "rust1", since = "1.0.0")]
 100         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
 101         #[must_use = "this returns the result of the operation, \
 102                       without modifying the original"]
 103         #[inline(always)]
 104         pub const fn count_zeros(self) -> u32 {
 105             (!self).count_ones()
 106         }
 107
 108         /// Returns the number of leading zeros in the binary representation of `self`.
 109         ///
 110         /// # Examples
 111         ///
 112         /// Basic usage:
 113         ///
 114         /// ```
 115         #[doc = concat!("let n = -1", stringify!($SelfT), ";")]
 116         ///
 117         /// assert_eq!(n.leading_zeros(), 0);
 118         /// ```
 119         #[stable(feature = "rust1", since = "1.0.0")]
 120         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
 121         #[must_use = "this returns the result of the operation, \
 122                       without modifying the original"]
 123         #[inline(always)]
 124         pub const fn leading_zeros(self) -> u32 {
 125             (self as $UnsignedT).leading_zeros()
 126         }
 127
 128         /// Returns the number of trailing zeros in the binary representation of `self`.
 129         ///
 130         /// # Examples
 131         ///
 132         /// Basic usage:
 133         ///
 134         /// ```
 135         #[doc = concat!("let n = -4", stringify!($SelfT), ";")]
 136         ///
 137         /// assert_eq!(n.trailing_zeros(), 2);
 138         /// ```
 139         #[stable(feature = "rust1", since = "1.0.0")]
 140         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
 141         #[must_use = "this returns the result of the operation, \
 142                       without modifying the original"]
 143         #[inline(always)]
 144         pub const fn trailing_zeros(self) -> u32 {
 145             (self as $UnsignedT).trailing_zeros()
 146         }
 147
 148         /// Returns the number of leading ones in the binary representation of `self`.
 149         ///
 150         /// # Examples
 151         ///
 152         /// Basic usage:
 153         ///
 154         /// ```
 155         #[doc = concat!("let n = -1", stringify!($SelfT), ";")]
 156         ///
 157         #[doc = concat!("assert_eq!(n.leading_ones(), ", stringify!($BITS), ");")]
 158         /// ```
 159         #[stable(feature = "leading_trailing_ones", since = "1.46.0")]
 160         #[rustc_const_stable(feature = "leading_trailing_ones", since = "1.46.0")]
 161         #[must_use = "this returns the result of the operation, \
 162                       without modifying the original"]
 163         #[inline(always)]
 164         pub const fn leading_ones(self) -> u32 {
 165             (self as $UnsignedT).leading_ones()
 166         }
 167
 168         /// Returns the number of trailing ones in the binary representation of `self`.
 169         ///
 170         /// # Examples
 171         ///
 172         /// Basic usage:
 173         ///
 174         /// ```
 175         #[doc = concat!("let n = 3", stringify!($SelfT), ";")]
 176         ///
 177         /// assert_eq!(n.trailing_ones(), 2);
 178         /// ```
 179         #[stable(feature = "leading_trailing_ones", since = "1.46.0")]
 180         #[rustc_const_stable(feature = "leading_trailing_ones", since = "1.46.0")]
 181         #[must_use = "this returns the result of the operation, \
 182                       without modifying the original"]
 183         #[inline(always)]
 184         pub const fn trailing_ones(self) -> u32 {
 185             (self as $UnsignedT).trailing_ones()
 186         }
 187
 188         /// Shifts the bits to the left by a specified amount, `n`,
 189         /// wrapping the truncated bits to the end of the resulting integer.
 190         ///
 191         /// Please note this isn't the same operation as the `<<` shifting operator!
 192         ///
 193         /// # Examples
 194         ///
 195         /// Basic usage:
 196         ///
 197         /// ```
 198         #[doc = concat!("let n = ", $rot_op, stringify!($SelfT), ";")]
 199         #[doc = concat!("let m = ", $rot_result, ";")]
 200         ///
 201         #[doc = concat!("assert_eq!(n.rotate_left(", $rot, "), m);")]
 202         /// ```
 203         #[stable(feature = "rust1", since = "1.0.0")]
 204         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
 205         #[must_use = "this returns the result of the operation, \
 206                       without modifying the original"]
 207         #[inline(always)]
 208         pub const fn rotate_left(self, n: u32) -> Self {
 209             (self as $UnsignedT).rotate_left(n) as Self
 210         }
 211
 212         /// Shifts the bits to the right by a specified amount, `n`,
 213         /// wrapping the truncated bits to the beginning of the resulting
 214         /// integer.
 215         ///
 216         /// Please note this isn't the same operation as the `>>` shifting operator!
 217         ///
 218         /// # Examples
 219         ///
 220         /// Basic usage:
 221         ///
 222         /// ```
 223         #[doc = concat!("let n = ", $rot_result, stringify!($SelfT), ";")]
 224         #[doc = concat!("let m = ", $rot_op, ";")]
 225         ///
 226         #[doc = concat!("assert_eq!(n.rotate_right(", $rot, "), m);")]
 227         /// ```
 228         #[stable(feature = "rust1", since = "1.0.0")]
 229         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
 230         #[must_use = "this returns the result of the operation, \
 231                       without modifying the original"]
 232         #[inline(always)]
 233         pub const fn rotate_right(self, n: u32) -> Self {
 234             (self as $UnsignedT).rotate_right(n) as Self
 235         }
 236
 237         /// Reverses the byte order of the integer.
 238         ///
 239         /// # Examples
 240         ///
 241         /// Basic usage:
 242         ///
 243         /// ```
 244         #[doc = concat!("let n = ", $swap_op, stringify!($SelfT), ";")]
 245         ///
 246         /// let m = n.swap_bytes();
 247         ///
 248         #[doc = concat!("assert_eq!(m, ", $swapped, ");")]
 249         /// ```
 250         #[stable(feature = "rust1", since = "1.0.0")]
 251         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
 252         #[must_use = "this returns the result of the operation, \
 253                       without modifying the original"]
 254         #[inline(always)]
 255         pub const fn swap_bytes(self) -> Self {
 256             (self as $UnsignedT).swap_bytes() as Self
 257         }
 258
 259         /// Reverses the order of bits in the integer. The least significant bit becomes the most significant bit,
 260         ///                 second least-significant bit becomes second most-significant bit, etc.
 261         ///
 262         /// # Examples
 263         ///
 264         /// Basic usage:
 265         ///
 266         /// ```
 267         #[doc = concat!("let n = ", $swap_op, stringify!($SelfT), ";")]
 268         /// let m = n.reverse_bits();
 269         ///
 270         #[doc = concat!("assert_eq!(m, ", $reversed, ");")]
 271         #[doc = concat!("assert_eq!(0, 0", stringify!($SelfT), ".reverse_bits());")]
 272         /// ```
 273         #[stable(feature = "reverse_bits", since = "1.37.0")]
 274         #[rustc_const_stable(feature = "reverse_bits", since = "1.37.0")]
 275         #[must_use = "this returns the result of the operation, \
 276                       without modifying the original"]
 277         #[inline(always)]
 278         pub const fn reverse_bits(self) -> Self {
 279             (self as $UnsignedT).reverse_bits() as Self
 280         }
 281
 282         /// Converts an integer from big endian to the target's endianness.
 283         ///
 284         /// On big endian this is a no-op. On little endian the bytes are swapped.
 285         ///
 286         /// # Examples
 287         ///
 288         /// Basic usage:
 289         ///
 290         /// ```
 291         #[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")]
 292         ///
 293         /// if cfg!(target_endian = "big") {
 294         #[doc = concat!("    assert_eq!(", stringify!($SelfT), "::from_be(n), n)")]
 295         /// } else {
 296         #[doc = concat!("    assert_eq!(", stringify!($SelfT), "::from_be(n), n.swap_bytes())")]
 297         /// }
 298         /// ```
 299         #[stable(feature = "rust1", since = "1.0.0")]
 300         #[rustc_const_stable(feature = "const_int_conversions", since = "1.32.0")]
 301         #[must_use]
 302         #[inline]
 303         pub const fn from_be(x: Self) -> Self {
 304             #[cfg(target_endian = "big")]
 305             {
 306                 x
 307             }
 308             #[cfg(not(target_endian = "big"))]
 309             {
 310                 x.swap_bytes()
 311             }
 312         }
 313
 314         /// Converts an integer from little endian to the target's endianness.
 315         ///
 316         /// On little endian this is a no-op. On big endian the bytes are swapped.
 317         ///
 318         /// # Examples
 319         ///
 320         /// Basic usage:
 321         ///
 322         /// ```
 323         #[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")]
 324         ///
 325         /// if cfg!(target_endian = "little") {
 326         #[doc = concat!("    assert_eq!(", stringify!($SelfT), "::from_le(n), n)")]
 327         /// } else {
 328         #[doc = concat!("    assert_eq!(", stringify!($SelfT), "::from_le(n), n.swap_bytes())")]
 329         /// }
 330         /// ```
 331         #[stable(feature = "rust1", since = "1.0.0")]
 332         #[rustc_const_stable(feature = "const_int_conversions", since = "1.32.0")]
 333         #[must_use]
 334         #[inline]
 335         pub const fn from_le(x: Self) -> Self {
 336             #[cfg(target_endian = "little")]
 337             {
 338                 x
 339             }
 340             #[cfg(not(target_endian = "little"))]
 341             {
 342                 x.swap_bytes()
 343             }
 344         }
 345
 346         /// Converts `self` to big endian from the target's endianness.
 347         ///
 348         /// On big endian this is a no-op. On little endian the bytes are swapped.
 349         ///
 350         /// # Examples
 351         ///
 352         /// Basic usage:
 353         ///
 354         /// ```
 355         #[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")]
 356         ///
 357         /// if cfg!(target_endian = "big") {
 358         ///     assert_eq!(n.to_be(), n)
 359         /// } else {
 360         ///     assert_eq!(n.to_be(), n.swap_bytes())
 361         /// }
 362         /// ```
 363         #[stable(feature = "rust1", since = "1.0.0")]
 364         #[rustc_const_stable(feature = "const_int_conversions", since = "1.32.0")]
 365         #[must_use = "this returns the result of the operation, \
 366                       without modifying the original"]
 367         #[inline]
 368         pub const fn to_be(self) -> Self { // or not to be?
 369             #[cfg(target_endian = "big")]
 370             {
 371                 self
 372             }
 373             #[cfg(not(target_endian = "big"))]
 374             {
 375                 self.swap_bytes()
 376             }
 377         }
 378
 379         /// Converts `self` to little endian from the target's endianness.
 380         ///
 381         /// On little endian this is a no-op. On big endian the bytes are swapped.
 382         ///
 383         /// # Examples
 384         ///
 385         /// Basic usage:
 386         ///
 387         /// ```
 388         #[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")]
 389         ///
 390         /// if cfg!(target_endian = "little") {
 391         ///     assert_eq!(n.to_le(), n)
 392         /// } else {
 393         ///     assert_eq!(n.to_le(), n.swap_bytes())
 394         /// }
 395         /// ```
 396         #[stable(feature = "rust1", since = "1.0.0")]
 397         #[rustc_const_stable(feature = "const_int_conversions", since = "1.32.0")]
 398         #[must_use = "this returns the result of the operation, \
 399                       without modifying the original"]
 400         #[inline]
 401         pub const fn to_le(self) -> Self {
 402             #[cfg(target_endian = "little")]
 403             {
 404                 self
 405             }
 406             #[cfg(not(target_endian = "little"))]
 407             {
 408                 self.swap_bytes()
 409             }
 410         }
 411
 412         /// Checked integer addition. Computes `self + rhs`, returning `None`
 413         /// if overflow occurred.
 414         ///
 415         /// # Examples
 416         ///
 417         /// Basic usage:
 418         ///
 419         /// ```
 420         #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).checked_add(1), Some(", stringify!($SelfT), "::MAX - 1));")]
 421         #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).checked_add(3), None);")]
 422         /// ```
 423         #[stable(feature = "rust1", since = "1.0.0")]
 424         #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
 425         #[must_use = "this returns the result of the operation, \
 426                       without modifying the original"]
 427         #[inline]
 428         pub const fn checked_add(self, rhs: Self) -> Option<Self> {
 429             let (a, b) = self.overflowing_add(rhs);
 430             if unlikely!(b) {None} else {Some(a)}
 431         }
 432
 433         /// Unchecked integer addition. Computes `self + rhs`, assuming overflow
 434         /// cannot occur.
 435         ///
 436         /// # Safety
 437         ///
 438         /// This results in undefined behavior when
 439         #[doc = concat!("`self + rhs > ", stringify!($SelfT), "::MAX` or `self + rhs < ", stringify!($SelfT), "::MIN`,")]
 440         /// i.e. when [`checked_add`] would return `None`.
 441         ///
 442         #[doc = concat!("[`checked_add`]: ", stringify!($SelfT), "::checked_add")]
 443         #[unstable(
 444             feature = "unchecked_math",
 445             reason = "niche optimization path",
 446             issue = "85122",
 447         )]
 448         #[must_use = "this returns the result of the operation, \
 449                       without modifying the original"]
 450         #[rustc_const_unstable(feature = "const_inherent_unchecked_arith", issue = "85122")]
 451         #[inline(always)]
 452         #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
 453         pub const unsafe fn unchecked_add(self, rhs: Self) -> Self {
 454             // SAFETY: the caller must uphold the safety contract for
 455             // `unchecked_add`.
 456             unsafe { intrinsics::unchecked_add(self, rhs) }
 457         }
 458
 459         /// Checked addition with an unsigned integer. Computes `self + rhs`,
 460         /// returning `None` if overflow occurred.
 461         ///
 462         /// # Examples
 463         ///
 464         /// Basic usage:
 465         ///
 466         /// ```
 467         #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".checked_add_unsigned(2), Some(3));")]
 468         #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).checked_add_unsigned(3), None);")]
 469         /// ```
 470         #[stable(feature = "mixed_integer_ops", since = "CURRENT_RUSTC_VERSION")]
 471         #[rustc_const_stable(feature = "mixed_integer_ops", since = "CURRENT_RUSTC_VERSION")]
 472         #[must_use = "this returns the result of the operation, \
 473                       without modifying the original"]
 474         #[inline]
 475         pub const fn checked_add_unsigned(self, rhs: $UnsignedT) -> Option<Self> {
 476             let (a, b) = self.overflowing_add_unsigned(rhs);
 477             if unlikely!(b) {None} else {Some(a)}
 478         }
 479
 480         /// Checked integer subtraction. Computes `self - rhs`, returning `None` if
 481         /// overflow occurred.
 482         ///
 483         /// # Examples
 484         ///
 485         /// Basic usage:
 486         ///
 487         /// ```
 488         #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 2).checked_sub(1), Some(", stringify!($SelfT), "::MIN + 1));")]
 489         #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 2).checked_sub(3), None);")]
 490         /// ```
 491         #[stable(feature = "rust1", since = "1.0.0")]
 492         #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
 493         #[must_use = "this returns the result of the operation, \
 494                       without modifying the original"]
 495         #[inline]
 496         pub const fn checked_sub(self, rhs: Self) -> Option<Self> {
 497             let (a, b) = self.overflowing_sub(rhs);
 498             if unlikely!(b) {None} else {Some(a)}
 499         }
 500
 501         /// Unchecked integer subtraction. Computes `self - rhs`, assuming overflow
 502         /// cannot occur.
 503         ///
 504         /// # Safety
 505         ///
 506         /// This results in undefined behavior when
 507         #[doc = concat!("`self - rhs > ", stringify!($SelfT), "::MAX` or `self - rhs < ", stringify!($SelfT), "::MIN`,")]
 508         /// i.e. when [`checked_sub`] would return `None`.
 509         ///
 510         #[doc = concat!("[`checked_sub`]: ", stringify!($SelfT), "::checked_sub")]
 511         #[unstable(
 512             feature = "unchecked_math",
 513             reason = "niche optimization path",
 514             issue = "85122",
 515         )]
 516         #[must_use = "this returns the result of the operation, \
 517                       without modifying the original"]
 518         #[rustc_const_unstable(feature = "const_inherent_unchecked_arith", issue = "85122")]
 519         #[inline(always)]
 520         #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
 521         pub const unsafe fn unchecked_sub(self, rhs: Self) -> Self {
 522             // SAFETY: the caller must uphold the safety contract for
 523             // `unchecked_sub`.
 524             unsafe { intrinsics::unchecked_sub(self, rhs) }
 525         }
 526
 527         /// Checked subtraction with an unsigned integer. Computes `self - rhs`,
 528         /// returning `None` if overflow occurred.
 529         ///
 530         /// # Examples
 531         ///
 532         /// Basic usage:
 533         ///
 534         /// ```
 535         #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".checked_sub_unsigned(2), Some(-1));")]
 536         #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 2).checked_sub_unsigned(3), None);")]
 537         /// ```
 538         #[stable(feature = "mixed_integer_ops", since = "CURRENT_RUSTC_VERSION")]
 539         #[rustc_const_stable(feature = "mixed_integer_ops", since = "CURRENT_RUSTC_VERSION")]
 540         #[must_use = "this returns the result of the operation, \
 541                       without modifying the original"]
 542         #[inline]
 543         pub const fn checked_sub_unsigned(self, rhs: $UnsignedT) -> Option<Self> {
 544             let (a, b) = self.overflowing_sub_unsigned(rhs);
 545             if unlikely!(b) {None} else {Some(a)}
 546         }
 547
 548         /// Checked integer multiplication. Computes `self * rhs`, returning `None` if
 549         /// overflow occurred.
 550         ///
 551         /// # Examples
 552         ///
 553         /// Basic usage:
 554         ///
 555         /// ```
 556         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_mul(1), Some(", stringify!($SelfT), "::MAX));")]
 557         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_mul(2), None);")]
 558         /// ```
 559         #[stable(feature = "rust1", since = "1.0.0")]
 560         #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
 561         #[must_use = "this returns the result of the operation, \
 562                       without modifying the original"]
 563         #[inline]
 564         pub const fn checked_mul(self, rhs: Self) -> Option<Self> {
 565             let (a, b) = self.overflowing_mul(rhs);
 566             if unlikely!(b) {None} else {Some(a)}
 567         }
 568
 569         /// Unchecked integer multiplication. Computes `self * rhs`, assuming overflow
 570         /// cannot occur.
 571         ///
 572         /// # Safety
 573         ///
 574         /// This results in undefined behavior when
 575         #[doc = concat!("`self * rhs > ", stringify!($SelfT), "::MAX` or `self * rhs < ", stringify!($SelfT), "::MIN`,")]
 576         /// i.e. when [`checked_mul`] would return `None`.
 577         ///
 578         #[doc = concat!("[`checked_mul`]: ", stringify!($SelfT), "::checked_mul")]
 579         #[unstable(
 580             feature = "unchecked_math",
 581             reason = "niche optimization path",
 582             issue = "85122",
 583         )]
 584         #[must_use = "this returns the result of the operation, \
 585                       without modifying the original"]
 586         #[rustc_const_unstable(feature = "const_inherent_unchecked_arith", issue = "85122")]
 587         #[inline(always)]
 588         #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
 589         pub const unsafe fn unchecked_mul(self, rhs: Self) -> Self {
 590             // SAFETY: the caller must uphold the safety contract for
 591             // `unchecked_mul`.
 592             unsafe { intrinsics::unchecked_mul(self, rhs) }
 593         }
 594
 595         /// Checked integer division. Computes `self / rhs`, returning `None` if `rhs == 0`
 596         /// or the division results in overflow.
 597         ///
 598         /// # Examples
 599         ///
 600         /// Basic usage:
 601         ///
 602         /// ```
 603         #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 1).checked_div(-1), Some(", stringify!($Max), "));")]
 604         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_div(-1), None);")]
 605         #[doc = concat!("assert_eq!((1", stringify!($SelfT), ").checked_div(0), None);")]
 606         /// ```
 607         #[stable(feature = "rust1", since = "1.0.0")]
 608         #[rustc_const_stable(feature = "const_checked_int_div", since = "1.52.0")]
 609         #[must_use = "this returns the result of the operation, \
 610                       without modifying the original"]
 611         #[inline]
 612         pub const fn checked_div(self, rhs: Self) -> Option<Self> {
 613             if unlikely!(rhs == 0 || ((self == Self::MIN) && (rhs == -1))) {
 614                 None
 615             } else {
 616                 // SAFETY: div by zero and by INT_MIN have been checked above
 617                 Some(unsafe { intrinsics::unchecked_div(self, rhs) })
 618             }
 619         }
 620
 621         /// Checked Euclidean division. Computes `self.div_euclid(rhs)`,
 622         /// returning `None` if `rhs == 0` or the division results in overflow.
 623         ///
 624         /// # Examples
 625         ///
 626         /// Basic usage:
 627         ///
 628         /// ```
 629         #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 1).checked_div_euclid(-1), Some(", stringify!($Max), "));")]
 630         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_div_euclid(-1), None);")]
 631         #[doc = concat!("assert_eq!((1", stringify!($SelfT), ").checked_div_euclid(0), None);")]
 632         /// ```
 633         #[stable(feature = "euclidean_division", since = "1.38.0")]
 634         #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
 635         #[must_use = "this returns the result of the operation, \
 636                       without modifying the original"]
 637         #[inline]
 638         pub const fn checked_div_euclid(self, rhs: Self) -> Option<Self> {
 639             // Using `&` helps LLVM see that it is the same check made in division.
 640             if unlikely!(rhs == 0 || ((self == Self::MIN) & (rhs == -1))) {
 641                 None
 642             } else {
 643                 Some(self.div_euclid(rhs))
 644             }
 645         }
 646
 647         /// Checked integer remainder. Computes `self % rhs`, returning `None` if
 648         /// `rhs == 0` or the division results in overflow.
 649         ///
 650         /// # Examples
 651         ///
 652         /// Basic usage:
 653         ///
 654         /// ```
 655         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem(2), Some(1));")]
 656         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem(0), None);")]
 657         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_rem(-1), None);")]
 658         /// ```
 659         #[stable(feature = "wrapping", since = "1.7.0")]
 660         #[rustc_const_stable(feature = "const_checked_int_div", since = "1.52.0")]
 661         #[must_use = "this returns the result of the operation, \
 662                       without modifying the original"]
 663         #[inline]
 664         pub const fn checked_rem(self, rhs: Self) -> Option<Self> {
 665             if unlikely!(rhs == 0 || ((self == Self::MIN) && (rhs == -1))) {
 666                 None
 667             } else {
 668                 // SAFETY: div by zero and by INT_MIN have been checked above
 669                 Some(unsafe { intrinsics::unchecked_rem(self, rhs) })
 670             }
 671         }
 672
 673         /// Checked Euclidean remainder. Computes `self.rem_euclid(rhs)`, returning `None`
 674         /// if `rhs == 0` or the division results in overflow.
 675         ///
 676         /// # Examples
 677         ///
 678         /// Basic usage:
 679         ///
 680         /// ```
 681         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem_euclid(2), Some(1));")]
 682         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem_euclid(0), None);")]
 683         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_rem_euclid(-1), None);")]
 684         /// ```
 685         #[stable(feature = "euclidean_division", since = "1.38.0")]
 686         #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
 687         #[must_use = "this returns the result of the operation, \
 688                       without modifying the original"]
 689         #[inline]
 690         pub const fn checked_rem_euclid(self, rhs: Self) -> Option<Self> {
 691             // Using `&` helps LLVM see that it is the same check made in division.
 692             if unlikely!(rhs == 0 || ((self == Self::MIN) & (rhs == -1))) {
 693                 None
 694             } else {
 695                 Some(self.rem_euclid(rhs))
 696             }
 697         }
 698
 699         /// Checked negation. Computes `-self`, returning `None` if `self == MIN`.
 700         ///
 701         /// # Examples
 702         ///
 703         /// Basic usage:
 704         ///
 705         /// ```
 706         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_neg(), Some(-5));")]
 707         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_neg(), None);")]
 708         /// ```
 709         #[stable(feature = "wrapping", since = "1.7.0")]
 710         #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
 711         #[must_use = "this returns the result of the operation, \
 712                       without modifying the original"]
 713         #[inline]
 714         pub const fn checked_neg(self) -> Option<Self> {
 715             let (a, b) = self.overflowing_neg();
 716             if unlikely!(b) {None} else {Some(a)}
 717         }
 718
 719         /// Checked shift left. Computes `self << rhs`, returning `None` if `rhs` is larger
 720         /// than or equal to the number of bits in `self`.
 721         ///
 722         /// # Examples
 723         ///
 724         /// Basic usage:
 725         ///
 726         /// ```
 727         #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".checked_shl(4), Some(0x10));")]
 728         #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".checked_shl(129), None);")]
 729         /// ```
 730         #[stable(feature = "wrapping", since = "1.7.0")]
 731         #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
 732         #[must_use = "this returns the result of the operation, \
 733                       without modifying the original"]
 734         #[inline]
 735         pub const fn checked_shl(self, rhs: u32) -> Option<Self> {
 736             let (a, b) = self.overflowing_shl(rhs);
 737             if unlikely!(b) {None} else {Some(a)}
 738         }
 739
 740         /// Unchecked shift left. Computes `self << rhs`, assuming that
 741         /// `rhs` is less than the number of bits in `self`.
 742         ///
 743         /// # Safety
 744         ///
 745         /// This results in undefined behavior if `rhs` is larger than
 746         /// or equal to the number of bits in `self`,
 747         /// i.e. when [`checked_shl`] would return `None`.
 748         ///
 749         #[doc = concat!("[`checked_shl`]: ", stringify!($SelfT), "::checked_shl")]
 750         #[unstable(
 751             feature = "unchecked_math",
 752             reason = "niche optimization path",
 753             issue = "85122",
 754         )]
 755         #[must_use = "this returns the result of the operation, \
 756                       without modifying the original"]
 757         #[rustc_const_unstable(feature = "const_inherent_unchecked_arith", issue = "85122")]
 758         #[inline(always)]
 759         #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
 760         pub const unsafe fn unchecked_shl(self, rhs: Self) -> Self {
 761             // SAFETY: the caller must uphold the safety contract for
 762             // `unchecked_shl`.
 763             unsafe { intrinsics::unchecked_shl(self, rhs) }
 764         }
 765
 766         /// Checked shift right. Computes `self >> rhs`, returning `None` if `rhs` is
 767         /// larger than or equal to the number of bits in `self`.
 768         ///
 769         /// # Examples
 770         ///
 771         /// Basic usage:
 772         ///
 773         /// ```
 774         #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".checked_shr(4), Some(0x1));")]
 775         #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".checked_shr(128), None);")]
 776         /// ```
 777         #[stable(feature = "wrapping", since = "1.7.0")]
 778         #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
 779         #[must_use = "this returns the result of the operation, \
 780                       without modifying the original"]
 781         #[inline]
 782         pub const fn checked_shr(self, rhs: u32) -> Option<Self> {
 783             let (a, b) = self.overflowing_shr(rhs);
 784             if unlikely!(b) {None} else {Some(a)}
 785         }
 786
 787         /// Unchecked shift right. Computes `self >> rhs`, assuming that
 788         /// `rhs` is less than the number of bits in `self`.
 789         ///
 790         /// # Safety
 791         ///
 792         /// This results in undefined behavior if `rhs` is larger than
 793         /// or equal to the number of bits in `self`,
 794         /// i.e. when [`checked_shr`] would return `None`.
 795         ///
 796         #[doc = concat!("[`checked_shr`]: ", stringify!($SelfT), "::checked_shr")]
 797         #[unstable(
 798             feature = "unchecked_math",
 799             reason = "niche optimization path",
 800             issue = "85122",
 801         )]
 802         #[must_use = "this returns the result of the operation, \
 803                       without modifying the original"]
 804         #[rustc_const_unstable(feature = "const_inherent_unchecked_arith", issue = "85122")]
 805         #[inline(always)]
 806         #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
 807         pub const unsafe fn unchecked_shr(self, rhs: Self) -> Self {
 808             // SAFETY: the caller must uphold the safety contract for
 809             // `unchecked_shr`.
 810             unsafe { intrinsics::unchecked_shr(self, rhs) }
 811         }
 812
 813         /// Checked absolute value. Computes `self.abs()`, returning `None` if
 814         /// `self == MIN`.
 815         ///
 816         /// # Examples
 817         ///
 818         /// Basic usage:
 819         ///
 820         /// ```
 821         #[doc = concat!("assert_eq!((-5", stringify!($SelfT), ").checked_abs(), Some(5));")]
 822         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_abs(), None);")]
 823         /// ```
 824         #[stable(feature = "no_panic_abs", since = "1.13.0")]
 825         #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
 826         #[must_use = "this returns the result of the operation, \
 827                       without modifying the original"]
 828         #[inline]
 829         pub const fn checked_abs(self) -> Option<Self> {
 830             if self.is_negative() {
 831                 self.checked_neg()
 832             } else {
 833                 Some(self)
 834             }
 835         }
 836
 837         /// Checked exponentiation. Computes `self.pow(exp)`, returning `None` if
 838         /// overflow occurred.
 839         ///
 840         /// # Examples
 841         ///
 842         /// Basic usage:
 843         ///
 844         /// ```
 845         #[doc = concat!("assert_eq!(8", stringify!($SelfT), ".checked_pow(2), Some(64));")]
 846         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_pow(2), None);")]
 847         /// ```
 848
 849         #[stable(feature = "no_panic_pow", since = "1.34.0")]
 850         #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
 851         #[must_use = "this returns the result of the operation, \
 852                       without modifying the original"]
 853         #[inline]
 854         pub const fn checked_pow(self, mut exp: u32) -> Option<Self> {
 855             if exp == 0 {
 856                 return Some(1);
 857             }
 858             let mut base = self;
 859             let mut acc: Self = 1;
 860
 861             while exp > 1 {
 862                 if (exp & 1) == 1 {
 863                     acc = try_opt!(acc.checked_mul(base));
 864                 }
 865                 exp /= 2;
 866                 base = try_opt!(base.checked_mul(base));
 867             }
 868             // since exp!=0, finally the exp must be 1.
 869             // Deal with the final bit of the exponent separately, since
 870             // squaring the base afterwards is not necessary and may cause a
 871             // needless overflow.
 872             acc.checked_mul(base)
 873         }
 874
 875         /// Saturating integer addition. Computes `self + rhs`, saturating at the numeric
 876         /// bounds instead of overflowing.
 877         ///
 878         /// # Examples
 879         ///
 880         /// Basic usage:
 881         ///
 882         /// ```
 883         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_add(1), 101);")]
 884         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_add(100), ", stringify!($SelfT), "::MAX);")]
 885         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_add(-1), ", stringify!($SelfT), "::MIN);")]
 886         /// ```
 887
 888         #[stable(feature = "rust1", since = "1.0.0")]
 889         #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")]
 890         #[must_use = "this returns the result of the operation, \
 891                       without modifying the original"]
 892         #[inline(always)]
 893         pub const fn saturating_add(self, rhs: Self) -> Self {
 894             intrinsics::saturating_add(self, rhs)
 895         }
 896
 897         /// Saturating addition with an unsigned integer. Computes `self + rhs`,
 898         /// saturating at the numeric bounds instead of overflowing.
 899         ///
 900         /// # Examples
 901         ///
 902         /// Basic usage:
 903         ///
 904         /// ```
 905         #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".saturating_add_unsigned(2), 3);")]
 906         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_add_unsigned(100), ", stringify!($SelfT), "::MAX);")]
 907         /// ```
 908         #[stable(feature = "mixed_integer_ops", since = "CURRENT_RUSTC_VERSION")]
 909         #[rustc_const_stable(feature = "mixed_integer_ops", since = "CURRENT_RUSTC_VERSION")]
 910         #[must_use = "this returns the result of the operation, \
 911                       without modifying the original"]
 912         #[inline]
 913         pub const fn saturating_add_unsigned(self, rhs: $UnsignedT) -> Self {
 914             // Overflow can only happen at the upper bound
 915             // We cannot use `unwrap_or` here because it is not `const`
 916             match self.checked_add_unsigned(rhs) {
 917                 Some(x) => x,
 918                 None => Self::MAX,
 919             }
 920         }
 921
 922         /// Saturating integer subtraction. Computes `self - rhs`, saturating at the
 923         /// numeric bounds instead of overflowing.
 924         ///
 925         /// # Examples
 926         ///
 927         /// Basic usage:
 928         ///
 929         /// ```
 930         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_sub(127), -27);")]
 931         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_sub(100), ", stringify!($SelfT), "::MIN);")]
 932         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_sub(-1), ", stringify!($SelfT), "::MAX);")]
 933         /// ```
 934         #[stable(feature = "rust1", since = "1.0.0")]
 935         #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")]
 936         #[must_use = "this returns the result of the operation, \
 937                       without modifying the original"]
 938         #[inline(always)]
 939         pub const fn saturating_sub(self, rhs: Self) -> Self {
 940             intrinsics::saturating_sub(self, rhs)
 941         }
 942
 943         /// Saturating subtraction with an unsigned integer. Computes `self - rhs`,
 944         /// saturating at the numeric bounds instead of overflowing.
 945         ///
 946         /// # Examples
 947         ///
 948         /// Basic usage:
 949         ///
 950         /// ```
 951         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_sub_unsigned(127), -27);")]
 952         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_sub_unsigned(100), ", stringify!($SelfT), "::MIN);")]
 953         /// ```
 954         #[stable(feature = "mixed_integer_ops", since = "CURRENT_RUSTC_VERSION")]
 955         #[rustc_const_stable(feature = "mixed_integer_ops", since = "CURRENT_RUSTC_VERSION")]
 956         #[must_use = "this returns the result of the operation, \
 957                       without modifying the original"]
 958         #[inline]
 959         pub const fn saturating_sub_unsigned(self, rhs: $UnsignedT) -> Self {
 960             // Overflow can only happen at the lower bound
 961             // We cannot use `unwrap_or` here because it is not `const`
 962             match self.checked_sub_unsigned(rhs) {
 963                 Some(x) => x,
 964                 None => Self::MIN,
 965             }
 966         }
 967
 968         /// Saturating integer negation. Computes `-self`, returning `MAX` if `self == MIN`
 969         /// instead of overflowing.
 970         ///
 971         /// # Examples
 972         ///
 973         /// Basic usage:
 974         ///
 975         /// ```
 976         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_neg(), -100);")]
 977         #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").saturating_neg(), 100);")]
 978         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_neg(), ", stringify!($SelfT), "::MAX);")]
 979         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_neg(), ", stringify!($SelfT), "::MIN + 1);")]
 980         /// ```
 981
 982         #[stable(feature = "saturating_neg", since = "1.45.0")]
 983         #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")]
 984         #[must_use = "this returns the result of the operation, \
 985                       without modifying the original"]
 986         #[inline(always)]
 987         pub const fn saturating_neg(self) -> Self {
 988             intrinsics::saturating_sub(0, self)
 989         }
 990
 991         /// Saturating absolute value. Computes `self.abs()`, returning `MAX` if `self ==
 992         /// MIN` instead of overflowing.
 993         ///
 994         /// # Examples
 995         ///
 996         /// Basic usage:
 997         ///
 998         /// ```
 999         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_abs(), 100);")]
1000         #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").saturating_abs(), 100);")]
1001         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_abs(), ", stringify!($SelfT), "::MAX);")]
1002         #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 1).saturating_abs(), ", stringify!($SelfT), "::MAX);")]
1003         /// ```
1004
1005         #[stable(feature = "saturating_neg", since = "1.45.0")]
1006         #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")]
1007         #[must_use = "this returns the result of the operation, \
1008                       without modifying the original"]
1009         #[inline]
1010         pub const fn saturating_abs(self) -> Self {
1011             if self.is_negative() {
1012                 self.saturating_neg()
1013             } else {
1014                 self
1015             }
1016         }
1017
1018         /// Saturating integer multiplication. Computes `self * rhs`, saturating at the
1019         /// numeric bounds instead of overflowing.
1020         ///
1021         /// # Examples
1022         ///
1023         /// Basic usage:
1024         ///
1025         /// ```
1026         #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".saturating_mul(12), 120);")]
1027         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_mul(10), ", stringify!($SelfT), "::MAX);")]
1028         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_mul(10), ", stringify!($SelfT), "::MIN);")]
1029         /// ```
1030         #[stable(feature = "wrapping", since = "1.7.0")]
1031         #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")]
1032         #[must_use = "this returns the result of the operation, \
1033                       without modifying the original"]
1034         #[inline]
1035         pub const fn saturating_mul(self, rhs: Self) -> Self {
1036             match self.checked_mul(rhs) {
1037                 Some(x) => x,
1038                 None => if (self < 0) == (rhs < 0) {
1039                     Self::MAX
1040                 } else {
1041                     Self::MIN
1042                 }
1043             }
1044         }
1045
1046         /// Saturating integer division. Computes `self / rhs`, saturating at the
1047         /// numeric bounds instead of overflowing.
1048         ///
1049         /// # Examples
1050         ///
1051         /// Basic usage:
1052         ///
1053         /// ```
1054         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".saturating_div(2), 2);")]
1055         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_div(-1), ", stringify!($SelfT), "::MIN + 1);")]
1056         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_div(-1), ", stringify!($SelfT), "::MAX);")]
1057         ///
1058         /// ```
1059         ///
1060         /// ```should_panic
1061         #[doc = concat!("let _ = 1", stringify!($SelfT), ".saturating_div(0);")]
1062         ///
1063         /// ```
1064         #[stable(feature = "saturating_div", since = "1.58.0")]
1065         #[rustc_const_stable(feature = "saturating_div", since = "1.58.0")]
1066         #[must_use = "this returns the result of the operation, \
1067                       without modifying the original"]
1068         #[inline]
1069         pub const fn saturating_div(self, rhs: Self) -> Self {
1070             match self.overflowing_div(rhs) {
1071                 (result, false) => result,
1072                 (_result, true) => Self::MAX, // MIN / -1 is the only possible saturating overflow
1073             }
1074         }
1075
1076         /// Saturating integer exponentiation. Computes `self.pow(exp)`,
1077         /// saturating at the numeric bounds instead of overflowing.
1078         ///
1079         /// # Examples
1080         ///
1081         /// Basic usage:
1082         ///
1083         /// ```
1084         #[doc = concat!("assert_eq!((-4", stringify!($SelfT), ").saturating_pow(3), -64);")]
1085         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_pow(2), ", stringify!($SelfT), "::MAX);")]
1086         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_pow(3), ", stringify!($SelfT), "::MIN);")]
1087         /// ```
1088         #[stable(feature = "no_panic_pow", since = "1.34.0")]
1089         #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
1090         #[must_use = "this returns the result of the operation, \
1091                       without modifying the original"]
1092         #[inline]
1093         pub const fn saturating_pow(self, exp: u32) -> Self {
1094             match self.checked_pow(exp) {
1095                 Some(x) => x,
1096                 None if self < 0 && exp % 2 == 1 => Self::MIN,
1097                 None => Self::MAX,
1098             }
1099         }
1100
1101         /// Wrapping (modular) addition. Computes `self + rhs`, wrapping around at the
1102         /// boundary of the type.
1103         ///
1104         /// # Examples
1105         ///
1106         /// Basic usage:
1107         ///
1108         /// ```
1109         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_add(27), 127);")]
1110         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.wrapping_add(2), ", stringify!($SelfT), "::MIN + 1);")]
1111         /// ```
1112         #[stable(feature = "rust1", since = "1.0.0")]
1113         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1114         #[must_use = "this returns the result of the operation, \
1115                       without modifying the original"]
1116         #[inline(always)]
1117         pub const fn wrapping_add(self, rhs: Self) -> Self {
1118             intrinsics::wrapping_add(self, rhs)
1119         }
1120
1121         /// Wrapping (modular) addition with an unsigned integer. Computes
1122         /// `self + rhs`, wrapping around at the boundary of the type.
1123         ///
1124         /// # Examples
1125         ///
1126         /// Basic usage:
1127         ///
1128         /// ```
1129         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_add_unsigned(27), 127);")]
1130         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.wrapping_add_unsigned(2), ", stringify!($SelfT), "::MIN + 1);")]
1131         /// ```
1132         #[stable(feature = "mixed_integer_ops", since = "CURRENT_RUSTC_VERSION")]
1133         #[rustc_const_stable(feature = "mixed_integer_ops", since = "CURRENT_RUSTC_VERSION")]
1134         #[must_use = "this returns the result of the operation, \
1135                       without modifying the original"]
1136         #[inline(always)]
1137         pub const fn wrapping_add_unsigned(self, rhs: $UnsignedT) -> Self {
1138             self.wrapping_add(rhs as Self)
1139         }
1140
1141         /// Wrapping (modular) subtraction. Computes `self - rhs`, wrapping around at the
1142         /// boundary of the type.
1143         ///
1144         /// # Examples
1145         ///
1146         /// Basic usage:
1147         ///
1148         /// ```
1149         #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".wrapping_sub(127), -127);")]
1150         #[doc = concat!("assert_eq!((-2", stringify!($SelfT), ").wrapping_sub(", stringify!($SelfT), "::MAX), ", stringify!($SelfT), "::MAX);")]
1151         /// ```
1152         #[stable(feature = "rust1", since = "1.0.0")]
1153         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1154         #[must_use = "this returns the result of the operation, \
1155                       without modifying the original"]
1156         #[inline(always)]
1157         pub const fn wrapping_sub(self, rhs: Self) -> Self {
1158             intrinsics::wrapping_sub(self, rhs)
1159         }
1160
1161         /// Wrapping (modular) subtraction with an unsigned integer. Computes
1162         /// `self - rhs`, wrapping around at the boundary of the type.
1163         ///
1164         /// # Examples
1165         ///
1166         /// Basic usage:
1167         ///
1168         /// ```
1169         #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".wrapping_sub_unsigned(127), -127);")]
1170         #[doc = concat!("assert_eq!((-2", stringify!($SelfT), ").wrapping_sub_unsigned(", stringify!($UnsignedT), "::MAX), -1);")]
1171         /// ```
1172         #[stable(feature = "mixed_integer_ops", since = "CURRENT_RUSTC_VERSION")]
1173         #[rustc_const_stable(feature = "mixed_integer_ops", since = "CURRENT_RUSTC_VERSION")]
1174         #[must_use = "this returns the result of the operation, \
1175                       without modifying the original"]
1176         #[inline(always)]
1177         pub const fn wrapping_sub_unsigned(self, rhs: $UnsignedT) -> Self {
1178             self.wrapping_sub(rhs as Self)
1179         }
1180
1181         /// Wrapping (modular) multiplication. Computes `self * rhs`, wrapping around at
1182         /// the boundary of the type.
1183         ///
1184         /// # Examples
1185         ///
1186         /// Basic usage:
1187         ///
1188         /// ```
1189         #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".wrapping_mul(12), 120);")]
1190         /// assert_eq!(11i8.wrapping_mul(12), -124);
1191         /// ```
1192         #[stable(feature = "rust1", since = "1.0.0")]
1193         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1194         #[must_use = "this returns the result of the operation, \
1195                       without modifying the original"]
1196         #[inline(always)]
1197         pub const fn wrapping_mul(self, rhs: Self) -> Self {
1198             intrinsics::wrapping_mul(self, rhs)
1199         }
1200
1201         /// Wrapping (modular) division. Computes `self / rhs`, wrapping around at the
1202         /// boundary of the type.
1203         ///
1204         /// The only case where such wrapping can occur is when one divides `MIN / -1` on a signed type (where
1205         /// `MIN` is the negative minimal value for the type); this is equivalent to `-MIN`, a positive value
1206         /// that is too large to represent in the type. In such a case, this function returns `MIN` itself.
1207         ///
1208         /// # Panics
1209         ///
1210         /// This function will panic if `rhs` is 0.
1211         ///
1212         /// # Examples
1213         ///
1214         /// Basic usage:
1215         ///
1216         /// ```
1217         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_div(10), 10);")]
1218         /// assert_eq!((-128i8).wrapping_div(-1), -128);
1219         /// ```
1220         #[stable(feature = "num_wrapping", since = "1.2.0")]
1221         #[rustc_const_stable(feature = "const_wrapping_int_methods", since = "1.52.0")]
1222         #[must_use = "this returns the result of the operation, \
1223                       without modifying the original"]
1224         #[inline]
1225         pub const fn wrapping_div(self, rhs: Self) -> Self {
1226             self.overflowing_div(rhs).0
1227         }
1228
1229         /// Wrapping Euclidean division. Computes `self.div_euclid(rhs)`,
1230         /// wrapping around at the boundary of the type.
1231         ///
1232         /// Wrapping will only occur in `MIN / -1` on a signed type (where `MIN` is the negative minimal value
1233         /// for the type). This is equivalent to `-MIN`, a positive value that is too large to represent in the
1234         /// type. In this case, this method returns `MIN` itself.
1235         ///
1236         /// # Panics
1237         ///
1238         /// This function will panic if `rhs` is 0.
1239         ///
1240         /// # Examples
1241         ///
1242         /// Basic usage:
1243         ///
1244         /// ```
1245         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_div_euclid(10), 10);")]
1246         /// assert_eq!((-128i8).wrapping_div_euclid(-1), -128);
1247         /// ```
1248         #[stable(feature = "euclidean_division", since = "1.38.0")]
1249         #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
1250         #[must_use = "this returns the result of the operation, \
1251                       without modifying the original"]
1252         #[inline]
1253         pub const fn wrapping_div_euclid(self, rhs: Self) -> Self {
1254             self.overflowing_div_euclid(rhs).0
1255         }
1256
1257         /// Wrapping (modular) remainder. Computes `self % rhs`, wrapping around at the
1258         /// boundary of the type.
1259         ///
1260         /// Such wrap-around never actually occurs mathematically; implementation artifacts make `x % y`
1261         /// invalid for `MIN / -1` on a signed type (where `MIN` is the negative minimal value). In such a case,
1262         /// this function returns `0`.
1263         ///
1264         /// # Panics
1265         ///
1266         /// This function will panic if `rhs` is 0.
1267         ///
1268         /// # Examples
1269         ///
1270         /// Basic usage:
1271         ///
1272         /// ```
1273         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_rem(10), 0);")]
1274         /// assert_eq!((-128i8).wrapping_rem(-1), 0);
1275         /// ```
1276         #[stable(feature = "num_wrapping", since = "1.2.0")]
1277         #[rustc_const_stable(feature = "const_wrapping_int_methods", since = "1.52.0")]
1278         #[must_use = "this returns the result of the operation, \
1279                       without modifying the original"]
1280         #[inline]
1281         pub const fn wrapping_rem(self, rhs: Self) -> Self {
1282             self.overflowing_rem(rhs).0
1283         }
1284
1285         /// Wrapping Euclidean remainder. Computes `self.rem_euclid(rhs)`, wrapping around
1286         /// at the boundary of the type.
1287         ///
1288         /// Wrapping will only occur in `MIN % -1` on a signed type (where `MIN` is the negative minimal value
1289         /// for the type). In this case, this method returns 0.
1290         ///
1291         /// # Panics
1292         ///
1293         /// This function will panic if `rhs` is 0.
1294         ///
1295         /// # Examples
1296         ///
1297         /// Basic usage:
1298         ///
1299         /// ```
1300         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_rem_euclid(10), 0);")]
1301         /// assert_eq!((-128i8).wrapping_rem_euclid(-1), 0);
1302         /// ```
1303         #[stable(feature = "euclidean_division", since = "1.38.0")]
1304         #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
1305         #[must_use = "this returns the result of the operation, \
1306                       without modifying the original"]
1307         #[inline]
1308         pub const fn wrapping_rem_euclid(self, rhs: Self) -> Self {
1309             self.overflowing_rem_euclid(rhs).0
1310         }
1311
1312         /// Wrapping (modular) negation. Computes `-self`, wrapping around at the boundary
1313         /// of the type.
1314         ///
1315         /// The only case where such wrapping can occur is when one negates `MIN` on a signed type (where `MIN`
1316         /// is the negative minimal value for the type); this is a positive value that is too large to represent
1317         /// in the type. In such a case, this function returns `MIN` itself.
1318         ///
1319         /// # Examples
1320         ///
1321         /// Basic usage:
1322         ///
1323         /// ```
1324         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_neg(), -100);")]
1325         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.wrapping_neg(), ", stringify!($SelfT), "::MIN);")]
1326         /// ```
1327         #[stable(feature = "num_wrapping", since = "1.2.0")]
1328         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1329         #[must_use = "this returns the result of the operation, \
1330                       without modifying the original"]
1331         #[inline(always)]
1332         pub const fn wrapping_neg(self) -> Self {
1333             (0 as $SelfT).wrapping_sub(self)
1334         }
1335
1336         /// Panic-free bitwise shift-left; yields `self << mask(rhs)`, where `mask` removes
1337         /// any high-order bits of `rhs` that would cause the shift to exceed the bitwidth of the type.
1338         ///
1339         /// Note that this is *not* the same as a rotate-left; the RHS of a wrapping shift-left is restricted to
1340         /// the range of the type, rather than the bits shifted out of the LHS being returned to the other end.
1341         /// The primitive integer types all implement a [`rotate_left`](Self::rotate_left) function,
1342         /// which may be what you want instead.
1343         ///
1344         /// # Examples
1345         ///
1346         /// Basic usage:
1347         ///
1348         /// ```
1349         #[doc = concat!("assert_eq!((-1", stringify!($SelfT), ").wrapping_shl(7), -128);")]
1350         #[doc = concat!("assert_eq!((-1", stringify!($SelfT), ").wrapping_shl(128), -1);")]
1351         /// ```
1352         #[stable(feature = "num_wrapping", since = "1.2.0")]
1353         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1354         #[must_use = "this returns the result of the operation, \
1355                       without modifying the original"]
1356         #[inline(always)]
1357         pub const fn wrapping_shl(self, rhs: u32) -> Self {
1358             // SAFETY: the masking by the bitsize of the type ensures that we do not shift
1359             // out of bounds
1360             unsafe {
1361                 intrinsics::unchecked_shl(self, (rhs & ($BITS - 1)) as $SelfT)
1362             }
1363         }
1364
1365         /// Panic-free bitwise shift-right; yields `self >> mask(rhs)`, where `mask`
1366         /// removes any high-order bits of `rhs` that would cause the shift to exceed the bitwidth of the type.
1367         ///
1368         /// Note that this is *not* the same as a rotate-right; the RHS of a wrapping shift-right is restricted
1369         /// to the range of the type, rather than the bits shifted out of the LHS being returned to the other
1370         /// end. The primitive integer types all implement a [`rotate_right`](Self::rotate_right) function,
1371         /// which may be what you want instead.
1372         ///
1373         /// # Examples
1374         ///
1375         /// Basic usage:
1376         ///
1377         /// ```
1378         #[doc = concat!("assert_eq!((-128", stringify!($SelfT), ").wrapping_shr(7), -1);")]
1379         /// assert_eq!((-128i16).wrapping_shr(64), -128);
1380         /// ```
1381         #[stable(feature = "num_wrapping", since = "1.2.0")]
1382         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1383         #[must_use = "this returns the result of the operation, \
1384                       without modifying the original"]
1385         #[inline(always)]
1386         pub const fn wrapping_shr(self, rhs: u32) -> Self {
1387             // SAFETY: the masking by the bitsize of the type ensures that we do not shift
1388             // out of bounds
1389             unsafe {
1390                 intrinsics::unchecked_shr(self, (rhs & ($BITS - 1)) as $SelfT)
1391             }
1392         }
1393
1394         /// Wrapping (modular) absolute value. Computes `self.abs()`, wrapping around at
1395         /// the boundary of the type.
1396         ///
1397         /// The only case where such wrapping can occur is when one takes the absolute value of the negative
1398         /// minimal value for the type; this is a positive value that is too large to represent in the type. In
1399         /// such a case, this function returns `MIN` itself.
1400         ///
1401         /// # Examples
1402         ///
1403         /// Basic usage:
1404         ///
1405         /// ```
1406         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_abs(), 100);")]
1407         #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").wrapping_abs(), 100);")]
1408         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.wrapping_abs(), ", stringify!($SelfT), "::MIN);")]
1409         /// assert_eq!((-128i8).wrapping_abs() as u8, 128);
1410         /// ```
1411         #[stable(feature = "no_panic_abs", since = "1.13.0")]
1412         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1413         #[must_use = "this returns the result of the operation, \
1414                       without modifying the original"]
1415         #[allow(unused_attributes)]
1416         #[inline]
1417         pub const fn wrapping_abs(self) -> Self {
1418              if self.is_negative() {
1419                  self.wrapping_neg()
1420              } else {
1421                  self
1422              }
1423         }
1424
1425         /// Computes the absolute value of `self` without any wrapping
1426         /// or panicking.
1427         ///
1428         ///
1429         /// # Examples
1430         ///
1431         /// Basic usage:
1432         ///
1433         /// ```
1434         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".unsigned_abs(), 100", stringify!($UnsignedT), ");")]
1435         #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").unsigned_abs(), 100", stringify!($UnsignedT), ");")]
1436         /// assert_eq!((-128i8).unsigned_abs(), 128u8);
1437         /// ```
1438         #[stable(feature = "unsigned_abs", since = "1.51.0")]
1439         #[rustc_const_stable(feature = "unsigned_abs", since = "1.51.0")]
1440         #[must_use = "this returns the result of the operation, \
1441                       without modifying the original"]
1442         #[inline]
1443         pub const fn unsigned_abs(self) -> $UnsignedT {
1444              self.wrapping_abs() as $UnsignedT
1445         }
1446
1447         /// Wrapping (modular) exponentiation. Computes `self.pow(exp)`,
1448         /// wrapping around at the boundary of the type.
1449         ///
1450         /// # Examples
1451         ///
1452         /// Basic usage:
1453         ///
1454         /// ```
1455         #[doc = concat!("assert_eq!(3", stringify!($SelfT), ".wrapping_pow(4), 81);")]
1456         /// assert_eq!(3i8.wrapping_pow(5), -13);
1457         /// assert_eq!(3i8.wrapping_pow(6), -39);
1458         /// ```
1459         #[stable(feature = "no_panic_pow", since = "1.34.0")]
1460         #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
1461         #[must_use = "this returns the result of the operation, \
1462                       without modifying the original"]
1463         #[inline]
1464         pub const fn wrapping_pow(self, mut exp: u32) -> Self {
1465             if exp == 0 {
1466                 return 1;
1467             }
1468             let mut base = self;
1469             let mut acc: Self = 1;
1470
1471             while exp > 1 {
1472                 if (exp & 1) == 1 {
1473                     acc = acc.wrapping_mul(base);
1474                 }
1475                 exp /= 2;
1476                 base = base.wrapping_mul(base);
1477             }
1478
1479             // since exp!=0, finally the exp must be 1.
1480             // Deal with the final bit of the exponent separately, since
1481             // squaring the base afterwards is not necessary and may cause a
1482             // needless overflow.
1483             acc.wrapping_mul(base)
1484         }
1485
1486         /// Calculates `self` + `rhs`
1487         ///
1488         /// Returns a tuple of the addition along with a boolean indicating whether an arithmetic overflow would
1489         /// occur. If an overflow would have occurred then the wrapped value is returned.
1490         ///
1491         /// # Examples
1492         ///
1493         /// Basic usage:
1494         ///
1495         /// ```
1496         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_add(2), (7, false));")]
1497         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.overflowing_add(1), (", stringify!($SelfT), "::MIN, true));")]
1498         /// ```
1499         #[stable(feature = "wrapping", since = "1.7.0")]
1500         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1501         #[must_use = "this returns the result of the operation, \
1502                       without modifying the original"]
1503         #[inline(always)]
1504         pub const fn overflowing_add(self, rhs: Self) -> (Self, bool) {
1505             let (a, b) = intrinsics::add_with_overflow(self as $ActualT, rhs as $ActualT);
1506             (a as Self, b)
1507         }
1508
1509         /// Calculates `self + rhs + carry` without the ability to overflow.
1510         ///
1511         /// Performs "signed ternary addition" which takes in an extra bit to add, and may return an
1512         /// additional bit of overflow. This signed function is used only on the highest-ordered data,
1513         /// for which the signed overflow result indicates whether the big integer overflowed or not.
1514         ///
1515         /// # Examples
1516         ///
1517         /// Basic usage:
1518         ///
1519         /// ```
1520         /// #![feature(bigint_helper_methods)]
1521         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".carrying_add(2, false), (7, false));")]
1522         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".carrying_add(2, true), (8, false));")]
1523         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.carrying_add(1, false), (", stringify!($SelfT), "::MIN, true));")]
1524         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.carrying_add(0, true), (", stringify!($SelfT), "::MIN, true));")]
1525         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.carrying_add(1, true), (", stringify!($SelfT), "::MIN + 1, true));")]
1526         #[doc = concat!("assert_eq!(",
1527             stringify!($SelfT), "::MAX.carrying_add(", stringify!($SelfT), "::MAX, true), ",
1528             "(-1, true));"
1529         )]
1530         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.carrying_add(-1, true), (", stringify!($SelfT), "::MIN, false));")]
1531         #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".carrying_add(", stringify!($SelfT), "::MAX, true), (", stringify!($SelfT), "::MIN, true));")]
1532         /// ```
1533         ///
1534         /// If `carry` is false, this method is equivalent to [`overflowing_add`](Self::overflowing_add):
1535         ///
1536         /// ```
1537         /// #![feature(bigint_helper_methods)]
1538         #[doc = concat!("assert_eq!(5_", stringify!($SelfT), ".carrying_add(2, false), 5_", stringify!($SelfT), ".overflowing_add(2));")]
1539         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.carrying_add(1, false), ", stringify!($SelfT), "::MAX.overflowing_add(1));")]
1540         /// ```
1541         #[unstable(feature = "bigint_helper_methods", issue = "85532")]
1542         #[rustc_const_unstable(feature = "const_bigint_helper_methods", issue = "85532")]
1543         #[must_use = "this returns the result of the operation, \
1544                       without modifying the original"]
1545         #[inline]
1546         pub const fn carrying_add(self, rhs: Self, carry: bool) -> (Self, bool) {
1547             // note: longer-term this should be done via an intrinsic.
1548             // note: no intermediate overflow is required (https://github.com/rust-lang/rust/issues/85532#issuecomment-1032214946).
1549             let (a, b) = self.overflowing_add(rhs);
1550             let (c, d) = a.overflowing_add(carry as $SelfT);
1551             (c, b != d)
1552         }
1553
1554         /// Calculates `self` + `rhs` with an unsigned `rhs`
1555         ///
1556         /// Returns a tuple of the addition along with a boolean indicating
1557         /// whether an arithmetic overflow would occur. If an overflow would
1558         /// have occurred then the wrapped value is returned.
1559         ///
1560         /// # Examples
1561         ///
1562         /// Basic usage:
1563         ///
1564         /// ```
1565         #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".overflowing_add_unsigned(2), (3, false));")]
1566         #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN).overflowing_add_unsigned(", stringify!($UnsignedT), "::MAX), (", stringify!($SelfT), "::MAX, false));")]
1567         #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).overflowing_add_unsigned(3), (", stringify!($SelfT), "::MIN, true));")]
1568         /// ```
1569         #[stable(feature = "mixed_integer_ops", since = "CURRENT_RUSTC_VERSION")]
1570         #[rustc_const_stable(feature = "mixed_integer_ops", since = "CURRENT_RUSTC_VERSION")]
1571         #[must_use = "this returns the result of the operation, \
1572                       without modifying the original"]
1573         #[inline]
1574         pub const fn overflowing_add_unsigned(self, rhs: $UnsignedT) -> (Self, bool) {
1575             let rhs = rhs as Self;
1576             let (res, overflowed) = self.overflowing_add(rhs);
1577             (res, overflowed ^ (rhs < 0))
1578         }
1579
1580         /// Calculates `self` - `rhs`
1581         ///
1582         /// Returns a tuple of the subtraction along with a boolean indicating whether an arithmetic overflow
1583         /// would occur. If an overflow would have occurred then the wrapped value is returned.
1584         ///
1585         /// # Examples
1586         ///
1587         /// Basic usage:
1588         ///
1589         /// ```
1590         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_sub(2), (3, false));")]
1591         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_sub(1), (", stringify!($SelfT), "::MAX, true));")]
1592         /// ```
1593         #[stable(feature = "wrapping", since = "1.7.0")]
1594         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1595         #[must_use = "this returns the result of the operation, \
1596                       without modifying the original"]
1597         #[inline(always)]
1598         pub const fn overflowing_sub(self, rhs: Self) -> (Self, bool) {
1599             let (a, b) = intrinsics::sub_with_overflow(self as $ActualT, rhs as $ActualT);
1600             (a as Self, b)
1601         }
1602
1603         /// Calculates `self - rhs - borrow` without the ability to overflow.
1604         ///
1605         /// Performs "signed ternary subtraction" which takes in an extra bit to subtract, and may return an
1606         /// additional bit of overflow. This signed function is used only on the highest-ordered data,
1607         /// for which the signed overflow result indicates whether the big integer overflowed or not.
1608         ///
1609         /// # Examples
1610         ///
1611         /// Basic usage:
1612         ///
1613         /// ```
1614         /// #![feature(bigint_helper_methods)]
1615         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".borrowing_sub(2, false), (3, false));")]
1616         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".borrowing_sub(2, true), (2, false));")]
1617         #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".borrowing_sub(1, false), (-1, false));")]
1618         #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".borrowing_sub(1, true), (-2, false));")]
1619         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.borrowing_sub(1, true), (", stringify!($SelfT), "::MAX - 1, true));")]
1620         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.borrowing_sub(-1, false), (", stringify!($SelfT), "::MIN, true));")]
1621         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.borrowing_sub(-1, true), (", stringify!($SelfT), "::MAX, false));")]
1622         /// ```
1623         #[unstable(feature = "bigint_helper_methods", issue = "85532")]
1624         #[rustc_const_unstable(feature = "const_bigint_helper_methods", issue = "85532")]
1625         #[must_use = "this returns the result of the operation, \
1626                       without modifying the original"]
1627         #[inline]
1628         pub const fn borrowing_sub(self, rhs: Self, borrow: bool) -> (Self, bool) {
1629             // note: longer-term this should be done via an intrinsic.
1630             // note: no intermediate overflow is required (https://github.com/rust-lang/rust/issues/85532#issuecomment-1032214946).
1631             let (a, b) = self.overflowing_sub(rhs);
1632             let (c, d) = a.overflowing_sub(borrow as $SelfT);
1633             (c, b != d)
1634         }
1635
1636         /// Calculates `self` - `rhs` with an unsigned `rhs`
1637         ///
1638         /// Returns a tuple of the subtraction along with a boolean indicating
1639         /// whether an arithmetic overflow would occur. If an overflow would
1640         /// have occurred then the wrapped value is returned.
1641         ///
1642         /// # Examples
1643         ///
1644         /// Basic usage:
1645         ///
1646         /// ```
1647         #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".overflowing_sub_unsigned(2), (-1, false));")]
1648         #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX).overflowing_sub_unsigned(", stringify!($UnsignedT), "::MAX), (", stringify!($SelfT), "::MIN, false));")]
1649         #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 2).overflowing_sub_unsigned(3), (", stringify!($SelfT), "::MAX, true));")]
1650         /// ```
1651         #[stable(feature = "mixed_integer_ops", since = "CURRENT_RUSTC_VERSION")]
1652         #[rustc_const_stable(feature = "mixed_integer_ops", since = "CURRENT_RUSTC_VERSION")]
1653         #[must_use = "this returns the result of the operation, \
1654                       without modifying the original"]
1655         #[inline]
1656         pub const fn overflowing_sub_unsigned(self, rhs: $UnsignedT) -> (Self, bool) {
1657             let rhs = rhs as Self;
1658             let (res, overflowed) = self.overflowing_sub(rhs);
1659             (res, overflowed ^ (rhs < 0))
1660         }
1661
1662         /// Calculates the multiplication of `self` and `rhs`.
1663         ///
1664         /// Returns a tuple of the multiplication along with a boolean indicating whether an arithmetic overflow
1665         /// would occur. If an overflow would have occurred then the wrapped value is returned.
1666         ///
1667         /// # Examples
1668         ///
1669         /// Basic usage:
1670         ///
1671         /// ```
1672         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_mul(2), (10, false));")]
1673         /// assert_eq!(1_000_000_000i32.overflowing_mul(10), (1410065408, true));
1674         /// ```
1675         #[stable(feature = "wrapping", since = "1.7.0")]
1676         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1677         #[must_use = "this returns the result of the operation, \
1678                       without modifying the original"]
1679         #[inline(always)]
1680         pub const fn overflowing_mul(self, rhs: Self) -> (Self, bool) {
1681             let (a, b) = intrinsics::mul_with_overflow(self as $ActualT, rhs as $ActualT);
1682             (a as Self, b)
1683         }
1684
1685         /// Calculates the divisor when `self` is divided by `rhs`.
1686         ///
1687         /// Returns a tuple of the divisor along with a boolean indicating whether an arithmetic overflow would
1688         /// occur. If an overflow would occur then self is returned.
1689         ///
1690         /// # Panics
1691         ///
1692         /// This function will panic if `rhs` is 0.
1693         ///
1694         /// # Examples
1695         ///
1696         /// Basic usage:
1697         ///
1698         /// ```
1699         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_div(2), (2, false));")]
1700         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_div(-1), (", stringify!($SelfT), "::MIN, true));")]
1701         /// ```
1702         #[inline]
1703         #[stable(feature = "wrapping", since = "1.7.0")]
1704         #[rustc_const_stable(feature = "const_overflowing_int_methods", since = "1.52.0")]
1705         #[must_use = "this returns the result of the operation, \
1706                       without modifying the original"]
1707         pub const fn overflowing_div(self, rhs: Self) -> (Self, bool) {
1708             // Using `&` helps LLVM see that it is the same check made in division.
1709             if unlikely!((self == Self::MIN) & (rhs == -1)) {
1710                 (self, true)
1711             } else {
1712                 (self / rhs, false)
1713             }
1714         }
1715
1716         /// Calculates the quotient of Euclidean division `self.div_euclid(rhs)`.
1717         ///
1718         /// Returns a tuple of the divisor along with a boolean indicating whether an arithmetic overflow would
1719         /// occur. If an overflow would occur then `self` is returned.
1720         ///
1721         /// # Panics
1722         ///
1723         /// This function will panic if `rhs` is 0.
1724         ///
1725         /// # Examples
1726         ///
1727         /// Basic usage:
1728         ///
1729         /// ```
1730         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_div_euclid(2), (2, false));")]
1731         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_div_euclid(-1), (", stringify!($SelfT), "::MIN, true));")]
1732         /// ```
1733         #[inline]
1734         #[stable(feature = "euclidean_division", since = "1.38.0")]
1735         #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
1736         #[must_use = "this returns the result of the operation, \
1737                       without modifying the original"]
1738         pub const fn overflowing_div_euclid(self, rhs: Self) -> (Self, bool) {
1739             // Using `&` helps LLVM see that it is the same check made in division.
1740             if unlikely!((self == Self::MIN) & (rhs == -1)) {
1741                 (self, true)
1742             } else {
1743                 (self.div_euclid(rhs), false)
1744             }
1745         }
1746
1747         /// Calculates the remainder when `self` is divided by `rhs`.
1748         ///
1749         /// Returns a tuple of the remainder after dividing along with a boolean indicating whether an
1750         /// arithmetic overflow would occur. If an overflow would occur then 0 is returned.
1751         ///
1752         /// # Panics
1753         ///
1754         /// This function will panic if `rhs` is 0.
1755         ///
1756         /// # Examples
1757         ///
1758         /// Basic usage:
1759         ///
1760         /// ```
1761         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_rem(2), (1, false));")]
1762         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_rem(-1), (0, true));")]
1763         /// ```
1764         #[inline]
1765         #[stable(feature = "wrapping", since = "1.7.0")]
1766         #[rustc_const_stable(feature = "const_overflowing_int_methods", since = "1.52.0")]
1767         #[must_use = "this returns the result of the operation, \
1768                       without modifying the original"]
1769         pub const fn overflowing_rem(self, rhs: Self) -> (Self, bool) {
1770             if unlikely!(rhs == -1) {
1771                 (0, self == Self::MIN)
1772             } else {
1773                 (self % rhs, false)
1774             }
1775         }
1776
1777
1778         /// Overflowing Euclidean remainder. Calculates `self.rem_euclid(rhs)`.
1779         ///
1780         /// Returns a tuple of the remainder after dividing along with a boolean indicating whether an
1781         /// arithmetic overflow would occur. If an overflow would occur then 0 is returned.
1782         ///
1783         /// # Panics
1784         ///
1785         /// This function will panic if `rhs` is 0.
1786         ///
1787         /// # Examples
1788         ///
1789         /// Basic usage:
1790         ///
1791         /// ```
1792         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_rem_euclid(2), (1, false));")]
1793         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_rem_euclid(-1), (0, true));")]
1794         /// ```
1795         #[stable(feature = "euclidean_division", since = "1.38.0")]
1796         #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
1797         #[must_use = "this returns the result of the operation, \
1798                       without modifying the original"]
1799         #[inline]
1800         pub const fn overflowing_rem_euclid(self, rhs: Self) -> (Self, bool) {
1801             if unlikely!(rhs == -1) {
1802                 (0, self == Self::MIN)
1803             } else {
1804                 (self.rem_euclid(rhs), false)
1805             }
1806         }
1807
1808
1809         /// Negates self, overflowing if this is equal to the minimum value.
1810         ///
1811         /// Returns a tuple of the negated version of self along with a boolean indicating whether an overflow
1812         /// happened. If `self` is the minimum value (e.g., `i32::MIN` for values of type `i32`), then the
1813         /// minimum value will be returned again and `true` will be returned for an overflow happening.
1814         ///
1815         /// # Examples
1816         ///
1817         /// Basic usage:
1818         ///
1819         /// ```
1820         #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".overflowing_neg(), (-2, false));")]
1821         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_neg(), (", stringify!($SelfT), "::MIN, true));")]
1822         /// ```
1823         #[inline]
1824         #[stable(feature = "wrapping", since = "1.7.0")]
1825         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1826         #[must_use = "this returns the result of the operation, \
1827                       without modifying the original"]
1828         #[allow(unused_attributes)]
1829         pub const fn overflowing_neg(self) -> (Self, bool) {
1830             if unlikely!(self == Self::MIN) {
1831                 (Self::MIN, true)
1832             } else {
1833                 (-self, false)
1834             }
1835         }
1836
1837         /// Shifts self left by `rhs` bits.
1838         ///
1839         /// Returns a tuple of the shifted version of self along with a boolean indicating whether the shift
1840         /// value was larger than or equal to the number of bits. If the shift value is too large, then value is
1841         /// masked (N-1) where N is the number of bits, and this value is then used to perform the shift.
1842         ///
1843         /// # Examples
1844         ///
1845         /// Basic usage:
1846         ///
1847         /// ```
1848         #[doc = concat!("assert_eq!(0x1", stringify!($SelfT),".overflowing_shl(4), (0x10, false));")]
1849         /// assert_eq!(0x1i32.overflowing_shl(36), (0x10, true));
1850         /// ```
1851         #[stable(feature = "wrapping", since = "1.7.0")]
1852         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1853         #[must_use = "this returns the result of the operation, \
1854                       without modifying the original"]
1855         #[inline]
1856         pub const fn overflowing_shl(self, rhs: u32) -> (Self, bool) {
1857             (self.wrapping_shl(rhs), (rhs > ($BITS - 1)))
1858         }
1859
1860         /// Shifts self right by `rhs` bits.
1861         ///
1862         /// Returns a tuple of the shifted version of self along with a boolean indicating whether the shift
1863         /// value was larger than or equal to the number of bits. If the shift value is too large, then value is
1864         /// masked (N-1) where N is the number of bits, and this value is then used to perform the shift.
1865         ///
1866         /// # Examples
1867         ///
1868         /// Basic usage:
1869         ///
1870         /// ```
1871         #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".overflowing_shr(4), (0x1, false));")]
1872         /// assert_eq!(0x10i32.overflowing_shr(36), (0x1, true));
1873         /// ```
1874         #[stable(feature = "wrapping", since = "1.7.0")]
1875         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1876         #[must_use = "this returns the result of the operation, \
1877                       without modifying the original"]
1878         #[inline]
1879         pub const fn overflowing_shr(self, rhs: u32) -> (Self, bool) {
1880             (self.wrapping_shr(rhs), (rhs > ($BITS - 1)))
1881         }
1882
1883         /// Computes the absolute value of `self`.
1884         ///
1885         /// Returns a tuple of the absolute version of self along with a boolean indicating whether an overflow
1886         /// happened. If self is the minimum value
1887         #[doc = concat!("(e.g., ", stringify!($SelfT), "::MIN for values of type ", stringify!($SelfT), "),")]
1888         /// then the minimum value will be returned again and true will be returned
1889         /// for an overflow happening.
1890         ///
1891         /// # Examples
1892         ///
1893         /// Basic usage:
1894         ///
1895         /// ```
1896         #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".overflowing_abs(), (10, false));")]
1897         #[doc = concat!("assert_eq!((-10", stringify!($SelfT), ").overflowing_abs(), (10, false));")]
1898         #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN).overflowing_abs(), (", stringify!($SelfT), "::MIN, true));")]
1899         /// ```
1900         #[stable(feature = "no_panic_abs", since = "1.13.0")]
1901         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1902         #[must_use = "this returns the result of the operation, \
1903                       without modifying the original"]
1904         #[inline]
1905         pub const fn overflowing_abs(self) -> (Self, bool) {
1906             (self.wrapping_abs(), self == Self::MIN)
1907         }
1908
1909         /// Raises self to the power of `exp`, using exponentiation by squaring.
1910         ///
1911         /// Returns a tuple of the exponentiation along with a bool indicating
1912         /// whether an overflow happened.
1913         ///
1914         /// # Examples
1915         ///
1916         /// Basic usage:
1917         ///
1918         /// ```
1919         #[doc = concat!("assert_eq!(3", stringify!($SelfT), ".overflowing_pow(4), (81, false));")]
1920         /// assert_eq!(3i8.overflowing_pow(5), (-13, true));
1921         /// ```
1922         #[stable(feature = "no_panic_pow", since = "1.34.0")]
1923         #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
1924         #[must_use = "this returns the result of the operation, \
1925                       without modifying the original"]
1926         #[inline]
1927         pub const fn overflowing_pow(self, mut exp: u32) -> (Self, bool) {
1928             if exp == 0 {
1929                 return (1,false);
1930             }
1931             let mut base = self;
1932             let mut acc: Self = 1;
1933             let mut overflown = false;
1934             // Scratch space for storing results of overflowing_mul.
1935             let mut r;
1936
1937             while exp > 1 {
1938                 if (exp & 1) == 1 {
1939                     r = acc.overflowing_mul(base);
1940                     acc = r.0;
1941                     overflown |= r.1;
1942                 }
1943                 exp /= 2;
1944                 r = base.overflowing_mul(base);
1945                 base = r.0;
1946                 overflown |= r.1;
1947             }
1948
1949             // since exp!=0, finally the exp must be 1.
1950             // Deal with the final bit of the exponent separately, since
1951             // squaring the base afterwards is not necessary and may cause a
1952             // needless overflow.
1953             r = acc.overflowing_mul(base);
1954             r.1 |= overflown;
1955             r
1956         }
1957
1958         /// Raises self to the power of `exp`, using exponentiation by squaring.
1959         ///
1960         /// # Examples
1961         ///
1962         /// Basic usage:
1963         ///
1964         /// ```
1965         #[doc = concat!("let x: ", stringify!($SelfT), " = 2; // or any other integer type")]
1966         ///
1967         /// assert_eq!(x.pow(5), 32);
1968         /// ```
1969         #[stable(feature = "rust1", since = "1.0.0")]
1970         #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
1971         #[must_use = "this returns the result of the operation, \
1972                       without modifying the original"]
1973         #[inline]
1974         #[rustc_inherit_overflow_checks]
1975         pub const fn pow(self, mut exp: u32) -> Self {
1976             if exp == 0 {
1977                 return 1;
1978             }
1979             let mut base = self;
1980             let mut acc = 1;
1981
1982             while exp > 1 {
1983                 if (exp & 1) == 1 {
1984                     acc = acc * base;
1985                 }
1986                 exp /= 2;
1987                 base = base * base;
1988             }
1989
1990             // since exp!=0, finally the exp must be 1.
1991             // Deal with the final bit of the exponent separately, since
1992             // squaring the base afterwards is not necessary and may cause a
1993             // needless overflow.
1994             acc * base
1995         }
1996
1997         /// Calculates the quotient of Euclidean division of `self` by `rhs`.
1998         ///
1999         /// This computes the integer `q` such that `self = q * rhs + r`, with
2000         /// `r = self.rem_euclid(rhs)` and `0 <= r < abs(rhs)`.
2001         ///
2002         /// In other words, the result is `self / rhs` rounded to the integer `q`
2003         /// such that `self >= q * rhs`.
2004         /// If `self > 0`, this is equal to round towards zero (the default in Rust);
2005         /// if `self < 0`, this is equal to round towards +/- infinity.
2006         ///
2007         /// # Panics
2008         ///
2009         /// This function will panic if `rhs` is 0 or the division results in overflow.
2010         ///
2011         /// # Examples
2012         ///
2013         /// Basic usage:
2014         ///
2015         /// ```
2016         #[doc = concat!("let a: ", stringify!($SelfT), " = 7; // or any other integer type")]
2017         /// let b = 4;
2018         ///
2019         /// assert_eq!(a.div_euclid(b), 1); // 7 >= 4 * 1
2020         /// assert_eq!(a.div_euclid(-b), -1); // 7 >= -4 * -1
2021         /// assert_eq!((-a).div_euclid(b), -2); // -7 >= 4 * -2
2022         /// assert_eq!((-a).div_euclid(-b), 2); // -7 >= -4 * 2
2023         /// ```
2024         #[stable(feature = "euclidean_division", since = "1.38.0")]
2025         #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
2026         #[must_use = "this returns the result of the operation, \
2027                       without modifying the original"]
2028         #[inline]
2029         #[rustc_inherit_overflow_checks]
2030         pub const fn div_euclid(self, rhs: Self) -> Self {
2031             let q = self / rhs;
2032             if self % rhs < 0 {
2033                 return if rhs > 0 { q - 1 } else { q + 1 }
2034             }
2035             q
2036         }
2037
2038
2039         /// Calculates the least nonnegative remainder of `self (mod rhs)`.
2040         ///
2041         /// This is done as if by the Euclidean division algorithm -- given
2042         /// `r = self.rem_euclid(rhs)`, `self = rhs * self.div_euclid(rhs) + r`, and
2043         /// `0 <= r < abs(rhs)`.
2044         ///
2045         /// # Panics
2046         ///
2047         /// This function will panic if `rhs` is 0 or the division results in overflow.
2048         ///
2049         /// # Examples
2050         ///
2051         /// Basic usage:
2052         ///
2053         /// ```
2054         #[doc = concat!("let a: ", stringify!($SelfT), " = 7; // or any other integer type")]
2055         /// let b = 4;
2056         ///
2057         /// assert_eq!(a.rem_euclid(b), 3);
2058         /// assert_eq!((-a).rem_euclid(b), 1);
2059         /// assert_eq!(a.rem_euclid(-b), 3);
2060         /// assert_eq!((-a).rem_euclid(-b), 1);
2061         /// ```
2062         #[stable(feature = "euclidean_division", since = "1.38.0")]
2063         #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
2064         #[must_use = "this returns the result of the operation, \
2065                       without modifying the original"]
2066         #[inline]
2067         #[rustc_inherit_overflow_checks]
2068         pub const fn rem_euclid(self, rhs: Self) -> Self {
2069             let r = self % rhs;
2070             if r < 0 {
2071                 if rhs < 0 {
2072                     r - rhs
2073                 } else {
2074                     r + rhs
2075                 }
2076             } else {
2077                 r
2078             }
2079         }
2080
2081         /// Calculates the quotient of `self` and `rhs`, rounding the result towards negative infinity.
2082         ///
2083         /// # Panics
2084         ///
2085         /// This function will panic if `rhs` is zero.
2086         ///
2087         /// ## Overflow behavior
2088         ///
2089         /// On overflow, this function will panic if overflow checks are enabled (default in debug
2090         /// mode) and wrap if overflow checks are disabled (default in release mode).
2091         ///
2092         /// # Examples
2093         ///
2094         /// Basic usage:
2095         ///
2096         /// ```
2097         /// #![feature(int_roundings)]
2098         #[doc = concat!("let a: ", stringify!($SelfT)," = 8;")]
2099         /// let b = 3;
2100         ///
2101         /// assert_eq!(a.div_floor(b), 2);
2102         /// assert_eq!(a.div_floor(-b), -3);
2103         /// assert_eq!((-a).div_floor(b), -3);
2104         /// assert_eq!((-a).div_floor(-b), 2);
2105         /// ```
2106         #[unstable(feature = "int_roundings", issue = "88581")]
2107         #[must_use = "this returns the result of the operation, \
2108                       without modifying the original"]
2109         #[inline]
2110         #[rustc_inherit_overflow_checks]
2111         pub const fn div_floor(self, rhs: Self) -> Self {
2112             let d = self / rhs;
2113             let r = self % rhs;
2114             if (r > 0 && rhs < 0) || (r < 0 && rhs > 0) {
2115                 d - 1
2116             } else {
2117                 d
2118             }
2119         }
2120
2121         /// Calculates the quotient of `self` and `rhs`, rounding the result towards positive infinity.
2122         ///
2123         /// # Panics
2124         ///
2125         /// This function will panic if `rhs` is zero.
2126         ///
2127         /// ## Overflow behavior
2128         ///
2129         /// On overflow, this function will panic if overflow checks are enabled (default in debug
2130         /// mode) and wrap if overflow checks are disabled (default in release mode).
2131         ///
2132         /// # Examples
2133         ///
2134         /// Basic usage:
2135         ///
2136         /// ```
2137         /// #![feature(int_roundings)]
2138         #[doc = concat!("let a: ", stringify!($SelfT)," = 8;")]
2139         /// let b = 3;
2140         ///
2141         /// assert_eq!(a.div_ceil(b), 3);
2142         /// assert_eq!(a.div_ceil(-b), -2);
2143         /// assert_eq!((-a).div_ceil(b), -2);
2144         /// assert_eq!((-a).div_ceil(-b), 3);
2145         /// ```
2146         #[unstable(feature = "int_roundings", issue = "88581")]
2147         #[must_use = "this returns the result of the operation, \
2148                       without modifying the original"]
2149         #[inline]
2150         #[rustc_inherit_overflow_checks]
2151         pub const fn div_ceil(self, rhs: Self) -> Self {
2152             let d = self / rhs;
2153             let r = self % rhs;
2154             if (r > 0 && rhs > 0) || (r < 0 && rhs < 0) {
2155                 d + 1
2156             } else {
2157                 d
2158             }
2159         }
2160
2161         /// If `rhs` is positive, calculates the smallest value greater than or
2162         /// equal to `self` that is a multiple of `rhs`. If `rhs` is negative,
2163         /// calculates the largest value less than or equal to `self` that is a
2164         /// multiple of `rhs`.
2165         ///
2166         /// # Panics
2167         ///
2168         /// This function will panic if `rhs` is zero.
2169         ///
2170         /// ## Overflow behavior
2171         ///
2172         /// On overflow, this function will panic if overflow checks are enabled (default in debug
2173         /// mode) and wrap if overflow checks are disabled (default in release mode).
2174         ///
2175         /// # Examples
2176         ///
2177         /// Basic usage:
2178         ///
2179         /// ```
2180         /// #![feature(int_roundings)]
2181         #[doc = concat!("assert_eq!(16_", stringify!($SelfT), ".next_multiple_of(8), 16);")]
2182         #[doc = concat!("assert_eq!(23_", stringify!($SelfT), ".next_multiple_of(8), 24);")]
2183         #[doc = concat!("assert_eq!(16_", stringify!($SelfT), ".next_multiple_of(-8), 16);")]
2184         #[doc = concat!("assert_eq!(23_", stringify!($SelfT), ".next_multiple_of(-8), 16);")]
2185         #[doc = concat!("assert_eq!((-16_", stringify!($SelfT), ").next_multiple_of(8), -16);")]
2186         #[doc = concat!("assert_eq!((-23_", stringify!($SelfT), ").next_multiple_of(8), -16);")]
2187         #[doc = concat!("assert_eq!((-16_", stringify!($SelfT), ").next_multiple_of(-8), -16);")]
2188         #[doc = concat!("assert_eq!((-23_", stringify!($SelfT), ").next_multiple_of(-8), -24);")]
2189         /// ```
2190         #[unstable(feature = "int_roundings", issue = "88581")]
2191         #[must_use = "this returns the result of the operation, \
2192                       without modifying the original"]
2193         #[inline]
2194         #[rustc_inherit_overflow_checks]
2195         pub const fn next_multiple_of(self, rhs: Self) -> Self {
2196             // This would otherwise fail when calculating `r` when self == T::MIN.
2197             if rhs == -1 {
2198                 return self;
2199             }
2200
2201             let r = self % rhs;
2202             let m = if (r > 0 && rhs < 0) || (r < 0 && rhs > 0) {
2203                 r + rhs
2204             } else {
2205                 r
2206             };
2207
2208             if m == 0 {
2209                 self
2210             } else {
2211                 self + (rhs - m)
2212             }
2213         }
2214
2215         /// If `rhs` is positive, calculates the smallest value greater than or
2216         /// equal to `self` that is a multiple of `rhs`. If `rhs` is negative,
2217         /// calculates the largest value less than or equal to `self` that is a
2218         /// multiple of `rhs`. Returns `None` if `rhs` is zero or the operation
2219         /// would result in overflow.
2220         ///
2221         /// # Examples
2222         ///
2223         /// Basic usage:
2224         ///
2225         /// ```
2226         /// #![feature(int_roundings)]
2227         #[doc = concat!("assert_eq!(16_", stringify!($SelfT), ".checked_next_multiple_of(8), Some(16));")]
2228         #[doc = concat!("assert_eq!(23_", stringify!($SelfT), ".checked_next_multiple_of(8), Some(24));")]
2229         #[doc = concat!("assert_eq!(16_", stringify!($SelfT), ".checked_next_multiple_of(-8), Some(16));")]
2230         #[doc = concat!("assert_eq!(23_", stringify!($SelfT), ".checked_next_multiple_of(-8), Some(16));")]
2231         #[doc = concat!("assert_eq!((-16_", stringify!($SelfT), ").checked_next_multiple_of(8), Some(-16));")]
2232         #[doc = concat!("assert_eq!((-23_", stringify!($SelfT), ").checked_next_multiple_of(8), Some(-16));")]
2233         #[doc = concat!("assert_eq!((-16_", stringify!($SelfT), ").checked_next_multiple_of(-8), Some(-16));")]
2234         #[doc = concat!("assert_eq!((-23_", stringify!($SelfT), ").checked_next_multiple_of(-8), Some(-24));")]
2235         #[doc = concat!("assert_eq!(1_", stringify!($SelfT), ".checked_next_multiple_of(0), None);")]
2236         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_next_multiple_of(2), None);")]
2237         /// ```
2238         #[unstable(feature = "int_roundings", issue = "88581")]
2239         #[must_use = "this returns the result of the operation, \
2240                       without modifying the original"]
2241         #[inline]
2242         pub const fn checked_next_multiple_of(self, rhs: Self) -> Option<Self> {
2243             // This would otherwise fail when calculating `r` when self == T::MIN.
2244             if rhs == -1 {
2245                 return Some(self);
2246             }
2247
2248             let r = try_opt!(self.checked_rem(rhs));
2249             let m = if (r > 0 && rhs < 0) || (r < 0 && rhs > 0) {
2250                 // r + rhs cannot overflow because they have opposite signs
2251                 r + rhs
2252             } else {
2253                 r
2254             };
2255
2256             if m == 0 {
2257                 Some(self)
2258             } else {
2259                 // rhs - m cannot overflow because m has the same sign as rhs
2260                 self.checked_add(rhs - m)
2261             }
2262         }
2263
2264         /// Returns the logarithm of the number with respect to an arbitrary base,
2265         /// rounded down.
2266         ///
2267         /// This method might not be optimized owing to implementation details;
2268         /// `ilog2` can produce results more efficiently for base 2, and `ilog10`
2269         /// can produce results more efficiently for base 10.
2270         ///
2271         /// # Panics
2272         ///
2273         /// This function will panic if `self` is less than or equal to zero,
2274         /// or if `base` is less then 2.
2275         ///
2276         /// # Examples
2277         ///
2278         /// ```
2279         /// #![feature(int_log)]
2280         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".ilog(5), 1);")]
2281         /// ```
2282         #[unstable(feature = "int_log", issue = "70887")]
2283         #[must_use = "this returns the result of the operation, \
2284                       without modifying the original"]
2285         #[inline]
2286         #[track_caller]
2287         pub const fn ilog(self, base: Self) -> u32 {
2288             assert!(base >= 2, "base of integer logarithm must be at least 2");
2289             self.checked_ilog(base).expect("argument of integer logarithm must be positive")
2290         }
2291
2292         /// Returns the base 2 logarithm of the number, rounded down.
2293         ///
2294         /// # Panics
2295         ///
2296         /// This function will panic if `self` is less than or equal to zero.
2297         ///
2298         /// # Examples
2299         ///
2300         /// ```
2301         /// #![feature(int_log)]
2302         #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".ilog2(), 1);")]
2303         /// ```
2304         #[unstable(feature = "int_log", issue = "70887")]
2305         #[must_use = "this returns the result of the operation, \
2306                       without modifying the original"]
2307         #[inline]
2308         #[track_caller]
2309         pub const fn ilog2(self) -> u32 {
2310             self.checked_ilog2().expect("argument of integer logarithm must be positive")
2311         }
2312
2313         /// Returns the base 10 logarithm of the number, rounded down.
2314         ///
2315         /// # Panics
2316         ///
2317         /// This function will panic if `self` is less than or equal to zero.
2318         ///
2319         /// # Example
2320         ///
2321         /// ```
2322         /// #![feature(int_log)]
2323         #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".ilog10(), 1);")]
2324         /// ```
2325         #[unstable(feature = "int_log", issue = "70887")]
2326         #[must_use = "this returns the result of the operation, \
2327                       without modifying the original"]
2328         #[inline]
2329         #[track_caller]
2330         pub const fn ilog10(self) -> u32 {
2331             self.checked_ilog10().expect("argument of integer logarithm must be positive")
2332         }
2333
2334         /// Returns the logarithm of the number with respect to an arbitrary base,
2335         /// rounded down.
2336         ///
2337         /// Returns `None` if the number is negative or zero, or if the base is not at least 2.
2338         ///
2339         /// This method might not be optimized owing to implementation details;
2340         /// `checked_ilog2` can produce results more efficiently for base 2, and
2341         /// `checked_ilog10` can produce results more efficiently for base 10.
2342         ///
2343         /// # Examples
2344         ///
2345         /// ```
2346         /// #![feature(int_log)]
2347         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_ilog(5), Some(1));")]
2348         /// ```
2349         #[unstable(feature = "int_log", issue = "70887")]
2350         #[must_use = "this returns the result of the operation, \
2351                       without modifying the original"]
2352         #[inline]
2353         pub const fn checked_ilog(self, base: Self) -> Option<u32> {
2354             if self <= 0 || base <= 1 {
2355                 None
2356             } else {
2357                 let mut n = 0;
2358                 let mut r = self;
2359
2360                 // Optimization for 128 bit wide integers.
2361                 if Self::BITS == 128 {
2362                     let b = Self::ilog2(self) / (Self::ilog2(base) + 1);
2363                     n += b;
2364                     r /= base.pow(b as u32);
2365                 }
2366
2367                 while r >= base {
2368                     r /= base;
2369                     n += 1;
2370                 }
2371                 Some(n)
2372             }
2373         }
2374
2375         /// Returns the base 2 logarithm of the number, rounded down.
2376         ///
2377         /// Returns `None` if the number is negative or zero.
2378         ///
2379         /// # Examples
2380         ///
2381         /// ```
2382         /// #![feature(int_log)]
2383         #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".checked_ilog2(), Some(1));")]
2384         /// ```
2385         #[unstable(feature = "int_log", issue = "70887")]
2386         #[must_use = "this returns the result of the operation, \
2387                       without modifying the original"]
2388         #[inline]
2389         pub const fn checked_ilog2(self) -> Option<u32> {
2390             if self <= 0 {
2391                 None
2392             } else {
2393                 // SAFETY: We just checked that this number is positive
2394                 let log = (Self::BITS - 1) - unsafe { intrinsics::ctlz_nonzero(self) as u32 };
2395                 Some(log)
2396             }
2397         }
2398
2399         /// Returns the base 10 logarithm of the number, rounded down.
2400         ///
2401         /// Returns `None` if the number is negative or zero.
2402         ///
2403         /// # Example
2404         ///
2405         /// ```
2406         /// #![feature(int_log)]
2407         #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".checked_ilog10(), Some(1));")]
2408         /// ```
2409         #[unstable(feature = "int_log", issue = "70887")]
2410         #[must_use = "this returns the result of the operation, \
2411                       without modifying the original"]
2412         #[inline]
2413         pub const fn checked_ilog10(self) -> Option<u32> {
2414             if self > 0 {
2415                 Some(int_log10::$ActualT(self as $ActualT))
2416             } else {
2417                 None
2418             }
2419         }
2420
2421         /// Computes the absolute value of `self`.
2422         ///
2423         /// # Overflow behavior
2424         ///
2425         /// The absolute value of
2426         #[doc = concat!("`", stringify!($SelfT), "::MIN`")]
2427         /// cannot be represented as an
2428         #[doc = concat!("`", stringify!($SelfT), "`,")]
2429         /// and attempting to calculate it will cause an overflow. This means
2430         /// that code in debug mode will trigger a panic on this case and
2431         /// optimized code will return
2432         #[doc = concat!("`", stringify!($SelfT), "::MIN`")]
2433         /// without a panic.
2434         ///
2435         /// # Examples
2436         ///
2437         /// Basic usage:
2438         ///
2439         /// ```
2440         #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".abs(), 10);")]
2441         #[doc = concat!("assert_eq!((-10", stringify!($SelfT), ").abs(), 10);")]
2442         /// ```
2443         #[stable(feature = "rust1", since = "1.0.0")]
2444         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
2445         #[allow(unused_attributes)]
2446         #[must_use = "this returns the result of the operation, \
2447                       without modifying the original"]
2448         #[inline]
2449         #[rustc_inherit_overflow_checks]
2450         pub const fn abs(self) -> Self {
2451             // Note that the #[rustc_inherit_overflow_checks] and #[inline]
2452             // above mean that the overflow semantics of the subtraction
2453             // depend on the crate we're being called from.
2454             if self.is_negative() {
2455                 -self
2456             } else {
2457                 self
2458             }
2459         }
2460
2461         /// Computes the absolute difference between `self` and `other`.
2462         ///
2463         /// This function always returns the correct answer without overflow or
2464         /// panics by returning an unsigned integer.
2465         ///
2466         /// # Examples
2467         ///
2468         /// Basic usage:
2469         ///
2470         /// ```
2471         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".abs_diff(80), 20", stringify!($UnsignedT), ");")]
2472         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".abs_diff(110), 10", stringify!($UnsignedT), ");")]
2473         #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").abs_diff(80), 180", stringify!($UnsignedT), ");")]
2474         #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").abs_diff(-120), 20", stringify!($UnsignedT), ");")]
2475         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.abs_diff(", stringify!($SelfT), "::MAX), ", stringify!($UnsignedT), "::MAX);")]
2476         /// ```
2477         #[stable(feature = "int_abs_diff", since = "1.60.0")]
2478         #[rustc_const_stable(feature = "int_abs_diff", since = "1.60.0")]
2479         #[must_use = "this returns the result of the operation, \
2480                       without modifying the original"]
2481         #[inline]
2482         pub const fn abs_diff(self, other: Self) -> $UnsignedT {
2483             if self < other {
2484                 // Converting a non-negative x from signed to unsigned by using
2485                 // `x as U` is left unchanged, but a negative x is converted
2486                 // to value x + 2^N. Thus if `s` and `o` are binary variables
2487                 // respectively indicating whether `self` and `other` are
2488                 // negative, we are computing the mathematical value:
2489                 //
2490                 //    (other + o*2^N) - (self + s*2^N)    mod  2^N
2491                 //    other - self + (o-s)*2^N            mod  2^N
2492                 //    other - self                        mod  2^N
2493                 //
2494                 // Finally, taking the mod 2^N of the mathematical value of
2495                 // `other - self` does not change it as it already is
2496                 // in the range [0, 2^N).
2497                 (other as $UnsignedT).wrapping_sub(self as $UnsignedT)
2498             } else {
2499                 (self as $UnsignedT).wrapping_sub(other as $UnsignedT)
2500             }
2501         }
2502
2503         /// Returns a number representing sign of `self`.
2504         ///
2505         ///  - `0` if the number is zero
2506         ///  - `1` if the number is positive
2507         ///  - `-1` if the number is negative
2508         ///
2509         /// # Examples
2510         ///
2511         /// Basic usage:
2512         ///
2513         /// ```
2514         #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".signum(), 1);")]
2515         #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".signum(), 0);")]
2516         #[doc = concat!("assert_eq!((-10", stringify!($SelfT), ").signum(), -1);")]
2517         /// ```
2518         #[stable(feature = "rust1", since = "1.0.0")]
2519         #[rustc_const_stable(feature = "const_int_sign", since = "1.47.0")]
2520         #[must_use = "this returns the result of the operation, \
2521                       without modifying the original"]
2522         #[inline(always)]
2523         pub const fn signum(self) -> Self {
2524             match self {
2525                 n if n > 0 =>  1,
2526                 0          =>  0,
2527                 _          => -1,
2528             }
2529         }
2530
2531         /// Returns `true` if `self` is positive and `false` if the number is zero or
2532         /// negative.
2533         ///
2534         /// # Examples
2535         ///
2536         /// Basic usage:
2537         ///
2538         /// ```
2539         #[doc = concat!("assert!(10", stringify!($SelfT), ".is_positive());")]
2540         #[doc = concat!("assert!(!(-10", stringify!($SelfT), ").is_positive());")]
2541         /// ```
2542         #[must_use]
2543         #[stable(feature = "rust1", since = "1.0.0")]
2544         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
2545         #[inline(always)]
2546         pub const fn is_positive(self) -> bool { self > 0 }
2547
2548         /// Returns `true` if `self` is negative and `false` if the number is zero or
2549         /// positive.
2550         ///
2551         /// # Examples
2552         ///
2553         /// Basic usage:
2554         ///
2555         /// ```
2556         #[doc = concat!("assert!((-10", stringify!($SelfT), ").is_negative());")]
2557         #[doc = concat!("assert!(!10", stringify!($SelfT), ".is_negative());")]
2558         /// ```
2559         #[must_use]
2560         #[stable(feature = "rust1", since = "1.0.0")]
2561         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
2562         #[inline(always)]
2563         pub const fn is_negative(self) -> bool { self < 0 }
2564
2565         /// Return the memory representation of this integer as a byte array in
2566         /// big-endian (network) byte order.
2567         ///
2568         #[doc = $to_xe_bytes_doc]
2569         ///
2570         /// # Examples
2571         ///
2572         /// ```
2573         #[doc = concat!("let bytes = ", $swap_op, stringify!($SelfT), ".to_be_bytes();")]
2574         #[doc = concat!("assert_eq!(bytes, ", $be_bytes, ");")]
2575         /// ```
2576         #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2577         #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2578         #[must_use = "this returns the result of the operation, \
2579                       without modifying the original"]
2580         #[inline]
2581         pub const fn to_be_bytes(self) -> [u8; mem::size_of::<Self>()] {
2582             self.to_be().to_ne_bytes()
2583         }
2584
2585         /// Return the memory representation of this integer as a byte array in
2586         /// little-endian byte order.
2587         ///
2588         #[doc = $to_xe_bytes_doc]
2589         ///
2590         /// # Examples
2591         ///
2592         /// ```
2593         #[doc = concat!("let bytes = ", $swap_op, stringify!($SelfT), ".to_le_bytes();")]
2594         #[doc = concat!("assert_eq!(bytes, ", $le_bytes, ");")]
2595         /// ```
2596         #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2597         #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2598         #[must_use = "this returns the result of the operation, \
2599                       without modifying the original"]
2600         #[inline]
2601         pub const fn to_le_bytes(self) -> [u8; mem::size_of::<Self>()] {
2602             self.to_le().to_ne_bytes()
2603         }
2604
2605         /// Return the memory representation of this integer as a byte array in
2606         /// native byte order.
2607         ///
2608         /// As the target platform's native endianness is used, portable code
2609         /// should use [`to_be_bytes`] or [`to_le_bytes`], as appropriate,
2610         /// instead.
2611         ///
2612         #[doc = $to_xe_bytes_doc]
2613         ///
2614         /// [`to_be_bytes`]: Self::to_be_bytes
2615         /// [`to_le_bytes`]: Self::to_le_bytes
2616         ///
2617         /// # Examples
2618         ///
2619         /// ```
2620         #[doc = concat!("let bytes = ", $swap_op, stringify!($SelfT), ".to_ne_bytes();")]
2621         /// assert_eq!(
2622         ///     bytes,
2623         ///     if cfg!(target_endian = "big") {
2624         #[doc = concat!("        ", $be_bytes)]
2625         ///     } else {
2626         #[doc = concat!("        ", $le_bytes)]
2627         ///     }
2628         /// );
2629         /// ```
2630         #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2631         #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2632         // SAFETY: const sound because integers are plain old datatypes so we can always
2633         // transmute them to arrays of bytes
2634         #[must_use = "this returns the result of the operation, \
2635                       without modifying the original"]
2636         #[inline]
2637         pub const fn to_ne_bytes(self) -> [u8; mem::size_of::<Self>()] {
2638             // SAFETY: integers are plain old datatypes so we can always transmute them to
2639             // arrays of bytes
2640             unsafe { mem::transmute(self) }
2641         }
2642
2643         /// Create an integer value from its representation as a byte array in
2644         /// big endian.
2645         ///
2646         #[doc = $from_xe_bytes_doc]
2647         ///
2648         /// # Examples
2649         ///
2650         /// ```
2651         #[doc = concat!("let value = ", stringify!($SelfT), "::from_be_bytes(", $be_bytes, ");")]
2652         #[doc = concat!("assert_eq!(value, ", $swap_op, ");")]
2653         /// ```
2654         ///
2655         /// When starting from a slice rather than an array, fallible conversion APIs can be used:
2656         ///
2657         /// ```
2658         #[doc = concat!("fn read_be_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {")]
2659         #[doc = concat!("    let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());")]
2660         ///     *input = rest;
2661         #[doc = concat!("    ", stringify!($SelfT), "::from_be_bytes(int_bytes.try_into().unwrap())")]
2662         /// }
2663         /// ```
2664         #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2665         #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2666         #[must_use]
2667         #[inline]
2668         pub const fn from_be_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
2669             Self::from_be(Self::from_ne_bytes(bytes))
2670         }
2671
2672         /// Create an integer value from its representation as a byte array in
2673         /// little endian.
2674         ///
2675         #[doc = $from_xe_bytes_doc]
2676         ///
2677         /// # Examples
2678         ///
2679         /// ```
2680         #[doc = concat!("let value = ", stringify!($SelfT), "::from_le_bytes(", $le_bytes, ");")]
2681         #[doc = concat!("assert_eq!(value, ", $swap_op, ");")]
2682         /// ```
2683         ///
2684         /// When starting from a slice rather than an array, fallible conversion APIs can be used:
2685         ///
2686         /// ```
2687         #[doc = concat!("fn read_le_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {")]
2688         #[doc = concat!("    let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());")]
2689         ///     *input = rest;
2690         #[doc = concat!("    ", stringify!($SelfT), "::from_le_bytes(int_bytes.try_into().unwrap())")]
2691         /// }
2692         /// ```
2693         #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2694         #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2695         #[must_use]
2696         #[inline]
2697         pub const fn from_le_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
2698             Self::from_le(Self::from_ne_bytes(bytes))
2699         }
2700
2701         /// Create an integer value from its memory representation as a byte
2702         /// array in native endianness.
2703         ///
2704         /// As the target platform's native endianness is used, portable code
2705         /// likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as
2706         /// appropriate instead.
2707         ///
2708         /// [`from_be_bytes`]: Self::from_be_bytes
2709         /// [`from_le_bytes`]: Self::from_le_bytes
2710         ///
2711         #[doc = $from_xe_bytes_doc]
2712         ///
2713         /// # Examples
2714         ///
2715         /// ```
2716         #[doc = concat!("let value = ", stringify!($SelfT), "::from_ne_bytes(if cfg!(target_endian = \"big\") {")]
2717         #[doc = concat!("    ", $be_bytes)]
2718         /// } else {
2719         #[doc = concat!("    ", $le_bytes)]
2720         /// });
2721         #[doc = concat!("assert_eq!(value, ", $swap_op, ");")]
2722         /// ```
2723         ///
2724         /// When starting from a slice rather than an array, fallible conversion APIs can be used:
2725         ///
2726         /// ```
2727         #[doc = concat!("fn read_ne_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {")]
2728         #[doc = concat!("    let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());")]
2729         ///     *input = rest;
2730         #[doc = concat!("    ", stringify!($SelfT), "::from_ne_bytes(int_bytes.try_into().unwrap())")]
2731         /// }
2732         /// ```
2733         #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2734         #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2735         #[must_use]
2736         // SAFETY: const sound because integers are plain old datatypes so we can always
2737         // transmute to them
2738         #[inline]
2739         pub const fn from_ne_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
2740             // SAFETY: integers are plain old datatypes so we can always transmute to them
2741             unsafe { mem::transmute(bytes) }
2742         }
2743
2744         /// New code should prefer to use
2745         #[doc = concat!("[`", stringify!($SelfT), "::MIN", "`] instead.")]
2746         ///
2747         /// Returns the smallest value that can be represented by this integer type.
2748         #[stable(feature = "rust1", since = "1.0.0")]
2749         #[inline(always)]
2750         #[rustc_promotable]
2751         #[rustc_const_stable(feature = "const_min_value", since = "1.32.0")]
2752         #[deprecated(since = "TBD", note = "replaced by the `MIN` associated constant on this type")]
2753         pub const fn min_value() -> Self {
2754             Self::MIN
2755         }
2756
2757         /// New code should prefer to use
2758         #[doc = concat!("[`", stringify!($SelfT), "::MAX", "`] instead.")]
2759         ///
2760         /// Returns the largest value that can be represented by this integer type.
2761         #[stable(feature = "rust1", since = "1.0.0")]
2762         #[inline(always)]
2763         #[rustc_promotable]
2764         #[rustc_const_stable(feature = "const_max_value", since = "1.32.0")]
2765         #[deprecated(since = "TBD", note = "replaced by the `MAX` associated constant on this type")]
2766         pub const fn max_value() -> Self {
2767             Self::MAX
2768         }
2769     }
2770 }