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