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