library/core/src/num/uint_macros.rs

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