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