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