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 division. Computes `self / rhs`, saturating at the
 922         /// numeric bounds instead of overflowing.
 923         ///
 924         /// # Examples
 925         ///
 926         /// Basic usage:
 927         ///
 928         /// ```
 929         /// #![feature(saturating_div)]
 930         ///
 931         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".saturating_div(2), 2);")]
 932         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_div(-1), ", stringify!($SelfT), "::MIN + 1);")]
 933         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_div(-1), ", stringify!($SelfT), "::MAX);")]
 934         ///
 935         /// ```
 936         ///
 937         /// ```should_panic
 938         /// #![feature(saturating_div)]
 939         ///
 940         #[doc = concat!("let _ = 1", stringify!($SelfT), ".saturating_div(0);")]
 941         ///
 942         /// ```
 943         #[unstable(feature = "saturating_div", issue = "87920")]
 944         #[rustc_const_unstable(feature = "saturating_div", issue = "87920")]
 945         #[must_use = "this returns the result of the operation, \
 946                       without modifying the original"]
 947         #[inline]
 948         pub const fn saturating_div(self, rhs: Self) -> Self {
 949             match self.overflowing_div(rhs) {
 950                 (result, false) => result,
 951                 (_result, true) => Self::MAX, // MIN / -1 is the only possible saturating overflow
 952             }
 953         }
 954
 955         /// Saturating integer exponentiation. Computes `self.pow(exp)`,
 956         /// saturating at the numeric bounds instead of overflowing.
 957         ///
 958         /// # Examples
 959         ///
 960         /// Basic usage:
 961         ///
 962         /// ```
 963         ///
 964         #[doc = concat!("assert_eq!((-4", stringify!($SelfT), ").saturating_pow(3), -64);")]
 965         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_pow(2), ", stringify!($SelfT), "::MAX);")]
 966         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_pow(3), ", stringify!($SelfT), "::MIN);")]
 967         /// ```
 968         #[stable(feature = "no_panic_pow", since = "1.34.0")]
 969         #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
 970         #[must_use = "this returns the result of the operation, \
 971                       without modifying the original"]
 972         #[inline]
 973         pub const fn saturating_pow(self, exp: u32) -> Self {
 974             match self.checked_pow(exp) {
 975                 Some(x) => x,
 976                 None if self < 0 && exp % 2 == 1 => Self::MIN,
 977                 None => Self::MAX,
 978             }
 979         }
 980
 981         /// Wrapping (modular) addition. Computes `self + rhs`, wrapping around at the
 982         /// boundary of the type.
 983         ///
 984         /// # Examples
 985         ///
 986         /// Basic usage:
 987         ///
 988         /// ```
 989         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_add(27), 127);")]
 990         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.wrapping_add(2), ", stringify!($SelfT), "::MIN + 1);")]
 991         /// ```
 992         #[stable(feature = "rust1", since = "1.0.0")]
 993         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
 994         #[must_use = "this returns the result of the operation, \
 995                       without modifying the original"]
 996         #[inline(always)]
 997         pub const fn wrapping_add(self, rhs: Self) -> Self {
 998             intrinsics::wrapping_add(self, rhs)
 999         }
1000
1001         /// Wrapping (modular) subtraction. Computes `self - rhs`, wrapping around at the
1002         /// boundary of the type.
1003         ///
1004         /// # Examples
1005         ///
1006         /// Basic usage:
1007         ///
1008         /// ```
1009         #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".wrapping_sub(127), -127);")]
1010         #[doc = concat!("assert_eq!((-2", stringify!($SelfT), ").wrapping_sub(", stringify!($SelfT), "::MAX), ", stringify!($SelfT), "::MAX);")]
1011         /// ```
1012         #[stable(feature = "rust1", since = "1.0.0")]
1013         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1014         #[must_use = "this returns the result of the operation, \
1015                       without modifying the original"]
1016         #[inline(always)]
1017         pub const fn wrapping_sub(self, rhs: Self) -> Self {
1018             intrinsics::wrapping_sub(self, rhs)
1019         }
1020
1021         /// Wrapping (modular) multiplication. Computes `self * rhs`, wrapping around at
1022         /// the boundary of the type.
1023         ///
1024         /// # Examples
1025         ///
1026         /// Basic usage:
1027         ///
1028         /// ```
1029         #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".wrapping_mul(12), 120);")]
1030         /// assert_eq!(11i8.wrapping_mul(12), -124);
1031         /// ```
1032         #[stable(feature = "rust1", since = "1.0.0")]
1033         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1034         #[must_use = "this returns the result of the operation, \
1035                       without modifying the original"]
1036         #[inline(always)]
1037         pub const fn wrapping_mul(self, rhs: Self) -> Self {
1038             intrinsics::wrapping_mul(self, rhs)
1039         }
1040
1041         /// Wrapping (modular) division. Computes `self / rhs`, wrapping around at the
1042         /// boundary of the type.
1043         ///
1044         /// The only case where such wrapping can occur is when one divides `MIN / -1` on a signed type (where
1045         /// `MIN` is the negative minimal value for the type); this is equivalent to `-MIN`, a positive value
1046         /// that is too large to represent in the type. In such a case, this function returns `MIN` itself.
1047         ///
1048         /// # Panics
1049         ///
1050         /// This function will panic if `rhs` is 0.
1051         ///
1052         /// # Examples
1053         ///
1054         /// Basic usage:
1055         ///
1056         /// ```
1057         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_div(10), 10);")]
1058         /// assert_eq!((-128i8).wrapping_div(-1), -128);
1059         /// ```
1060         #[stable(feature = "num_wrapping", since = "1.2.0")]
1061         #[rustc_const_stable(feature = "const_wrapping_int_methods", since = "1.52.0")]
1062         #[must_use = "this returns the result of the operation, \
1063                       without modifying the original"]
1064         #[inline]
1065         pub const fn wrapping_div(self, rhs: Self) -> Self {
1066             self.overflowing_div(rhs).0
1067         }
1068
1069         /// Wrapping Euclidean division. Computes `self.div_euclid(rhs)`,
1070         /// wrapping around at the boundary of the type.
1071         ///
1072         /// Wrapping will only occur in `MIN / -1` on a signed type (where `MIN` is the negative minimal value
1073         /// for the type). This is equivalent to `-MIN`, a positive value that is too large to represent in the
1074         /// type. In this case, this method returns `MIN` itself.
1075         ///
1076         /// # Panics
1077         ///
1078         /// This function will panic if `rhs` is 0.
1079         ///
1080         /// # Examples
1081         ///
1082         /// Basic usage:
1083         ///
1084         /// ```
1085         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_div_euclid(10), 10);")]
1086         /// assert_eq!((-128i8).wrapping_div_euclid(-1), -128);
1087         /// ```
1088         #[stable(feature = "euclidean_division", since = "1.38.0")]
1089         #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
1090         #[must_use = "this returns the result of the operation, \
1091                       without modifying the original"]
1092         #[inline]
1093         pub const fn wrapping_div_euclid(self, rhs: Self) -> Self {
1094             self.overflowing_div_euclid(rhs).0
1095         }
1096
1097         /// Wrapping (modular) remainder. Computes `self % rhs`, wrapping around at the
1098         /// boundary of the type.
1099         ///
1100         /// Such wrap-around never actually occurs mathematically; implementation artifacts make `x % y`
1101         /// invalid for `MIN / -1` on a signed type (where `MIN` is the negative minimal value). In such a case,
1102         /// this function returns `0`.
1103         ///
1104         /// # Panics
1105         ///
1106         /// This function will panic if `rhs` is 0.
1107         ///
1108         /// # Examples
1109         ///
1110         /// Basic usage:
1111         ///
1112         /// ```
1113         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_rem(10), 0);")]
1114         /// assert_eq!((-128i8).wrapping_rem(-1), 0);
1115         /// ```
1116         #[stable(feature = "num_wrapping", since = "1.2.0")]
1117         #[rustc_const_stable(feature = "const_wrapping_int_methods", since = "1.52.0")]
1118         #[must_use = "this returns the result of the operation, \
1119                       without modifying the original"]
1120         #[inline]
1121         pub const fn wrapping_rem(self, rhs: Self) -> Self {
1122             self.overflowing_rem(rhs).0
1123         }
1124
1125         /// Wrapping Euclidean remainder. Computes `self.rem_euclid(rhs)`, wrapping around
1126         /// at the boundary of the type.
1127         ///
1128         /// Wrapping will only occur in `MIN % -1` on a signed type (where `MIN` is the negative minimal value
1129         /// for the type). In this case, this method returns 0.
1130         ///
1131         /// # Panics
1132         ///
1133         /// This function will panic if `rhs` is 0.
1134         ///
1135         /// # Examples
1136         ///
1137         /// Basic usage:
1138         ///
1139         /// ```
1140         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_rem_euclid(10), 0);")]
1141         /// assert_eq!((-128i8).wrapping_rem_euclid(-1), 0);
1142         /// ```
1143         #[stable(feature = "euclidean_division", since = "1.38.0")]
1144         #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
1145         #[must_use = "this returns the result of the operation, \
1146                       without modifying the original"]
1147         #[inline]
1148         pub const fn wrapping_rem_euclid(self, rhs: Self) -> Self {
1149             self.overflowing_rem_euclid(rhs).0
1150         }
1151
1152         /// Wrapping (modular) negation. Computes `-self`, wrapping around at the boundary
1153         /// of the type.
1154         ///
1155         /// The only case where such wrapping can occur is when one negates `MIN` on a signed type (where `MIN`
1156         /// is the negative minimal value for the type); this is a positive value that is too large to represent
1157         /// in the type. In such a case, this function returns `MIN` itself.
1158         ///
1159         /// # Examples
1160         ///
1161         /// Basic usage:
1162         ///
1163         /// ```
1164         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_neg(), -100);")]
1165         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.wrapping_neg(), ", stringify!($SelfT), "::MIN);")]
1166         /// ```
1167         #[stable(feature = "num_wrapping", since = "1.2.0")]
1168         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1169         #[inline(always)]
1170         pub const fn wrapping_neg(self) -> Self {
1171             (0 as $SelfT).wrapping_sub(self)
1172         }
1173
1174         /// Panic-free bitwise shift-left; yields `self << mask(rhs)`, where `mask` removes
1175         /// any high-order bits of `rhs` that would cause the shift to exceed the bitwidth of the type.
1176         ///
1177         /// Note that this is *not* the same as a rotate-left; the RHS of a wrapping shift-left is restricted to
1178         /// the range of the type, rather than the bits shifted out of the LHS being returned to the other end.
1179         /// The primitive integer types all implement a [`rotate_left`](Self::rotate_left) function,
1180         /// which may be what you want instead.
1181         ///
1182         /// # Examples
1183         ///
1184         /// Basic usage:
1185         ///
1186         /// ```
1187         #[doc = concat!("assert_eq!((-1", stringify!($SelfT), ").wrapping_shl(7), -128);")]
1188         #[doc = concat!("assert_eq!((-1", stringify!($SelfT), ").wrapping_shl(128), -1);")]
1189         /// ```
1190         #[stable(feature = "num_wrapping", since = "1.2.0")]
1191         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1192         #[must_use = "this returns the result of the operation, \
1193                       without modifying the original"]
1194         #[inline(always)]
1195         pub const fn wrapping_shl(self, rhs: u32) -> Self {
1196             // SAFETY: the masking by the bitsize of the type ensures that we do not shift
1197             // out of bounds
1198             unsafe {
1199                 intrinsics::unchecked_shl(self, (rhs & ($BITS - 1)) as $SelfT)
1200             }
1201         }
1202
1203         /// Panic-free bitwise shift-right; yields `self >> mask(rhs)`, where `mask`
1204         /// removes any high-order bits of `rhs` that would cause the shift to exceed the bitwidth of the type.
1205         ///
1206         /// Note that this is *not* the same as a rotate-right; the RHS of a wrapping shift-right is restricted
1207         /// to the range of the type, rather than the bits shifted out of the LHS being returned to the other
1208         /// end. The primitive integer types all implement a [`rotate_right`](Self::rotate_right) function,
1209         /// which may be what you want instead.
1210         ///
1211         /// # Examples
1212         ///
1213         /// Basic usage:
1214         ///
1215         /// ```
1216         #[doc = concat!("assert_eq!((-128", stringify!($SelfT), ").wrapping_shr(7), -1);")]
1217         /// assert_eq!((-128i16).wrapping_shr(64), -128);
1218         /// ```
1219         #[stable(feature = "num_wrapping", since = "1.2.0")]
1220         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1221         #[must_use = "this returns the result of the operation, \
1222                       without modifying the original"]
1223         #[inline(always)]
1224         pub const fn wrapping_shr(self, rhs: u32) -> Self {
1225             // SAFETY: the masking by the bitsize of the type ensures that we do not shift
1226             // out of bounds
1227             unsafe {
1228                 intrinsics::unchecked_shr(self, (rhs & ($BITS - 1)) as $SelfT)
1229             }
1230         }
1231
1232         /// Wrapping (modular) absolute value. Computes `self.abs()`, wrapping around at
1233         /// the boundary of the type.
1234         ///
1235         /// The only case where such wrapping can occur is when one takes the absolute value of the negative
1236         /// minimal value for the type; this is a positive value that is too large to represent in the type. In
1237         /// such a case, this function returns `MIN` itself.
1238         ///
1239         /// # Examples
1240         ///
1241         /// Basic usage:
1242         ///
1243         /// ```
1244         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_abs(), 100);")]
1245         #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").wrapping_abs(), 100);")]
1246         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.wrapping_abs(), ", stringify!($SelfT), "::MIN);")]
1247         /// assert_eq!((-128i8).wrapping_abs() as u8, 128);
1248         /// ```
1249         #[stable(feature = "no_panic_abs", since = "1.13.0")]
1250         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1251         #[allow(unused_attributes)]
1252         #[inline]
1253         pub const fn wrapping_abs(self) -> Self {
1254              if self.is_negative() {
1255                  self.wrapping_neg()
1256              } else {
1257                  self
1258              }
1259         }
1260
1261         /// Computes the absolute value of `self` without any wrapping
1262         /// or panicking.
1263         ///
1264         ///
1265         /// # Examples
1266         ///
1267         /// Basic usage:
1268         ///
1269         /// ```
1270         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".unsigned_abs(), 100", stringify!($UnsignedT), ");")]
1271         #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").unsigned_abs(), 100", stringify!($UnsignedT), ");")]
1272         /// assert_eq!((-128i8).unsigned_abs(), 128u8);
1273         /// ```
1274         #[stable(feature = "unsigned_abs", since = "1.51.0")]
1275         #[rustc_const_stable(feature = "unsigned_abs", since = "1.51.0")]
1276         #[inline]
1277         pub const fn unsigned_abs(self) -> $UnsignedT {
1278              self.wrapping_abs() as $UnsignedT
1279         }
1280
1281         /// Wrapping (modular) exponentiation. Computes `self.pow(exp)`,
1282         /// wrapping around at the boundary of the type.
1283         ///
1284         /// # Examples
1285         ///
1286         /// Basic usage:
1287         ///
1288         /// ```
1289         #[doc = concat!("assert_eq!(3", stringify!($SelfT), ".wrapping_pow(4), 81);")]
1290         /// assert_eq!(3i8.wrapping_pow(5), -13);
1291         /// assert_eq!(3i8.wrapping_pow(6), -39);
1292         /// ```
1293         #[stable(feature = "no_panic_pow", since = "1.34.0")]
1294         #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
1295         #[must_use = "this returns the result of the operation, \
1296                       without modifying the original"]
1297         #[inline]
1298         pub const fn wrapping_pow(self, mut exp: u32) -> Self {
1299             if exp == 0 {
1300                 return 1;
1301             }
1302             let mut base = self;
1303             let mut acc: Self = 1;
1304
1305             while exp > 1 {
1306                 if (exp & 1) == 1 {
1307                     acc = acc.wrapping_mul(base);
1308                 }
1309                 exp /= 2;
1310                 base = base.wrapping_mul(base);
1311             }
1312
1313             // since exp!=0, finally the exp must be 1.
1314             // Deal with the final bit of the exponent separately, since
1315             // squaring the base afterwards is not necessary and may cause a
1316             // needless overflow.
1317             acc.wrapping_mul(base)
1318         }
1319
1320         /// Calculates `self` + `rhs`
1321         ///
1322         /// Returns a tuple of the addition along with a boolean indicating whether an arithmetic overflow would
1323         /// occur. If an overflow would have occurred then the wrapped value is returned.
1324         ///
1325         /// # Examples
1326         ///
1327         /// Basic usage:
1328         ///
1329         /// ```
1330         ///
1331         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_add(2), (7, false));")]
1332         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.overflowing_add(1), (", stringify!($SelfT), "::MIN, true));")]
1333         /// ```
1334         #[stable(feature = "wrapping", since = "1.7.0")]
1335         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1336         #[must_use = "this returns the result of the operation, \
1337                       without modifying the original"]
1338         #[inline(always)]
1339         pub const fn overflowing_add(self, rhs: Self) -> (Self, bool) {
1340             let (a, b) = intrinsics::add_with_overflow(self as $ActualT, rhs as $ActualT);
1341             (a as Self, b)
1342         }
1343
1344         /// Calculates `self + rhs + carry` without the ability to overflow.
1345         ///
1346         /// Performs "ternary addition" which takes in an extra bit to add, and may return an
1347         /// additional bit of overflow. This allows for chaining together multiple additions
1348         /// to create "big integers" which represent larger values.
1349         ///
1350         /// # Examples
1351         ///
1352         /// Basic usage
1353         ///
1354         /// ```
1355         /// #![feature(bigint_helper_methods)]
1356         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".carrying_add(2, false), (7, false));")]
1357         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".carrying_add(2, true), (8, false));")]
1358         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.carrying_add(1, false), (", stringify!($SelfT), "::MIN, false));")]
1359         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.carrying_add(1, true), (", stringify!($SelfT), "::MIN + 1, false));")]
1360         /// ```
1361         #[unstable(feature = "bigint_helper_methods", issue = "85532")]
1362         #[rustc_const_unstable(feature = "const_bigint_helper_methods", issue = "85532")]
1363         #[must_use = "this returns the result of the operation, \
1364                       without modifying the original"]
1365         #[inline]
1366         pub const fn carrying_add(self, rhs: Self, carry: bool) -> (Self, bool) {
1367             let (sum, carry) = (self as $UnsignedT).carrying_add(rhs as $UnsignedT, carry);
1368             (sum as $SelfT, carry)
1369         }
1370
1371         /// Calculates `self` - `rhs`
1372         ///
1373         /// Returns a tuple of the subtraction along with a boolean indicating whether an arithmetic overflow
1374         /// would occur. If an overflow would have occurred then the wrapped value is returned.
1375         ///
1376         /// # Examples
1377         ///
1378         /// Basic usage:
1379         ///
1380         /// ```
1381         ///
1382         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_sub(2), (3, false));")]
1383         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_sub(1), (", stringify!($SelfT), "::MAX, true));")]
1384         /// ```
1385         #[stable(feature = "wrapping", since = "1.7.0")]
1386         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1387         #[must_use = "this returns the result of the operation, \
1388                       without modifying the original"]
1389         #[inline(always)]
1390         pub const fn overflowing_sub(self, rhs: Self) -> (Self, bool) {
1391             let (a, b) = intrinsics::sub_with_overflow(self as $ActualT, rhs as $ActualT);
1392             (a as Self, b)
1393         }
1394
1395         /// Calculates `self - rhs - borrow` without the ability to overflow.
1396         ///
1397         /// Performs "ternary subtraction" which takes in an extra bit to subtract, and may return
1398         /// an additional bit of overflow. This allows for chaining together multiple subtractions
1399         /// to create "big integers" which represent larger values.
1400         ///
1401         /// # Examples
1402         ///
1403         /// Basic usage
1404         ///
1405         /// ```
1406         /// #![feature(bigint_helper_methods)]
1407         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".borrowing_sub(2, false), (3, false));")]
1408         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".borrowing_sub(2, true), (2, false));")]
1409         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.borrowing_sub(1, false), (", stringify!($SelfT), "::MAX, false));")]
1410         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.borrowing_sub(1, true), (", stringify!($SelfT), "::MAX - 1, false));")]
1411         /// ```
1412         #[unstable(feature = "bigint_helper_methods", issue = "85532")]
1413         #[rustc_const_unstable(feature = "const_bigint_helper_methods", issue = "85532")]
1414         #[must_use = "this returns the result of the operation, \
1415                       without modifying the original"]
1416         #[inline]
1417         pub const fn borrowing_sub(self, rhs: Self, borrow: bool) -> (Self, bool) {
1418             let (sum, borrow) = (self as $UnsignedT).borrowing_sub(rhs as $UnsignedT, borrow);
1419             (sum as $SelfT, borrow)
1420         }
1421
1422         /// Calculates the multiplication of `self` and `rhs`.
1423         ///
1424         /// Returns a tuple of the multiplication along with a boolean indicating whether an arithmetic overflow
1425         /// would occur. If an overflow would have occurred then the wrapped value is returned.
1426         ///
1427         /// # Examples
1428         ///
1429         /// Basic usage:
1430         ///
1431         /// ```
1432         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_mul(2), (10, false));")]
1433         /// assert_eq!(1_000_000_000i32.overflowing_mul(10), (1410065408, true));
1434         /// ```
1435         #[stable(feature = "wrapping", since = "1.7.0")]
1436         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1437         #[must_use = "this returns the result of the operation, \
1438                       without modifying the original"]
1439         #[inline(always)]
1440         pub const fn overflowing_mul(self, rhs: Self) -> (Self, bool) {
1441             let (a, b) = intrinsics::mul_with_overflow(self as $ActualT, rhs as $ActualT);
1442             (a as Self, b)
1443         }
1444
1445         /// Calculates the divisor when `self` is divided by `rhs`.
1446         ///
1447         /// Returns a tuple of the divisor along with a boolean indicating whether an arithmetic overflow would
1448         /// occur. If an overflow would occur then self is returned.
1449         ///
1450         /// # Panics
1451         ///
1452         /// This function will panic if `rhs` is 0.
1453         ///
1454         /// # Examples
1455         ///
1456         /// Basic usage:
1457         ///
1458         /// ```
1459         ///
1460         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_div(2), (2, false));")]
1461         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_div(-1), (", stringify!($SelfT), "::MIN, true));")]
1462         /// ```
1463         #[inline]
1464         #[stable(feature = "wrapping", since = "1.7.0")]
1465         #[rustc_const_stable(feature = "const_overflowing_int_methods", since = "1.52.0")]
1466         #[must_use = "this returns the result of the operation, \
1467                       without modifying the original"]
1468         pub const fn overflowing_div(self, rhs: Self) -> (Self, bool) {
1469             if unlikely!(self == Self::MIN && rhs == -1) {
1470                 (self, true)
1471             } else {
1472                 (self / rhs, false)
1473             }
1474         }
1475
1476         /// Calculates the quotient of Euclidean division `self.div_euclid(rhs)`.
1477         ///
1478         /// Returns a tuple of the divisor along with a boolean indicating whether an arithmetic overflow would
1479         /// occur. If an overflow would occur then `self` is returned.
1480         ///
1481         /// # Panics
1482         ///
1483         /// This function will panic if `rhs` is 0.
1484         ///
1485         /// # Examples
1486         ///
1487         /// Basic usage:
1488         ///
1489         /// ```
1490         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_div_euclid(2), (2, false));")]
1491         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_div_euclid(-1), (", stringify!($SelfT), "::MIN, true));")]
1492         /// ```
1493         #[inline]
1494         #[stable(feature = "euclidean_division", since = "1.38.0")]
1495         #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
1496         #[must_use = "this returns the result of the operation, \
1497                       without modifying the original"]
1498         pub const fn overflowing_div_euclid(self, rhs: Self) -> (Self, bool) {
1499             if unlikely!(self == Self::MIN && rhs == -1) {
1500                 (self, true)
1501             } else {
1502                 (self.div_euclid(rhs), false)
1503             }
1504         }
1505
1506         /// Calculates the remainder when `self` is divided by `rhs`.
1507         ///
1508         /// Returns a tuple of the remainder after dividing along with a boolean indicating whether an
1509         /// arithmetic overflow would occur. If an overflow would occur then 0 is returned.
1510         ///
1511         /// # Panics
1512         ///
1513         /// This function will panic if `rhs` is 0.
1514         ///
1515         /// # Examples
1516         ///
1517         /// Basic usage:
1518         ///
1519         /// ```
1520         ///
1521         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_rem(2), (1, false));")]
1522         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_rem(-1), (0, true));")]
1523         /// ```
1524         #[inline]
1525         #[stable(feature = "wrapping", since = "1.7.0")]
1526         #[rustc_const_stable(feature = "const_overflowing_int_methods", since = "1.52.0")]
1527         #[must_use = "this returns the result of the operation, \
1528                       without modifying the original"]
1529         pub const fn overflowing_rem(self, rhs: Self) -> (Self, bool) {
1530             if unlikely!(self == Self::MIN && rhs == -1) {
1531                 (0, true)
1532             } else {
1533                 (self % rhs, false)
1534             }
1535         }
1536
1537
1538         /// Overflowing Euclidean remainder. Calculates `self.rem_euclid(rhs)`.
1539         ///
1540         /// Returns a tuple of the remainder after dividing along with a boolean indicating whether an
1541         /// arithmetic overflow would occur. If an overflow would occur then 0 is returned.
1542         ///
1543         /// # Panics
1544         ///
1545         /// This function will panic if `rhs` is 0.
1546         ///
1547         /// # Examples
1548         ///
1549         /// Basic usage:
1550         ///
1551         /// ```
1552         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_rem_euclid(2), (1, false));")]
1553         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_rem_euclid(-1), (0, true));")]
1554         /// ```
1555         #[stable(feature = "euclidean_division", since = "1.38.0")]
1556         #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
1557         #[must_use = "this returns the result of the operation, \
1558                       without modifying the original"]
1559         #[inline]
1560         pub const fn overflowing_rem_euclid(self, rhs: Self) -> (Self, bool) {
1561             if unlikely!(self == Self::MIN && rhs == -1) {
1562                 (0, true)
1563             } else {
1564                 (self.rem_euclid(rhs), false)
1565             }
1566         }
1567
1568
1569         /// Negates self, overflowing if this is equal to the minimum value.
1570         ///
1571         /// Returns a tuple of the negated version of self along with a boolean indicating whether an overflow
1572         /// happened. If `self` is the minimum value (e.g., `i32::MIN` for values of type `i32`), then the
1573         /// minimum value will be returned again and `true` will be returned for an overflow happening.
1574         ///
1575         /// # Examples
1576         ///
1577         /// Basic usage:
1578         ///
1579         /// ```
1580         #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".overflowing_neg(), (-2, false));")]
1581         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_neg(), (", stringify!($SelfT), "::MIN, true));")]
1582         /// ```
1583         #[inline]
1584         #[stable(feature = "wrapping", since = "1.7.0")]
1585         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1586         #[allow(unused_attributes)]
1587         pub const fn overflowing_neg(self) -> (Self, bool) {
1588             if unlikely!(self == Self::MIN) {
1589                 (Self::MIN, true)
1590             } else {
1591                 (-self, false)
1592             }
1593         }
1594
1595         /// Shifts self left by `rhs` bits.
1596         ///
1597         /// Returns a tuple of the shifted version of self along with a boolean indicating whether the shift
1598         /// value was larger than or equal to the number of bits. If the shift value is too large, then value is
1599         /// masked (N-1) where N is the number of bits, and this value is then used to perform the shift.
1600         ///
1601         /// # Examples
1602         ///
1603         /// Basic usage:
1604         ///
1605         /// ```
1606         #[doc = concat!("assert_eq!(0x1", stringify!($SelfT),".overflowing_shl(4), (0x10, false));")]
1607         /// assert_eq!(0x1i32.overflowing_shl(36), (0x10, true));
1608         /// ```
1609         #[stable(feature = "wrapping", since = "1.7.0")]
1610         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1611         #[must_use = "this returns the result of the operation, \
1612                       without modifying the original"]
1613         #[inline]
1614         pub const fn overflowing_shl(self, rhs: u32) -> (Self, bool) {
1615             (self.wrapping_shl(rhs), (rhs > ($BITS - 1)))
1616         }
1617
1618         /// Shifts self right by `rhs` bits.
1619         ///
1620         /// Returns a tuple of the shifted version of self along with a boolean indicating whether the shift
1621         /// value was larger than or equal to the number of bits. If the shift value is too large, then value is
1622         /// masked (N-1) where N is the number of bits, and this value is then used to perform the shift.
1623         ///
1624         /// # Examples
1625         ///
1626         /// Basic usage:
1627         ///
1628         /// ```
1629         #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".overflowing_shr(4), (0x1, false));")]
1630         /// assert_eq!(0x10i32.overflowing_shr(36), (0x1, true));
1631         /// ```
1632         #[stable(feature = "wrapping", since = "1.7.0")]
1633         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1634         #[must_use = "this returns the result of the operation, \
1635                       without modifying the original"]
1636         #[inline]
1637         pub const fn overflowing_shr(self, rhs: u32) -> (Self, bool) {
1638             (self.wrapping_shr(rhs), (rhs > ($BITS - 1)))
1639         }
1640
1641         /// Computes the absolute value of `self`.
1642         ///
1643         /// Returns a tuple of the absolute version of self along with a boolean indicating whether an overflow
1644         /// happened. If self is the minimum value
1645         #[doc = concat!("(e.g., ", stringify!($SelfT), "::MIN for values of type ", stringify!($SelfT), "),")]
1646         /// then the minimum value will be returned again and true will be returned
1647         /// for an overflow happening.
1648         ///
1649         /// # Examples
1650         ///
1651         /// Basic usage:
1652         ///
1653         /// ```
1654         #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".overflowing_abs(), (10, false));")]
1655         #[doc = concat!("assert_eq!((-10", stringify!($SelfT), ").overflowing_abs(), (10, false));")]
1656         #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN).overflowing_abs(), (", stringify!($SelfT), "::MIN, true));")]
1657         /// ```
1658         #[stable(feature = "no_panic_abs", since = "1.13.0")]
1659         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
1660         #[inline]
1661         pub const fn overflowing_abs(self) -> (Self, bool) {
1662             (self.wrapping_abs(), self == Self::MIN)
1663         }
1664
1665         /// Raises self to the power of `exp`, using exponentiation by squaring.
1666         ///
1667         /// Returns a tuple of the exponentiation along with a bool indicating
1668         /// whether an overflow happened.
1669         ///
1670         /// # Examples
1671         ///
1672         /// Basic usage:
1673         ///
1674         /// ```
1675         #[doc = concat!("assert_eq!(3", stringify!($SelfT), ".overflowing_pow(4), (81, false));")]
1676         /// assert_eq!(3i8.overflowing_pow(5), (-13, true));
1677         /// ```
1678         #[stable(feature = "no_panic_pow", since = "1.34.0")]
1679         #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
1680         #[must_use = "this returns the result of the operation, \
1681                       without modifying the original"]
1682         #[inline]
1683         pub const fn overflowing_pow(self, mut exp: u32) -> (Self, bool) {
1684             if exp == 0 {
1685                 return (1,false);
1686             }
1687             let mut base = self;
1688             let mut acc: Self = 1;
1689             let mut overflown = false;
1690             // Scratch space for storing results of overflowing_mul.
1691             let mut r;
1692
1693             while exp > 1 {
1694                 if (exp & 1) == 1 {
1695                     r = acc.overflowing_mul(base);
1696                     acc = r.0;
1697                     overflown |= r.1;
1698                 }
1699                 exp /= 2;
1700                 r = base.overflowing_mul(base);
1701                 base = r.0;
1702                 overflown |= r.1;
1703             }
1704
1705             // since exp!=0, finally the exp must be 1.
1706             // Deal with the final bit of the exponent separately, since
1707             // squaring the base afterwards is not necessary and may cause a
1708             // needless overflow.
1709             r = acc.overflowing_mul(base);
1710             r.1 |= overflown;
1711             r
1712         }
1713
1714         /// Raises self to the power of `exp`, using exponentiation by squaring.
1715         ///
1716         /// # Examples
1717         ///
1718         /// Basic usage:
1719         ///
1720         /// ```
1721         #[doc = concat!("let x: ", stringify!($SelfT), " = 2; // or any other integer type")]
1722         ///
1723         /// assert_eq!(x.pow(5), 32);
1724         /// ```
1725         #[stable(feature = "rust1", since = "1.0.0")]
1726         #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
1727         #[must_use = "this returns the result of the operation, \
1728                       without modifying the original"]
1729         #[inline]
1730         #[rustc_inherit_overflow_checks]
1731         pub const fn pow(self, mut exp: u32) -> Self {
1732             if exp == 0 {
1733                 return 1;
1734             }
1735             let mut base = self;
1736             let mut acc = 1;
1737
1738             while exp > 1 {
1739                 if (exp & 1) == 1 {
1740                     acc = acc * base;
1741                 }
1742                 exp /= 2;
1743                 base = base * base;
1744             }
1745
1746             // since exp!=0, finally the exp must be 1.
1747             // Deal with the final bit of the exponent separately, since
1748             // squaring the base afterwards is not necessary and may cause a
1749             // needless overflow.
1750             acc * base
1751         }
1752
1753         /// Calculates the quotient of Euclidean division of `self` by `rhs`.
1754         ///
1755         /// This computes the integer `q` such that `self = q * rhs + r`, with
1756         /// `r = self.rem_euclid(rhs)` and `0 <= r < abs(rhs)`.
1757         ///
1758         /// In other words, the result is `self / rhs` rounded to the integer `q`
1759         /// such that `self >= q * rhs`.
1760         /// If `self > 0`, this is equal to round towards zero (the default in Rust);
1761         /// if `self < 0`, this is equal to round towards +/- infinity.
1762         ///
1763         /// # Panics
1764         ///
1765         /// This function will panic if `rhs` is 0 or the division results in overflow.
1766         ///
1767         /// # Examples
1768         ///
1769         /// Basic usage:
1770         ///
1771         /// ```
1772         #[doc = concat!("let a: ", stringify!($SelfT), " = 7; // or any other integer type")]
1773         /// let b = 4;
1774         ///
1775         /// assert_eq!(a.div_euclid(b), 1); // 7 >= 4 * 1
1776         /// assert_eq!(a.div_euclid(-b), -1); // 7 >= -4 * -1
1777         /// assert_eq!((-a).div_euclid(b), -2); // -7 >= 4 * -2
1778         /// assert_eq!((-a).div_euclid(-b), 2); // -7 >= -4 * 2
1779         /// ```
1780         #[stable(feature = "euclidean_division", since = "1.38.0")]
1781         #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
1782         #[must_use = "this returns the result of the operation, \
1783                       without modifying the original"]
1784         #[inline]
1785         #[rustc_inherit_overflow_checks]
1786         pub const fn div_euclid(self, rhs: Self) -> Self {
1787             let q = self / rhs;
1788             if self % rhs < 0 {
1789                 return if rhs > 0 { q - 1 } else { q + 1 }
1790             }
1791             q
1792         }
1793
1794
1795         /// Calculates the least nonnegative remainder of `self (mod rhs)`.
1796         ///
1797         /// This is done as if by the Euclidean division algorithm -- given
1798         /// `r = self.rem_euclid(rhs)`, `self = rhs * self.div_euclid(rhs) + r`, and
1799         /// `0 <= r < abs(rhs)`.
1800         ///
1801         /// # Panics
1802         ///
1803         /// This function will panic if `rhs` is 0 or the division results in overflow.
1804         ///
1805         /// # Examples
1806         ///
1807         /// Basic usage:
1808         ///
1809         /// ```
1810         #[doc = concat!("let a: ", stringify!($SelfT), " = 7; // or any other integer type")]
1811         /// let b = 4;
1812         ///
1813         /// assert_eq!(a.rem_euclid(b), 3);
1814         /// assert_eq!((-a).rem_euclid(b), 1);
1815         /// assert_eq!(a.rem_euclid(-b), 3);
1816         /// assert_eq!((-a).rem_euclid(-b), 1);
1817         /// ```
1818         #[stable(feature = "euclidean_division", since = "1.38.0")]
1819         #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
1820         #[must_use = "this returns the result of the operation, \
1821                       without modifying the original"]
1822         #[inline]
1823         #[rustc_inherit_overflow_checks]
1824         pub const fn rem_euclid(self, rhs: Self) -> Self {
1825             let r = self % rhs;
1826             if r < 0 {
1827                 if rhs < 0 {
1828                     r - rhs
1829                 } else {
1830                     r + rhs
1831                 }
1832             } else {
1833                 r
1834             }
1835         }
1836
1837         /// Calculates the quotient of `self` and `rhs`, rounding the result towards negative infinity.
1838         ///
1839         /// # Panics
1840         ///
1841         /// This function will panic if `rhs` is 0 or the division results in overflow.
1842         ///
1843         /// # Examples
1844         ///
1845         /// Basic usage:
1846         ///
1847         /// ```
1848         /// #![feature(int_roundings)]
1849         #[doc = concat!("let a: ", stringify!($SelfT)," = 8;")]
1850         /// let b = 3;
1851         ///
1852         /// assert_eq!(a.div_floor(b), 2);
1853         /// assert_eq!(a.div_floor(-b), -3);
1854         /// assert_eq!((-a).div_floor(b), -3);
1855         /// assert_eq!((-a).div_floor(-b), 2);
1856         /// ```
1857         #[unstable(feature = "int_roundings", issue = "88581")]
1858         #[must_use = "this returns the result of the operation, \
1859                       without modifying the original"]
1860         #[inline]
1861         #[rustc_inherit_overflow_checks]
1862         pub const fn div_floor(self, rhs: Self) -> Self {
1863             let d = self / rhs;
1864             let r = self % rhs;
1865             if (r > 0 && rhs < 0) || (r < 0 && rhs > 0) {
1866                 d - 1
1867             } else {
1868                 d
1869             }
1870         }
1871
1872         /// Calculates the quotient of `self` and `rhs`, rounding the result towards positive infinity.
1873         ///
1874         /// # Panics
1875         ///
1876         /// This function will panic if `rhs` is 0 or the division results in overflow.
1877         ///
1878         /// # Examples
1879         ///
1880         /// Basic usage:
1881         ///
1882         /// ```
1883         /// #![feature(int_roundings)]
1884         #[doc = concat!("let a: ", stringify!($SelfT)," = 8;")]
1885         /// let b = 3;
1886         ///
1887         /// assert_eq!(a.div_ceil(b), 3);
1888         /// assert_eq!(a.div_ceil(-b), -2);
1889         /// assert_eq!((-a).div_ceil(b), -2);
1890         /// assert_eq!((-a).div_ceil(-b), 3);
1891         /// ```
1892         #[unstable(feature = "int_roundings", issue = "88581")]
1893         #[must_use = "this returns the result of the operation, \
1894                       without modifying the original"]
1895         #[inline]
1896         #[rustc_inherit_overflow_checks]
1897         pub const fn div_ceil(self, rhs: Self) -> Self {
1898             let d = self / rhs;
1899             let r = self % rhs;
1900             if (r > 0 && rhs > 0) || (r < 0 && rhs < 0) {
1901                 d + 1
1902             } else {
1903                 d
1904             }
1905         }
1906
1907         /// If `rhs` is positive, calculates the smallest value greater than or
1908         /// equal to `self` that is a multiple of `rhs`. If `rhs` is negative,
1909         /// calculates the largest value less than or equal to `self` that is a
1910         /// multiple of `rhs`.
1911         ///
1912         /// # Panics
1913         ///
1914         /// This function will panic if `rhs` is 0 or the operation results in overflow.
1915         ///
1916         /// # Examples
1917         ///
1918         /// Basic usage:
1919         ///
1920         /// ```
1921         /// #![feature(int_roundings)]
1922         #[doc = concat!("assert_eq!(16_", stringify!($SelfT), ".next_multiple_of(8), 16);")]
1923         #[doc = concat!("assert_eq!(23_", stringify!($SelfT), ".next_multiple_of(8), 24);")]
1924         #[doc = concat!("assert_eq!(16_", stringify!($SelfT), ".next_multiple_of(-8), 16);")]
1925         #[doc = concat!("assert_eq!(23_", stringify!($SelfT), ".next_multiple_of(-8), 16);")]
1926         #[doc = concat!("assert_eq!((-16_", stringify!($SelfT), ").next_multiple_of(8), -16);")]
1927         #[doc = concat!("assert_eq!((-23_", stringify!($SelfT), ").next_multiple_of(8), -16);")]
1928         #[doc = concat!("assert_eq!((-16_", stringify!($SelfT), ").next_multiple_of(-8), -16);")]
1929         #[doc = concat!("assert_eq!((-23_", stringify!($SelfT), ").next_multiple_of(-8), -24);")]
1930         /// ```
1931         #[unstable(feature = "int_roundings", issue = "88581")]
1932         #[must_use = "this returns the result of the operation, \
1933                       without modifying the original"]
1934         #[inline]
1935         #[rustc_inherit_overflow_checks]
1936         pub const fn next_multiple_of(self, rhs: Self) -> Self {
1937             // This would otherwise fail when calculating `r` when self == T::MIN.
1938             if rhs == -1 {
1939                 return self;
1940             }
1941
1942             let r = self % rhs;
1943             let m = if (r > 0 && rhs < 0) || (r < 0 && rhs > 0) {
1944                 r + rhs
1945             } else {
1946                 r
1947             };
1948
1949             if m == 0 {
1950                 self
1951             } else {
1952                 self + (rhs - m)
1953             }
1954         }
1955
1956         /// If `rhs` is positive, calculates the smallest value greater than or
1957         /// equal to `self` that is a multiple of `rhs`. If `rhs` is negative,
1958         /// calculates the largest value less than or equal to `self` that is a
1959         /// multiple of `rhs`. Returns `None` if `rhs` is zero or the operation
1960         /// would result in overflow.
1961         ///
1962         /// # Examples
1963         ///
1964         /// Basic usage:
1965         ///
1966         /// ```
1967         /// #![feature(int_roundings)]
1968         #[doc = concat!("assert_eq!(16_", stringify!($SelfT), ".checked_next_multiple_of(8), Some(16));")]
1969         #[doc = concat!("assert_eq!(23_", stringify!($SelfT), ".checked_next_multiple_of(8), Some(24));")]
1970         #[doc = concat!("assert_eq!(16_", stringify!($SelfT), ".checked_next_multiple_of(-8), Some(16));")]
1971         #[doc = concat!("assert_eq!(23_", stringify!($SelfT), ".checked_next_multiple_of(-8), Some(16));")]
1972         #[doc = concat!("assert_eq!((-16_", stringify!($SelfT), ").checked_next_multiple_of(8), Some(-16));")]
1973         #[doc = concat!("assert_eq!((-23_", stringify!($SelfT), ").checked_next_multiple_of(8), Some(-16));")]
1974         #[doc = concat!("assert_eq!((-16_", stringify!($SelfT), ").checked_next_multiple_of(-8), Some(-16));")]
1975         #[doc = concat!("assert_eq!((-23_", stringify!($SelfT), ").checked_next_multiple_of(-8), Some(-24));")]
1976         #[doc = concat!("assert_eq!(1_", stringify!($SelfT), ".checked_next_multiple_of(0), None);")]
1977         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_next_multiple_of(2), None);")]
1978         /// ```
1979         #[unstable(feature = "int_roundings", issue = "88581")]
1980         #[must_use = "this returns the result of the operation, \
1981                       without modifying the original"]
1982         #[inline]
1983         #[rustc_inherit_overflow_checks]
1984         pub const fn checked_next_multiple_of(self, rhs: Self) -> Option<Self> {
1985             // This would otherwise fail when calculating `r` when self == T::MIN.
1986             if rhs == -1 {
1987                 return Some(self);
1988             }
1989
1990             let r = try_opt!(self.checked_rem(rhs));
1991             let m = if (r > 0 && rhs < 0) || (r < 0 && rhs > 0) {
1992                 try_opt!(r.checked_add(rhs))
1993             } else {
1994                 r
1995             };
1996
1997             if m == 0 {
1998                 Some(self)
1999             } else {
2000                 self.checked_add(try_opt!(rhs.checked_sub(m)))
2001             }
2002         }
2003
2004         /// Returns the logarithm of the number with respect to an arbitrary base.
2005         ///
2006         /// This method might not be optimized owing to implementation details;
2007         /// `log2` can produce results more efficiently for base 2, and `log10`
2008         /// can produce results more efficiently for base 10.
2009         ///
2010         /// # Panics
2011         ///
2012         /// When the number is zero, or if the base is not at least 2; it
2013         /// panics in debug mode and the return value is wrapped to 0 in release
2014         /// mode (the only situation in which the method can return 0).
2015         ///
2016         /// # Examples
2017         ///
2018         /// ```
2019         /// #![feature(int_log)]
2020         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".log(5), 1);")]
2021         /// ```
2022         #[unstable(feature = "int_log", issue = "70887")]
2023         #[must_use = "this returns the result of the operation, \
2024                         without modifying the original"]
2025         #[inline]
2026         #[track_caller]
2027         #[rustc_inherit_overflow_checks]
2028         #[allow(arithmetic_overflow)]
2029         pub const fn log(self, base: Self) -> u32 {
2030             match self.checked_log(base) {
2031                 Some(n) => n,
2032                 None => {
2033                     // In debug builds, trigger a panic on None.
2034                     // This should optimize completely out in release builds.
2035                     let _ = Self::MAX + 1;
2036
2037                     0
2038                 },
2039             }
2040         }
2041
2042         /// Returns the base 2 logarithm of the number.
2043         ///
2044         /// # Panics
2045         ///
2046         /// When the number is zero it panics in debug mode and the return value
2047         /// is wrapped to 0 in release mode (the only situation in which the
2048         /// method can return 0).
2049         ///
2050         /// # Examples
2051         ///
2052         /// ```
2053         /// #![feature(int_log)]
2054         #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".log2(), 1);")]
2055         /// ```
2056         #[unstable(feature = "int_log", issue = "70887")]
2057         #[must_use = "this returns the result of the operation, \
2058                         without modifying the original"]
2059         #[inline]
2060         #[track_caller]
2061         #[rustc_inherit_overflow_checks]
2062         #[allow(arithmetic_overflow)]
2063         pub const fn log2(self) -> u32 {
2064             match self.checked_log2() {
2065                 Some(n) => n,
2066                 None => {
2067                     // In debug builds, trigger a panic on None.
2068                     // This should optimize completely out in release builds.
2069                     let _ = Self::MAX + 1;
2070
2071                     0
2072                 },
2073             }
2074         }
2075
2076         /// Returns the base 10 logarithm of the number.
2077         ///
2078         /// # Panics
2079         ///
2080         /// When the number is zero it panics in debug mode and the return value
2081         /// is wrapped to 0 in release mode (the only situation in which the
2082         /// method can return 0).
2083         ///
2084         /// # Example
2085         ///
2086         /// ```
2087         /// #![feature(int_log)]
2088         #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".log10(), 1);")]
2089         /// ```
2090         #[unstable(feature = "int_log", issue = "70887")]
2091         #[must_use = "this returns the result of the operation, \
2092                         without modifying the original"]
2093         #[inline]
2094         #[track_caller]
2095         #[rustc_inherit_overflow_checks]
2096         #[allow(arithmetic_overflow)]
2097         pub const fn log10(self) -> u32 {
2098             match self.checked_log10() {
2099                 Some(n) => n,
2100                 None => {
2101                     // In debug builds, trigger a panic on None.
2102                     // This should optimize completely out in release builds.
2103                     let _ = Self::MAX + 1;
2104
2105                     0
2106                 },
2107             }
2108         }
2109
2110         /// Returns the logarithm of the number with respect to an arbitrary base.
2111         ///
2112         /// Returns `None` if the number is negative or zero, or if the base is not at least 2.
2113         ///
2114         /// This method might not be optimized owing to implementation details;
2115         /// `checked_log2` can produce results more efficiently for base 2, and
2116         /// `checked_log10` can produce results more efficiently for base 10.
2117         ///
2118         /// # Examples
2119         ///
2120         /// ```
2121         /// #![feature(int_log)]
2122         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_log(5), Some(1));")]
2123         /// ```
2124         #[unstable(feature = "int_log", issue = "70887")]
2125         #[must_use = "this returns the result of the operation, \
2126                         without modifying the original"]
2127         #[inline]
2128         pub const fn checked_log(self, base: Self) -> Option<u32> {
2129             if self <= 0 || base <= 1 {
2130                 None
2131             } else {
2132                 let mut n = 0;
2133                 let mut r = self;
2134
2135                 // Optimization for 128 bit wide integers.
2136                 if Self::BITS == 128 {
2137                     let b = Self::log2(self) / (Self::log2(base) + 1);
2138                     n += b;
2139                     r /= base.pow(b as u32);
2140                 }
2141
2142                 while r >= base {
2143                     r /= base;
2144                     n += 1;
2145                 }
2146                 Some(n)
2147             }
2148         }
2149
2150         /// Returns the base 2 logarithm of the number.
2151         ///
2152         /// Returns `None` if the number is negative or zero.
2153         ///
2154         /// # Examples
2155         ///
2156         /// ```
2157         /// #![feature(int_log)]
2158         #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".checked_log2(), Some(1));")]
2159         /// ```
2160         #[unstable(feature = "int_log", issue = "70887")]
2161         #[must_use = "this returns the result of the operation, \
2162                         without modifying the original"]
2163         #[inline]
2164         pub const fn checked_log2(self) -> Option<u32> {
2165             if self <= 0 {
2166                 None
2167             } else {
2168                 // SAFETY: We just checked that this number is positive
2169                 let log = (Self::BITS - 1) - unsafe { intrinsics::ctlz_nonzero(self) as u32 };
2170                 Some(log)
2171             }
2172         }
2173
2174         /// Returns the base 10 logarithm of the number.
2175         ///
2176         /// Returns `None` if the number is negative or zero.
2177         ///
2178         /// # Example
2179         ///
2180         /// ```
2181         /// #![feature(int_log)]
2182         #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".checked_log10(), Some(1));")]
2183         /// ```
2184         #[unstable(feature = "int_log", issue = "70887")]
2185         #[must_use = "this returns the result of the operation, \
2186                         without modifying the original"]
2187         #[inline]
2188         pub const fn checked_log10(self) -> Option<u32> {
2189             int_log10::$ActualT(self as $ActualT)
2190         }
2191
2192         /// Computes the absolute value of `self`.
2193         ///
2194         /// # Overflow behavior
2195         ///
2196         /// The absolute value of
2197         #[doc = concat!("`", stringify!($SelfT), "::MIN`")]
2198         /// cannot be represented as an
2199         #[doc = concat!("`", stringify!($SelfT), "`,")]
2200         /// and attempting to calculate it will cause an overflow. This means
2201         /// that code in debug mode will trigger a panic on this case and
2202         /// optimized code will return
2203         #[doc = concat!("`", stringify!($SelfT), "::MIN`")]
2204         /// without a panic.
2205         ///
2206         /// # Examples
2207         ///
2208         /// Basic usage:
2209         ///
2210         /// ```
2211         #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".abs(), 10);")]
2212         #[doc = concat!("assert_eq!((-10", stringify!($SelfT), ").abs(), 10);")]
2213         /// ```
2214         #[stable(feature = "rust1", since = "1.0.0")]
2215         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
2216         #[allow(unused_attributes)]
2217         #[inline]
2218         #[rustc_inherit_overflow_checks]
2219         pub const fn abs(self) -> Self {
2220             // Note that the #[rustc_inherit_overflow_checks] and #[inline]
2221             // above mean that the overflow semantics of the subtraction
2222             // depend on the crate we're being called from.
2223             if self.is_negative() {
2224                 -self
2225             } else {
2226                 self
2227             }
2228         }
2229
2230         /// Returns a number representing sign of `self`.
2231         ///
2232         ///  - `0` if the number is zero
2233         ///  - `1` if the number is positive
2234         ///  - `-1` if the number is negative
2235         ///
2236         /// # Examples
2237         ///
2238         /// Basic usage:
2239         ///
2240         /// ```
2241         #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".signum(), 1);")]
2242         #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".signum(), 0);")]
2243         #[doc = concat!("assert_eq!((-10", stringify!($SelfT), ").signum(), -1);")]
2244         /// ```
2245         #[stable(feature = "rust1", since = "1.0.0")]
2246         #[rustc_const_stable(feature = "const_int_sign", since = "1.47.0")]
2247         #[inline(always)]
2248         pub const fn signum(self) -> Self {
2249             match self {
2250                 n if n > 0 =>  1,
2251                 0          =>  0,
2252                 _          => -1,
2253             }
2254         }
2255
2256         /// Returns `true` if `self` is positive and `false` if the number is zero or
2257         /// negative.
2258         ///
2259         /// # Examples
2260         ///
2261         /// Basic usage:
2262         ///
2263         /// ```
2264         #[doc = concat!("assert!(10", stringify!($SelfT), ".is_positive());")]
2265         #[doc = concat!("assert!(!(-10", stringify!($SelfT), ").is_positive());")]
2266         /// ```
2267         #[stable(feature = "rust1", since = "1.0.0")]
2268         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
2269         #[inline(always)]
2270         pub const fn is_positive(self) -> bool { self > 0 }
2271
2272         /// Returns `true` if `self` is negative and `false` if the number is zero or
2273         /// positive.
2274         ///
2275         /// # Examples
2276         ///
2277         /// Basic usage:
2278         ///
2279         /// ```
2280         #[doc = concat!("assert!((-10", stringify!($SelfT), ").is_negative());")]
2281         #[doc = concat!("assert!(!10", stringify!($SelfT), ".is_negative());")]
2282         /// ```
2283         #[stable(feature = "rust1", since = "1.0.0")]
2284         #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")]
2285         #[inline(always)]
2286         pub const fn is_negative(self) -> bool { self < 0 }
2287
2288         /// Return the memory representation of this integer as a byte array in
2289         /// big-endian (network) byte order.
2290         ///
2291         #[doc = $to_xe_bytes_doc]
2292         ///
2293         /// # Examples
2294         ///
2295         /// ```
2296         #[doc = concat!("let bytes = ", $swap_op, stringify!($SelfT), ".to_be_bytes();")]
2297         #[doc = concat!("assert_eq!(bytes, ", $be_bytes, ");")]
2298         /// ```
2299         #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2300         #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2301         #[inline]
2302         pub const fn to_be_bytes(self) -> [u8; mem::size_of::<Self>()] {
2303             self.to_be().to_ne_bytes()
2304         }
2305
2306         /// Return the memory representation of this integer as a byte array in
2307         /// little-endian byte order.
2308         ///
2309         #[doc = $to_xe_bytes_doc]
2310         ///
2311         /// # Examples
2312         ///
2313         /// ```
2314         #[doc = concat!("let bytes = ", $swap_op, stringify!($SelfT), ".to_le_bytes();")]
2315         #[doc = concat!("assert_eq!(bytes, ", $le_bytes, ");")]
2316         /// ```
2317         #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2318         #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2319         #[inline]
2320         pub const fn to_le_bytes(self) -> [u8; mem::size_of::<Self>()] {
2321             self.to_le().to_ne_bytes()
2322         }
2323
2324         /// Return the memory representation of this integer as a byte array in
2325         /// native byte order.
2326         ///
2327         /// As the target platform's native endianness is used, portable code
2328         /// should use [`to_be_bytes`] or [`to_le_bytes`], as appropriate,
2329         /// instead.
2330         ///
2331         #[doc = $to_xe_bytes_doc]
2332         ///
2333         /// [`to_be_bytes`]: Self::to_be_bytes
2334         /// [`to_le_bytes`]: Self::to_le_bytes
2335         ///
2336         /// # Examples
2337         ///
2338         /// ```
2339         #[doc = concat!("let bytes = ", $swap_op, stringify!($SelfT), ".to_ne_bytes();")]
2340         /// assert_eq!(
2341         ///     bytes,
2342         ///     if cfg!(target_endian = "big") {
2343         #[doc = concat!("        ", $be_bytes)]
2344         ///     } else {
2345         #[doc = concat!("        ", $le_bytes)]
2346         ///     }
2347         /// );
2348         /// ```
2349         #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2350         #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2351         // SAFETY: const sound because integers are plain old datatypes so we can always
2352         // transmute them to arrays of bytes
2353         #[inline]
2354         pub const fn to_ne_bytes(self) -> [u8; mem::size_of::<Self>()] {
2355             // SAFETY: integers are plain old datatypes so we can always transmute them to
2356             // arrays of bytes
2357             unsafe { mem::transmute(self) }
2358         }
2359
2360         /// Create an integer value from its representation as a byte array in
2361         /// big endian.
2362         ///
2363         #[doc = $to_xe_bytes_doc]
2364         ///
2365         /// # Examples
2366         ///
2367         /// ```
2368         #[doc = concat!("let value = ", stringify!($SelfT), "::from_be_bytes(", $be_bytes, ");")]
2369         #[doc = concat!("assert_eq!(value, ", $swap_op, ");")]
2370         /// ```
2371         ///
2372         /// When starting from a slice rather than an array, fallible conversion APIs can be used:
2373         ///
2374         /// ```
2375         /// use std::convert::TryInto;
2376         ///
2377         #[doc = concat!("fn read_be_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {")]
2378         #[doc = concat!("    let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());")]
2379         ///     *input = rest;
2380         #[doc = concat!("    ", stringify!($SelfT), "::from_be_bytes(int_bytes.try_into().unwrap())")]
2381         /// }
2382         /// ```
2383         #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2384         #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2385         #[inline]
2386         pub const fn from_be_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
2387             Self::from_be(Self::from_ne_bytes(bytes))
2388         }
2389
2390         /// Create an integer value from its representation as a byte array in
2391         /// little endian.
2392         ///
2393         #[doc = $to_xe_bytes_doc]
2394         ///
2395         /// # Examples
2396         ///
2397         /// ```
2398         #[doc = concat!("let value = ", stringify!($SelfT), "::from_le_bytes(", $le_bytes, ");")]
2399         #[doc = concat!("assert_eq!(value, ", $swap_op, ");")]
2400         /// ```
2401         ///
2402         /// When starting from a slice rather than an array, fallible conversion APIs can be used:
2403         ///
2404         /// ```
2405         /// use std::convert::TryInto;
2406         ///
2407         #[doc = concat!("fn read_le_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {")]
2408         #[doc = concat!("    let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());")]
2409         ///     *input = rest;
2410         #[doc = concat!("    ", stringify!($SelfT), "::from_le_bytes(int_bytes.try_into().unwrap())")]
2411         /// }
2412         /// ```
2413         #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2414         #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2415         #[inline]
2416         pub const fn from_le_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
2417             Self::from_le(Self::from_ne_bytes(bytes))
2418         }
2419
2420         /// Create an integer value from its memory representation as a byte
2421         /// array in native endianness.
2422         ///
2423         /// As the target platform's native endianness is used, portable code
2424         /// likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as
2425         /// appropriate instead.
2426         ///
2427         /// [`from_be_bytes`]: Self::from_be_bytes
2428         /// [`from_le_bytes`]: Self::from_le_bytes
2429         ///
2430         #[doc = $to_xe_bytes_doc]
2431         ///
2432         /// # Examples
2433         ///
2434         /// ```
2435         #[doc = concat!("let value = ", stringify!($SelfT), "::from_ne_bytes(if cfg!(target_endian = \"big\") {")]
2436         #[doc = concat!("    ", $be_bytes)]
2437         /// } else {
2438         #[doc = concat!("    ", $le_bytes)]
2439         /// });
2440         #[doc = concat!("assert_eq!(value, ", $swap_op, ");")]
2441         /// ```
2442         ///
2443         /// When starting from a slice rather than an array, fallible conversion APIs can be used:
2444         ///
2445         /// ```
2446         /// use std::convert::TryInto;
2447         ///
2448         #[doc = concat!("fn read_ne_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {")]
2449         #[doc = concat!("    let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());")]
2450         ///     *input = rest;
2451         #[doc = concat!("    ", stringify!($SelfT), "::from_ne_bytes(int_bytes.try_into().unwrap())")]
2452         /// }
2453         /// ```
2454         #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2455         #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2456         // SAFETY: const sound because integers are plain old datatypes so we can always
2457         // transmute to them
2458         #[inline]
2459         pub const fn from_ne_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
2460             // SAFETY: integers are plain old datatypes so we can always transmute to them
2461             unsafe { mem::transmute(bytes) }
2462         }
2463
2464         /// New code should prefer to use
2465         #[doc = concat!("[`", stringify!($SelfT), "::MIN", "`] instead.")]
2466         ///
2467         /// Returns the smallest value that can be represented by this integer type.
2468         #[stable(feature = "rust1", since = "1.0.0")]
2469         #[inline(always)]
2470         #[rustc_promotable]
2471         #[rustc_const_stable(feature = "const_min_value", since = "1.32.0")]
2472         #[rustc_deprecated(since = "TBD", reason = "replaced by the `MIN` associated constant on this type")]
2473         pub const fn min_value() -> Self {
2474             Self::MIN
2475         }
2476
2477         /// New code should prefer to use
2478         #[doc = concat!("[`", stringify!($SelfT), "::MAX", "`] instead.")]
2479         ///
2480         /// Returns the largest value that can be represented by this integer type.
2481         #[stable(feature = "rust1", since = "1.0.0")]
2482         #[inline(always)]
2483         #[rustc_promotable]
2484         #[rustc_const_stable(feature = "const_max_value", since = "1.32.0")]
2485         #[rustc_deprecated(since = "TBD", reason = "replaced by the `MAX` associated constant on this type")]
2486         pub const fn max_value() -> Self {
2487             Self::MAX
2488         }
2489     }
2490 }