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 then 2.
 696         ///
 697         /// # Examples
 698         ///
 699         /// ```
 700         /// #![feature(int_log)]
 701         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".ilog(5), 1);")]
 702         /// ```
 703         #[unstable(feature = "int_log", issue = "70887")]
 704         #[must_use = "this returns the result of the operation, \
 705                       without modifying the original"]
 706         #[inline]
 707         #[track_caller]
 708         pub const fn ilog(self, base: Self) -> u32 {
 709             assert!(base >= 2, "base of integer logarithm must be at least 2");
 710             self.checked_ilog(base).expect("argument of integer logarithm must be positive")
 711         }
 712
 713         /// Returns the base 2 logarithm of the number, rounded down.
 714         ///
 715         /// # Panics
 716         ///
 717         /// This function will panic if `self` is zero.
 718         ///
 719         /// # Examples
 720         ///
 721         /// ```
 722         /// #![feature(int_log)]
 723         #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".ilog2(), 1);")]
 724         /// ```
 725         #[unstable(feature = "int_log", issue = "70887")]
 726         #[must_use = "this returns the result of the operation, \
 727                       without modifying the original"]
 728         #[inline]
 729         #[track_caller]
 730         pub const fn ilog2(self) -> u32 {
 731             self.checked_ilog2().expect("argument of integer logarithm must be positive")
 732         }
 733
 734         /// Returns the base 10 logarithm of the number, rounded down.
 735         ///
 736         /// # Panics
 737         ///
 738         /// This function will panic if `self` is zero.
 739         ///
 740         /// # Example
 741         ///
 742         /// ```
 743         /// #![feature(int_log)]
 744         #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".ilog10(), 1);")]
 745         /// ```
 746         #[unstable(feature = "int_log", issue = "70887")]
 747         #[must_use = "this returns the result of the operation, \
 748                       without modifying the original"]
 749         #[inline]
 750         #[track_caller]
 751         pub const fn ilog10(self) -> u32 {
 752             self.checked_ilog10().expect("argument of integer logarithm must be positive")
 753         }
 754
 755         /// Returns the logarithm of the number with respect to an arbitrary base,
 756         /// rounded down.
 757         ///
 758         /// Returns `None` if the number is zero, or if the base is not at least 2.
 759         ///
 760         /// This method might not be optimized owing to implementation details;
 761         /// `checked_ilog2` can produce results more efficiently for base 2, and
 762         /// `checked_ilog10` can produce results more efficiently for base 10.
 763         ///
 764         /// # Examples
 765         ///
 766         /// ```
 767         /// #![feature(int_log)]
 768         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_ilog(5), Some(1));")]
 769         /// ```
 770         #[unstable(feature = "int_log", issue = "70887")]
 771         #[must_use = "this returns the result of the operation, \
 772                       without modifying the original"]
 773         #[inline]
 774         pub const fn checked_ilog(self, base: Self) -> Option<u32> {
 775             if self <= 0 || base <= 1 {
 776                 None
 777             } else {
 778                 let mut n = 0;
 779                 let mut r = self;
 780
 781                 // Optimization for 128 bit wide integers.
 782                 if Self::BITS == 128 {
 783                     let b = Self::ilog2(self) / (Self::ilog2(base) + 1);
 784                     n += b;
 785                     r /= base.pow(b as u32);
 786                 }
 787
 788                 while r >= base {
 789                     r /= base;
 790                     n += 1;
 791                 }
 792                 Some(n)
 793             }
 794         }
 795
 796         /// Returns the base 2 logarithm of the number, rounded down.
 797         ///
 798         /// Returns `None` if the number is zero.
 799         ///
 800         /// # Examples
 801         ///
 802         /// ```
 803         /// #![feature(int_log)]
 804         #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".checked_ilog2(), Some(1));")]
 805         /// ```
 806         #[unstable(feature = "int_log", issue = "70887")]
 807         #[must_use = "this returns the result of the operation, \
 808                       without modifying the original"]
 809         #[inline]
 810         pub const fn checked_ilog2(self) -> Option<u32> {
 811             if let Some(x) = <$NonZeroT>::new(self) {
 812                 Some(x.ilog2())
 813             } else {
 814                 None
 815             }
 816         }
 817
 818         /// Returns the base 10 logarithm of the number, rounded down.
 819         ///
 820         /// Returns `None` if the number is zero.
 821         ///
 822         /// # Examples
 823         ///
 824         /// ```
 825         /// #![feature(int_log)]
 826         #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".checked_ilog10(), Some(1));")]
 827         /// ```
 828         #[unstable(feature = "int_log", issue = "70887")]
 829         #[must_use = "this returns the result of the operation, \
 830                       without modifying the original"]
 831         #[inline]
 832         pub const fn checked_ilog10(self) -> Option<u32> {
 833             if let Some(x) = <$NonZeroT>::new(self) {
 834                 Some(x.ilog10())
 835             } else {
 836                 None
 837             }
 838         }
 839
 840         /// Checked negation. Computes `-self`, returning `None` unless `self ==
 841         /// 0`.
 842         ///
 843         /// Note that negating any positive integer will overflow.
 844         ///
 845         /// # Examples
 846         ///
 847         /// Basic usage:
 848         ///
 849         /// ```
 850         #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".checked_neg(), Some(0));")]
 851         #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".checked_neg(), None);")]
 852         /// ```
 853         #[stable(feature = "wrapping", since = "1.7.0")]
 854         #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
 855         #[must_use = "this returns the result of the operation, \
 856                       without modifying the original"]
 857         #[inline]
 858         pub const fn checked_neg(self) -> Option<Self> {
 859             let (a, b) = self.overflowing_neg();
 860             if unlikely!(b) {None} else {Some(a)}
 861         }
 862
 863         /// Checked shift left. Computes `self << rhs`, returning `None`
 864         /// if `rhs` is larger than or equal to the number of bits in `self`.
 865         ///
 866         /// # Examples
 867         ///
 868         /// Basic usage:
 869         ///
 870         /// ```
 871         #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".checked_shl(4), Some(0x10));")]
 872         #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".checked_shl(129), None);")]
 873         /// ```
 874         #[stable(feature = "wrapping", since = "1.7.0")]
 875         #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
 876         #[must_use = "this returns the result of the operation, \
 877                       without modifying the original"]
 878         #[inline]
 879         pub const fn checked_shl(self, rhs: u32) -> Option<Self> {
 880             let (a, b) = self.overflowing_shl(rhs);
 881             if unlikely!(b) {None} else {Some(a)}
 882         }
 883
 884         /// Unchecked shift left. Computes `self << rhs`, assuming that
 885         /// `rhs` is less than the number of bits in `self`.
 886         ///
 887         /// # Safety
 888         ///
 889         /// This results in undefined behavior if `rhs` is larger than
 890         /// or equal to the number of bits in `self`,
 891         /// i.e. when [`checked_shl`] would return `None`.
 892         ///
 893         #[doc = concat!("[`checked_shl`]: ", stringify!($SelfT), "::checked_shl")]
 894         #[unstable(
 895             feature = "unchecked_math",
 896             reason = "niche optimization path",
 897             issue = "85122",
 898         )]
 899         #[must_use = "this returns the result of the operation, \
 900                       without modifying the original"]
 901         #[rustc_const_unstable(feature = "const_inherent_unchecked_arith", issue = "85122")]
 902         #[inline(always)]
 903         #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
 904         pub const unsafe fn unchecked_shl(self, rhs: Self) -> Self {
 905             // SAFETY: the caller must uphold the safety contract for
 906             // `unchecked_shl`.
 907             unsafe { intrinsics::unchecked_shl(self, rhs) }
 908         }
 909
 910         /// Checked shift right. Computes `self >> rhs`, returning `None`
 911         /// if `rhs` is larger than or equal to the number of bits in `self`.
 912         ///
 913         /// # Examples
 914         ///
 915         /// Basic usage:
 916         ///
 917         /// ```
 918         #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".checked_shr(4), Some(0x1));")]
 919         #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".checked_shr(129), None);")]
 920         /// ```
 921         #[stable(feature = "wrapping", since = "1.7.0")]
 922         #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
 923         #[must_use = "this returns the result of the operation, \
 924                       without modifying the original"]
 925         #[inline]
 926         pub const fn checked_shr(self, rhs: u32) -> Option<Self> {
 927             let (a, b) = self.overflowing_shr(rhs);
 928             if unlikely!(b) {None} else {Some(a)}
 929         }
 930
 931         /// Unchecked shift right. Computes `self >> rhs`, assuming that
 932         /// `rhs` is less than the number of bits in `self`.
 933         ///
 934         /// # Safety
 935         ///
 936         /// This results in undefined behavior if `rhs` is larger than
 937         /// or equal to the number of bits in `self`,
 938         /// i.e. when [`checked_shr`] would return `None`.
 939         ///
 940         #[doc = concat!("[`checked_shr`]: ", stringify!($SelfT), "::checked_shr")]
 941         #[unstable(
 942             feature = "unchecked_math",
 943             reason = "niche optimization path",
 944             issue = "85122",
 945         )]
 946         #[must_use = "this returns the result of the operation, \
 947                       without modifying the original"]
 948         #[rustc_const_unstable(feature = "const_inherent_unchecked_arith", issue = "85122")]
 949         #[inline(always)]
 950         #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
 951         pub const unsafe fn unchecked_shr(self, rhs: Self) -> Self {
 952             // SAFETY: the caller must uphold the safety contract for
 953             // `unchecked_shr`.
 954             unsafe { intrinsics::unchecked_shr(self, rhs) }
 955         }
 956
 957         /// Checked exponentiation. Computes `self.pow(exp)`, returning `None` if
 958         /// overflow occurred.
 959         ///
 960         /// # Examples
 961         ///
 962         /// Basic usage:
 963         ///
 964         /// ```
 965         #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".checked_pow(5), Some(32));")]
 966         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_pow(2), None);")]
 967         /// ```
 968         #[stable(feature = "no_panic_pow", since = "1.34.0")]
 969         #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
 970         #[must_use = "this returns the result of the operation, \
 971                       without modifying the original"]
 972         #[inline]
 973         pub const fn checked_pow(self, mut exp: u32) -> Option<Self> {
 974             if exp == 0 {
 975                 return Some(1);
 976             }
 977             let mut base = self;
 978             let mut acc: Self = 1;
 979
 980             while exp > 1 {
 981                 if (exp & 1) == 1 {
 982                     acc = try_opt!(acc.checked_mul(base));
 983                 }
 984                 exp /= 2;
 985                 base = try_opt!(base.checked_mul(base));
 986             }
 987
 988             // since exp!=0, finally the exp must be 1.
 989             // Deal with the final bit of the exponent separately, since
 990             // squaring the base afterwards is not necessary and may cause a
 991             // needless overflow.
 992
 993             acc.checked_mul(base)
 994         }
 995
 996         /// Saturating integer addition. Computes `self + rhs`, saturating at
 997         /// the numeric bounds instead of overflowing.
 998         ///
 999         /// # Examples
1000         ///
1001         /// Basic usage:
1002         ///
1003         /// ```
1004         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_add(1), 101);")]
1005         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_add(127), ", stringify!($SelfT), "::MAX);")]
1006         /// ```
1007         #[stable(feature = "rust1", since = "1.0.0")]
1008         #[must_use = "this returns the result of the operation, \
1009                       without modifying the original"]
1010         #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")]
1011         #[inline(always)]
1012         pub const fn saturating_add(self, rhs: Self) -> Self {
1013             intrinsics::saturating_add(self, rhs)
1014         }
1015
1016         /// Saturating addition with a signed integer. Computes `self + rhs`,
1017         /// saturating at the numeric bounds instead of overflowing.
1018         ///
1019         /// # Examples
1020         ///
1021         /// Basic usage:
1022         ///
1023         /// ```
1024         #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".saturating_add_signed(2), 3);")]
1025         #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".saturating_add_signed(-2), 0);")]
1026         #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).saturating_add_signed(4), ", stringify!($SelfT), "::MAX);")]
1027         /// ```
1028         #[stable(feature = "mixed_integer_ops", since = "CURRENT_RUSTC_VERSION")]
1029         #[rustc_const_stable(feature = "mixed_integer_ops", since = "CURRENT_RUSTC_VERSION")]
1030         #[must_use = "this returns the result of the operation, \
1031                       without modifying the original"]
1032         #[inline]
1033         pub const fn saturating_add_signed(self, rhs: $SignedT) -> Self {
1034             let (res, overflow) = self.overflowing_add(rhs as Self);
1035             if overflow == (rhs < 0) {
1036                 res
1037             } else if overflow {
1038                 Self::MAX
1039             } else {
1040                 0
1041             }
1042         }
1043
1044         /// Saturating integer subtraction. Computes `self - rhs`, saturating
1045         /// at the numeric bounds instead of overflowing.
1046         ///
1047         /// # Examples
1048         ///
1049         /// Basic usage:
1050         ///
1051         /// ```
1052         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_sub(27), 73);")]
1053         #[doc = concat!("assert_eq!(13", stringify!($SelfT), ".saturating_sub(127), 0);")]
1054         /// ```
1055         #[stable(feature = "rust1", since = "1.0.0")]
1056         #[must_use = "this returns the result of the operation, \
1057                       without modifying the original"]
1058         #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")]
1059         #[inline(always)]
1060         pub const fn saturating_sub(self, rhs: Self) -> Self {
1061             intrinsics::saturating_sub(self, rhs)
1062         }
1063
1064         /// Saturating integer multiplication. Computes `self * rhs`,
1065         /// saturating at the numeric bounds instead of overflowing.
1066         ///
1067         /// # Examples
1068         ///
1069         /// Basic usage:
1070         ///
1071         /// ```
1072         #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".saturating_mul(10), 20);")]
1073         #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX).saturating_mul(10), ", stringify!($SelfT),"::MAX);")]
1074         /// ```
1075         #[stable(feature = "wrapping", since = "1.7.0")]
1076         #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")]
1077         #[must_use = "this returns the result of the operation, \
1078                       without modifying the original"]
1079         #[inline]
1080         pub const fn saturating_mul(self, rhs: Self) -> Self {
1081             match self.checked_mul(rhs) {
1082                 Some(x) => x,
1083                 None => Self::MAX,
1084             }
1085         }
1086
1087         /// Saturating integer division. Computes `self / rhs`, saturating at the
1088         /// numeric bounds instead of overflowing.
1089         ///
1090         /// # Examples
1091         ///
1092         /// Basic usage:
1093         ///
1094         /// ```
1095         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".saturating_div(2), 2);")]
1096         ///
1097         /// ```
1098         ///
1099         /// ```should_panic
1100         #[doc = concat!("let _ = 1", stringify!($SelfT), ".saturating_div(0);")]
1101         ///
1102         /// ```
1103         #[stable(feature = "saturating_div", since = "1.58.0")]
1104         #[rustc_const_stable(feature = "saturating_div", since = "1.58.0")]
1105         #[must_use = "this returns the result of the operation, \
1106                       without modifying the original"]
1107         #[inline]
1108         pub const fn saturating_div(self, rhs: Self) -> Self {
1109             // on unsigned types, there is no overflow in integer division
1110             self.wrapping_div(rhs)
1111         }
1112
1113         /// Saturating integer exponentiation. Computes `self.pow(exp)`,
1114         /// saturating at the numeric bounds instead of overflowing.
1115         ///
1116         /// # Examples
1117         ///
1118         /// Basic usage:
1119         ///
1120         /// ```
1121         #[doc = concat!("assert_eq!(4", stringify!($SelfT), ".saturating_pow(3), 64);")]
1122         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_pow(2), ", stringify!($SelfT), "::MAX);")]
1123         /// ```
1124         #[stable(feature = "no_panic_pow", since = "1.34.0")]
1125         #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
1126         #[must_use = "this returns the result of the operation, \
1127                       without modifying the original"]
1128         #[inline]
1129         pub const fn saturating_pow(self, exp: u32) -> Self {
1130             match self.checked_pow(exp) {
1131                 Some(x) => x,
1132                 None => Self::MAX,
1133             }
1134         }
1135
1136         /// Wrapping (modular) addition. Computes `self + rhs`,
1137         /// wrapping around at the boundary of the type.
1138         ///
1139         /// # Examples
1140         ///
1141         /// Basic usage:
1142         ///
1143         /// ```
1144         #[doc = concat!("assert_eq!(200", stringify!($SelfT), ".wrapping_add(55), 255);")]
1145         #[doc = concat!("assert_eq!(200", stringify!($SelfT), ".wrapping_add(", stringify!($SelfT), "::MAX), 199);")]
1146         /// ```
1147         #[stable(feature = "rust1", since = "1.0.0")]
1148         #[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")]
1149         #[must_use = "this returns the result of the operation, \
1150                       without modifying the original"]
1151         #[inline(always)]
1152         pub const fn wrapping_add(self, rhs: Self) -> Self {
1153             intrinsics::wrapping_add(self, rhs)
1154         }
1155
1156         /// Wrapping (modular) addition with a signed integer. Computes
1157         /// `self + rhs`, wrapping around at the boundary of the type.
1158         ///
1159         /// # Examples
1160         ///
1161         /// Basic usage:
1162         ///
1163         /// ```
1164         #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".wrapping_add_signed(2), 3);")]
1165         #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".wrapping_add_signed(-2), ", stringify!($SelfT), "::MAX);")]
1166         #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).wrapping_add_signed(4), 1);")]
1167         /// ```
1168         #[stable(feature = "mixed_integer_ops", since = "CURRENT_RUSTC_VERSION")]
1169         #[rustc_const_stable(feature = "mixed_integer_ops", since = "CURRENT_RUSTC_VERSION")]
1170         #[must_use = "this returns the result of the operation, \
1171                       without modifying the original"]
1172         #[inline]
1173         pub const fn wrapping_add_signed(self, rhs: $SignedT) -> Self {
1174             self.wrapping_add(rhs as Self)
1175         }
1176
1177         /// Wrapping (modular) subtraction. Computes `self - rhs`,
1178         /// wrapping around at the boundary of the type.
1179         ///
1180         /// # Examples
1181         ///
1182         /// Basic usage:
1183         ///
1184         /// ```
1185         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_sub(100), 0);")]
1186         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_sub(", stringify!($SelfT), "::MAX), 101);")]
1187         /// ```
1188         #[stable(feature = "rust1", since = "1.0.0")]
1189         #[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")]
1190         #[must_use = "this returns the result of the operation, \
1191                       without modifying the original"]
1192         #[inline(always)]
1193         pub const fn wrapping_sub(self, rhs: Self) -> Self {
1194             intrinsics::wrapping_sub(self, rhs)
1195         }
1196
1197         /// Wrapping (modular) multiplication. Computes `self *
1198         /// rhs`, wrapping around at the boundary of the type.
1199         ///
1200         /// # Examples
1201         ///
1202         /// Basic usage:
1203         ///
1204         /// Please note that this example is shared between integer types.
1205         /// Which explains why `u8` is used here.
1206         ///
1207         /// ```
1208         /// assert_eq!(10u8.wrapping_mul(12), 120);
1209         /// assert_eq!(25u8.wrapping_mul(12), 44);
1210         /// ```
1211         #[stable(feature = "rust1", since = "1.0.0")]
1212         #[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")]
1213         #[must_use = "this returns the result of the operation, \
1214                       without modifying the original"]
1215         #[inline(always)]
1216         pub const fn wrapping_mul(self, rhs: Self) -> Self {
1217             intrinsics::wrapping_mul(self, rhs)
1218         }
1219
1220         /// Wrapping (modular) division. Computes `self / rhs`.
1221         /// Wrapped division on unsigned types is just normal division.
1222         /// There's no way wrapping could ever happen.
1223         /// This function exists, so that all operations
1224         /// are accounted for in the wrapping operations.
1225         ///
1226         /// # Examples
1227         ///
1228         /// Basic usage:
1229         ///
1230         /// ```
1231         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_div(10), 10);")]
1232         /// ```
1233         #[stable(feature = "num_wrapping", since = "1.2.0")]
1234         #[rustc_const_stable(feature = "const_wrapping_int_methods", since = "1.52.0")]
1235         #[must_use = "this returns the result of the operation, \
1236                       without modifying the original"]
1237         #[inline(always)]
1238         pub const fn wrapping_div(self, rhs: Self) -> Self {
1239             self / rhs
1240         }
1241
1242         /// Wrapping Euclidean division. Computes `self.div_euclid(rhs)`.
1243         /// Wrapped division on unsigned types is just normal division.
1244         /// There's no way wrapping could ever happen.
1245         /// This function exists, so that all operations
1246         /// are accounted for in the wrapping operations.
1247         /// Since, for the positive integers, all common
1248         /// definitions of division are equal, this
1249         /// is exactly equal to `self.wrapping_div(rhs)`.
1250         ///
1251         /// # Examples
1252         ///
1253         /// Basic usage:
1254         ///
1255         /// ```
1256         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_div_euclid(10), 10);")]
1257         /// ```
1258         #[stable(feature = "euclidean_division", since = "1.38.0")]
1259         #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
1260         #[must_use = "this returns the result of the operation, \
1261                       without modifying the original"]
1262         #[inline(always)]
1263         pub const fn wrapping_div_euclid(self, rhs: Self) -> Self {
1264             self / rhs
1265         }
1266
1267         /// Wrapping (modular) remainder. Computes `self % rhs`.
1268         /// Wrapped remainder calculation on unsigned types is
1269         /// just the regular remainder calculation.
1270         /// There's no way wrapping could ever happen.
1271         /// This function exists, so that all operations
1272         /// are accounted for in the wrapping operations.
1273         ///
1274         /// # Examples
1275         ///
1276         /// Basic usage:
1277         ///
1278         /// ```
1279         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_rem(10), 0);")]
1280         /// ```
1281         #[stable(feature = "num_wrapping", since = "1.2.0")]
1282         #[rustc_const_stable(feature = "const_wrapping_int_methods", since = "1.52.0")]
1283         #[must_use = "this returns the result of the operation, \
1284                       without modifying the original"]
1285         #[inline(always)]
1286         pub const fn wrapping_rem(self, rhs: Self) -> Self {
1287             self % rhs
1288         }
1289
1290         /// Wrapping Euclidean modulo. Computes `self.rem_euclid(rhs)`.
1291         /// Wrapped modulo calculation on unsigned types is
1292         /// just the regular remainder calculation.
1293         /// There's no way wrapping could ever happen.
1294         /// This function exists, so that all operations
1295         /// are accounted for in the wrapping operations.
1296         /// Since, for the positive integers, all common
1297         /// definitions of division are equal, this
1298         /// is exactly equal to `self.wrapping_rem(rhs)`.
1299         ///
1300         /// # Examples
1301         ///
1302         /// Basic usage:
1303         ///
1304         /// ```
1305         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_rem_euclid(10), 0);")]
1306         /// ```
1307         #[stable(feature = "euclidean_division", since = "1.38.0")]
1308         #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
1309         #[must_use = "this returns the result of the operation, \
1310                       without modifying the original"]
1311         #[inline(always)]
1312         pub const fn wrapping_rem_euclid(self, rhs: Self) -> Self {
1313             self % rhs
1314         }
1315
1316         /// Wrapping (modular) negation. Computes `-self`,
1317         /// wrapping around at the boundary of the type.
1318         ///
1319         /// Since unsigned types do not have negative equivalents
1320         /// all applications of this function will wrap (except for `-0`).
1321         /// For values smaller than the corresponding signed type's maximum
1322         /// the result is the same as casting the corresponding signed value.
1323         /// Any larger values are equivalent to `MAX + 1 - (val - MAX - 1)` where
1324         /// `MAX` is the corresponding signed type's maximum.
1325         ///
1326         /// # Examples
1327         ///
1328         /// Basic usage:
1329         ///
1330         /// Please note that this example is shared between integer types.
1331         /// Which explains why `i8` is used here.
1332         ///
1333         /// ```
1334         /// assert_eq!(100i8.wrapping_neg(), -100);
1335         /// assert_eq!((-128i8).wrapping_neg(), -128);
1336         /// ```
1337         #[stable(feature = "num_wrapping", since = "1.2.0")]
1338         #[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")]
1339         #[must_use = "this returns the result of the operation, \
1340                       without modifying the original"]
1341         #[inline(always)]
1342         pub const fn wrapping_neg(self) -> Self {
1343             (0 as $SelfT).wrapping_sub(self)
1344         }
1345
1346         /// Panic-free bitwise shift-left; yields `self << mask(rhs)`,
1347         /// where `mask` removes any high-order bits of `rhs` that
1348         /// would cause the shift to exceed the bitwidth of the type.
1349         ///
1350         /// Note that this is *not* the same as a rotate-left; the
1351         /// RHS of a wrapping shift-left is restricted to the range
1352         /// of the type, rather than the bits shifted out of the LHS
1353         /// being returned to the other end. The primitive integer
1354         /// types all implement a [`rotate_left`](Self::rotate_left) function,
1355         /// which may be what you want instead.
1356         ///
1357         /// # Examples
1358         ///
1359         /// Basic usage:
1360         ///
1361         /// ```
1362         #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".wrapping_shl(7), 128);")]
1363         #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".wrapping_shl(128), 1);")]
1364         /// ```
1365         #[stable(feature = "num_wrapping", since = "1.2.0")]
1366         #[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")]
1367         #[must_use = "this returns the result of the operation, \
1368                       without modifying the original"]
1369         #[inline(always)]
1370         pub const fn wrapping_shl(self, rhs: u32) -> Self {
1371             // SAFETY: the masking by the bitsize of the type ensures that we do not shift
1372             // out of bounds
1373             unsafe {
1374                 intrinsics::unchecked_shl(self, (rhs & ($BITS - 1)) as $SelfT)
1375             }
1376         }
1377
1378         /// Panic-free bitwise shift-right; yields `self >> mask(rhs)`,
1379         /// where `mask` removes any high-order bits of `rhs` that
1380         /// would cause the shift to exceed the bitwidth of the type.
1381         ///
1382         /// Note that this is *not* the same as a rotate-right; the
1383         /// RHS of a wrapping shift-right is restricted to the range
1384         /// of the type, rather than the bits shifted out of the LHS
1385         /// being returned to the other end. The primitive integer
1386         /// types all implement a [`rotate_right`](Self::rotate_right) function,
1387         /// which may be what you want instead.
1388         ///
1389         /// # Examples
1390         ///
1391         /// Basic usage:
1392         ///
1393         /// ```
1394         #[doc = concat!("assert_eq!(128", stringify!($SelfT), ".wrapping_shr(7), 1);")]
1395         #[doc = concat!("assert_eq!(128", stringify!($SelfT), ".wrapping_shr(128), 128);")]
1396         /// ```
1397         #[stable(feature = "num_wrapping", since = "1.2.0")]
1398         #[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")]
1399         #[must_use = "this returns the result of the operation, \
1400                       without modifying the original"]
1401         #[inline(always)]
1402         pub const fn wrapping_shr(self, rhs: u32) -> Self {
1403             // SAFETY: the masking by the bitsize of the type ensures that we do not shift
1404             // out of bounds
1405             unsafe {
1406                 intrinsics::unchecked_shr(self, (rhs & ($BITS - 1)) as $SelfT)
1407             }
1408         }
1409
1410         /// Wrapping (modular) exponentiation. Computes `self.pow(exp)`,
1411         /// wrapping around at the boundary of the type.
1412         ///
1413         /// # Examples
1414         ///
1415         /// Basic usage:
1416         ///
1417         /// ```
1418         #[doc = concat!("assert_eq!(3", stringify!($SelfT), ".wrapping_pow(5), 243);")]
1419         /// assert_eq!(3u8.wrapping_pow(6), 217);
1420         /// ```
1421         #[stable(feature = "no_panic_pow", since = "1.34.0")]
1422         #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
1423         #[must_use = "this returns the result of the operation, \
1424                       without modifying the original"]
1425         #[inline]
1426         pub const fn wrapping_pow(self, mut exp: u32) -> Self {
1427             if exp == 0 {
1428                 return 1;
1429             }
1430             let mut base = self;
1431             let mut acc: Self = 1;
1432
1433             while exp > 1 {
1434                 if (exp & 1) == 1 {
1435                     acc = acc.wrapping_mul(base);
1436                 }
1437                 exp /= 2;
1438                 base = base.wrapping_mul(base);
1439             }
1440
1441             // since exp!=0, finally the exp must be 1.
1442             // Deal with the final bit of the exponent separately, since
1443             // squaring the base afterwards is not necessary and may cause a
1444             // needless overflow.
1445             acc.wrapping_mul(base)
1446         }
1447
1448         /// Calculates `self` + `rhs`
1449         ///
1450         /// Returns a tuple of the addition along with a boolean indicating
1451         /// whether an arithmetic overflow would occur. If an overflow would
1452         /// have occurred then the wrapped value is returned.
1453         ///
1454         /// # Examples
1455         ///
1456         /// Basic usage
1457         ///
1458         /// ```
1459         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_add(2), (7, false));")]
1460         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.overflowing_add(1), (0, true));")]
1461         /// ```
1462         #[stable(feature = "wrapping", since = "1.7.0")]
1463         #[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")]
1464         #[must_use = "this returns the result of the operation, \
1465                       without modifying the original"]
1466         #[inline(always)]
1467         pub const fn overflowing_add(self, rhs: Self) -> (Self, bool) {
1468             let (a, b) = intrinsics::add_with_overflow(self as $ActualT, rhs as $ActualT);
1469             (a as Self, b)
1470         }
1471
1472         /// Calculates `self` + `rhs` + `carry` and returns a tuple containing
1473         /// the sum and the output carry.
1474         ///
1475         /// Performs "ternary addition" of two integer operands and a carry-in
1476         /// bit, and returns an output integer and a carry-out bit. This allows
1477         /// chaining together multiple additions to create a wider addition, and
1478         /// can be useful for bignum addition.
1479         ///
1480         #[doc = concat!("This can be thought of as a ", stringify!($BITS), "-bit \"full adder\", in the electronics sense.")]
1481         ///
1482         /// If the input carry is false, this method is equivalent to
1483         /// [`overflowing_add`](Self::overflowing_add), and the output carry is
1484         /// equal to the overflow flag. Note that although carry and overflow
1485         /// flags are similar for unsigned integers, they are different for
1486         /// signed integers.
1487         ///
1488         /// # Examples
1489         ///
1490         /// ```
1491         /// #![feature(bigint_helper_methods)]
1492         ///
1493         #[doc = concat!("//    3  MAX    (a = 3 × 2^", stringify!($BITS), " + 2^", stringify!($BITS), " - 1)")]
1494         #[doc = concat!("// +  5    7    (b = 5 × 2^", stringify!($BITS), " + 7)")]
1495         /// // ---------
1496         #[doc = concat!("//    9    6    (sum = 9 × 2^", stringify!($BITS), " + 6)")]
1497         ///
1498         #[doc = concat!("let (a1, a0): (", stringify!($SelfT), ", ", stringify!($SelfT), ") = (3, ", stringify!($SelfT), "::MAX);")]
1499         #[doc = concat!("let (b1, b0): (", stringify!($SelfT), ", ", stringify!($SelfT), ") = (5, 7);")]
1500         /// let carry0 = false;
1501         ///
1502         /// let (sum0, carry1) = a0.carrying_add(b0, carry0);
1503         /// assert_eq!(carry1, true);
1504         /// let (sum1, carry2) = a1.carrying_add(b1, carry1);
1505         /// assert_eq!(carry2, false);
1506         ///
1507         /// assert_eq!((sum1, sum0), (9, 6));
1508         /// ```
1509         #[unstable(feature = "bigint_helper_methods", issue = "85532")]
1510         #[rustc_const_unstable(feature = "const_bigint_helper_methods", issue = "85532")]
1511         #[must_use = "this returns the result of the operation, \
1512                       without modifying the original"]
1513         #[inline]
1514         pub const fn carrying_add(self, rhs: Self, carry: bool) -> (Self, bool) {
1515             // note: longer-term this should be done via an intrinsic, but this has been shown
1516             //   to generate optimal code for now, and LLVM doesn't have an equivalent intrinsic
1517             let (a, b) = self.overflowing_add(rhs);
1518             let (c, d) = a.overflowing_add(carry as $SelfT);
1519             (c, b || d)
1520         }
1521
1522         /// Calculates `self` + `rhs` with a signed `rhs`
1523         ///
1524         /// Returns a tuple of the addition along with a boolean indicating
1525         /// whether an arithmetic overflow would occur. If an overflow would
1526         /// have occurred then the wrapped value is returned.
1527         ///
1528         /// # Examples
1529         ///
1530         /// Basic usage:
1531         ///
1532         /// ```
1533         #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".overflowing_add_signed(2), (3, false));")]
1534         #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".overflowing_add_signed(-2), (", stringify!($SelfT), "::MAX, true));")]
1535         #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).overflowing_add_signed(4), (1, true));")]
1536         /// ```
1537         #[stable(feature = "mixed_integer_ops", since = "CURRENT_RUSTC_VERSION")]
1538         #[rustc_const_stable(feature = "mixed_integer_ops", since = "CURRENT_RUSTC_VERSION")]
1539         #[must_use = "this returns the result of the operation, \
1540                       without modifying the original"]
1541         #[inline]
1542         pub const fn overflowing_add_signed(self, rhs: $SignedT) -> (Self, bool) {
1543             let (res, overflowed) = self.overflowing_add(rhs as Self);
1544             (res, overflowed ^ (rhs < 0))
1545         }
1546
1547         /// Calculates `self` - `rhs`
1548         ///
1549         /// Returns a tuple of the subtraction along with a boolean indicating
1550         /// whether an arithmetic overflow would occur. If an overflow would
1551         /// have occurred then the wrapped value is returned.
1552         ///
1553         /// # Examples
1554         ///
1555         /// Basic usage
1556         ///
1557         /// ```
1558         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_sub(2), (3, false));")]
1559         #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".overflowing_sub(1), (", stringify!($SelfT), "::MAX, true));")]
1560         /// ```
1561         #[stable(feature = "wrapping", since = "1.7.0")]
1562         #[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")]
1563         #[must_use = "this returns the result of the operation, \
1564                       without modifying the original"]
1565         #[inline(always)]
1566         pub const fn overflowing_sub(self, rhs: Self) -> (Self, bool) {
1567             let (a, b) = intrinsics::sub_with_overflow(self as $ActualT, rhs as $ActualT);
1568             (a as Self, b)
1569         }
1570
1571         /// Calculates `self` &minus; `rhs` &minus; `borrow` and returns a tuple
1572         /// containing the difference and the output borrow.
1573         ///
1574         /// Performs "ternary subtraction" by subtracting both an integer
1575         /// operand and a borrow-in bit from `self`, and returns an output
1576         /// integer and a borrow-out bit. This allows chaining together multiple
1577         /// subtractions to create a wider subtraction, and can be useful for
1578         /// bignum subtraction.
1579         ///
1580         /// # Examples
1581         ///
1582         /// ```
1583         /// #![feature(bigint_helper_methods)]
1584         ///
1585         #[doc = concat!("//    9    6    (a = 9 × 2^", stringify!($BITS), " + 6)")]
1586         #[doc = concat!("// -  5    7    (b = 5 × 2^", stringify!($BITS), " + 7)")]
1587         /// // ---------
1588         #[doc = concat!("//    3  MAX    (diff = 3 × 2^", stringify!($BITS), " + 2^", stringify!($BITS), " - 1)")]
1589         ///
1590         #[doc = concat!("let (a1, a0): (", stringify!($SelfT), ", ", stringify!($SelfT), ") = (9, 6);")]
1591         #[doc = concat!("let (b1, b0): (", stringify!($SelfT), ", ", stringify!($SelfT), ") = (5, 7);")]
1592         /// let borrow0 = false;
1593         ///
1594         /// let (diff0, borrow1) = a0.borrowing_sub(b0, borrow0);
1595         /// assert_eq!(borrow1, true);
1596         /// let (diff1, borrow2) = a1.borrowing_sub(b1, borrow1);
1597         /// assert_eq!(borrow2, false);
1598         ///
1599         #[doc = concat!("assert_eq!((diff1, diff0), (3, ", stringify!($SelfT), "::MAX));")]
1600         /// ```
1601         #[unstable(feature = "bigint_helper_methods", issue = "85532")]
1602         #[rustc_const_unstable(feature = "const_bigint_helper_methods", issue = "85532")]
1603         #[must_use = "this returns the result of the operation, \
1604                       without modifying the original"]
1605         #[inline]
1606         pub const fn borrowing_sub(self, rhs: Self, borrow: bool) -> (Self, bool) {
1607             // note: longer-term this should be done via an intrinsic, but this has been shown
1608             //   to generate optimal code for now, and LLVM doesn't have an equivalent intrinsic
1609             let (a, b) = self.overflowing_sub(rhs);
1610             let (c, d) = a.overflowing_sub(borrow as $SelfT);
1611             (c, b || d)
1612         }
1613
1614         /// Computes the absolute difference between `self` and `other`.
1615         ///
1616         /// # Examples
1617         ///
1618         /// Basic usage:
1619         ///
1620         /// ```
1621         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".abs_diff(80), 20", stringify!($SelfT), ");")]
1622         #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".abs_diff(110), 10", stringify!($SelfT), ");")]
1623         /// ```
1624         #[stable(feature = "int_abs_diff", since = "1.60.0")]
1625         #[rustc_const_stable(feature = "int_abs_diff", since = "1.60.0")]
1626         #[must_use = "this returns the result of the operation, \
1627                       without modifying the original"]
1628         #[inline]
1629         pub const fn abs_diff(self, other: Self) -> Self {
1630             if mem::size_of::<Self>() == 1 {
1631                 // Trick LLVM into generating the psadbw instruction when SSE2
1632                 // is available and this function is autovectorized for u8's.
1633                 (self as i32).wrapping_sub(other as i32).abs() as Self
1634             } else {
1635                 if self < other {
1636                     other - self
1637                 } else {
1638                     self - other
1639                 }
1640             }
1641         }
1642
1643         /// Calculates the multiplication of `self` and `rhs`.
1644         ///
1645         /// Returns a tuple of the multiplication along with a boolean
1646         /// indicating whether an arithmetic overflow would occur. If an
1647         /// overflow would have occurred then the wrapped value is returned.
1648         ///
1649         /// # Examples
1650         ///
1651         /// Basic usage:
1652         ///
1653         /// Please note that this example is shared between integer types.
1654         /// Which explains why `u32` is used here.
1655         ///
1656         /// ```
1657         /// assert_eq!(5u32.overflowing_mul(2), (10, false));
1658         /// assert_eq!(1_000_000_000u32.overflowing_mul(10), (1410065408, true));
1659         /// ```
1660         #[stable(feature = "wrapping", since = "1.7.0")]
1661         #[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")]
1662         #[must_use = "this returns the result of the operation, \
1663                           without modifying the original"]
1664         #[inline(always)]
1665         pub const fn overflowing_mul(self, rhs: Self) -> (Self, bool) {
1666             let (a, b) = intrinsics::mul_with_overflow(self as $ActualT, rhs as $ActualT);
1667             (a as Self, b)
1668         }
1669
1670         /// Calculates the divisor when `self` is divided by `rhs`.
1671         ///
1672         /// Returns a tuple of the divisor along with a boolean indicating
1673         /// whether an arithmetic overflow would occur. Note that for unsigned
1674         /// integers overflow never occurs, so the second value is always
1675         /// `false`.
1676         ///
1677         /// # Panics
1678         ///
1679         /// This function will panic if `rhs` is 0.
1680         ///
1681         /// # Examples
1682         ///
1683         /// Basic usage
1684         ///
1685         /// ```
1686         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_div(2), (2, false));")]
1687         /// ```
1688         #[inline(always)]
1689         #[stable(feature = "wrapping", since = "1.7.0")]
1690         #[rustc_const_stable(feature = "const_overflowing_int_methods", since = "1.52.0")]
1691         #[must_use = "this returns the result of the operation, \
1692                       without modifying the original"]
1693         pub const fn overflowing_div(self, rhs: Self) -> (Self, bool) {
1694             (self / rhs, false)
1695         }
1696
1697         /// Calculates the quotient of Euclidean division `self.div_euclid(rhs)`.
1698         ///
1699         /// Returns a tuple of the divisor along with a boolean indicating
1700         /// whether an arithmetic overflow would occur. Note that for unsigned
1701         /// integers overflow never occurs, so the second value is always
1702         /// `false`.
1703         /// Since, for the positive integers, all common
1704         /// definitions of division are equal, this
1705         /// is exactly equal to `self.overflowing_div(rhs)`.
1706         ///
1707         /// # Panics
1708         ///
1709         /// This function will panic if `rhs` is 0.
1710         ///
1711         /// # Examples
1712         ///
1713         /// Basic usage
1714         ///
1715         /// ```
1716         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_div_euclid(2), (2, false));")]
1717         /// ```
1718         #[inline(always)]
1719         #[stable(feature = "euclidean_division", since = "1.38.0")]
1720         #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
1721         #[must_use = "this returns the result of the operation, \
1722                       without modifying the original"]
1723         pub const fn overflowing_div_euclid(self, rhs: Self) -> (Self, bool) {
1724             (self / rhs, false)
1725         }
1726
1727         /// Calculates the remainder when `self` is divided by `rhs`.
1728         ///
1729         /// Returns a tuple of the remainder after dividing along with a boolean
1730         /// indicating whether an arithmetic overflow would occur. Note that for
1731         /// unsigned integers overflow never occurs, so the second value is
1732         /// always `false`.
1733         ///
1734         /// # Panics
1735         ///
1736         /// This function will panic if `rhs` is 0.
1737         ///
1738         /// # Examples
1739         ///
1740         /// Basic usage
1741         ///
1742         /// ```
1743         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_rem(2), (1, false));")]
1744         /// ```
1745         #[inline(always)]
1746         #[stable(feature = "wrapping", since = "1.7.0")]
1747         #[rustc_const_stable(feature = "const_overflowing_int_methods", since = "1.52.0")]
1748         #[must_use = "this returns the result of the operation, \
1749                       without modifying the original"]
1750         pub const fn overflowing_rem(self, rhs: Self) -> (Self, bool) {
1751             (self % rhs, false)
1752         }
1753
1754         /// Calculates the remainder `self.rem_euclid(rhs)` as if by Euclidean division.
1755         ///
1756         /// Returns a tuple of the modulo after dividing along with a boolean
1757         /// indicating whether an arithmetic overflow would occur. Note that for
1758         /// unsigned integers overflow never occurs, so the second value is
1759         /// always `false`.
1760         /// Since, for the positive integers, all common
1761         /// definitions of division are equal, this operation
1762         /// is exactly equal to `self.overflowing_rem(rhs)`.
1763         ///
1764         /// # Panics
1765         ///
1766         /// This function will panic if `rhs` is 0.
1767         ///
1768         /// # Examples
1769         ///
1770         /// Basic usage
1771         ///
1772         /// ```
1773         #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_rem_euclid(2), (1, false));")]
1774         /// ```
1775         #[inline(always)]
1776         #[stable(feature = "euclidean_division", since = "1.38.0")]
1777         #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
1778         #[must_use = "this returns the result of the operation, \
1779                       without modifying the original"]
1780         pub const fn overflowing_rem_euclid(self, rhs: Self) -> (Self, bool) {
1781             (self % rhs, false)
1782         }
1783
1784         /// Negates self in an overflowing fashion.
1785         ///
1786         /// Returns `!self + 1` using wrapping operations to return the value
1787         /// that represents the negation of this unsigned value. Note that for
1788         /// positive unsigned values overflow always occurs, but negating 0 does
1789         /// not overflow.
1790         ///
1791         /// # Examples
1792         ///
1793         /// Basic usage
1794         ///
1795         /// ```
1796         #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".overflowing_neg(), (0, false));")]
1797         #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".overflowing_neg(), (-2i32 as ", stringify!($SelfT), ", true));")]
1798         /// ```
1799         #[inline(always)]
1800         #[stable(feature = "wrapping", since = "1.7.0")]
1801         #[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")]
1802         #[must_use = "this returns the result of the operation, \
1803                       without modifying the original"]
1804         pub const fn overflowing_neg(self) -> (Self, bool) {
1805             ((!self).wrapping_add(1), self != 0)
1806         }
1807
1808         /// Shifts self left by `rhs` bits.
1809         ///
1810         /// Returns a tuple of the shifted version of self along with a boolean
1811         /// indicating whether the shift value was larger than or equal to the
1812         /// number of bits. If the shift value is too large, then value is
1813         /// masked (N-1) where N is the number of bits, and this value is then
1814         /// used to perform the shift.
1815         ///
1816         /// # Examples
1817         ///
1818         /// Basic usage
1819         ///
1820         /// ```
1821         #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".overflowing_shl(4), (0x10, false));")]
1822         #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".overflowing_shl(132), (0x10, true));")]
1823         /// ```
1824         #[stable(feature = "wrapping", since = "1.7.0")]
1825         #[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")]
1826         #[must_use = "this returns the result of the operation, \
1827                       without modifying the original"]
1828         #[inline(always)]
1829         pub const fn overflowing_shl(self, rhs: u32) -> (Self, bool) {
1830             (self.wrapping_shl(rhs), (rhs > ($BITS - 1)))
1831         }
1832
1833         /// Shifts self right by `rhs` bits.
1834         ///
1835         /// Returns a tuple of the shifted version of self along with a boolean
1836         /// indicating whether the shift value was larger than or equal to the
1837         /// number of bits. If the shift value is too large, then value is
1838         /// masked (N-1) where N is the number of bits, and this value is then
1839         /// used to perform the shift.
1840         ///
1841         /// # Examples
1842         ///
1843         /// Basic usage
1844         ///
1845         /// ```
1846         #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".overflowing_shr(4), (0x1, false));")]
1847         #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".overflowing_shr(132), (0x1, true));")]
1848         /// ```
1849         #[stable(feature = "wrapping", since = "1.7.0")]
1850         #[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")]
1851         #[must_use = "this returns the result of the operation, \
1852                       without modifying the original"]
1853         #[inline(always)]
1854         pub const fn overflowing_shr(self, rhs: u32) -> (Self, bool) {
1855             (self.wrapping_shr(rhs), (rhs > ($BITS - 1)))
1856         }
1857
1858         /// Raises self to the power of `exp`, using exponentiation by squaring.
1859         ///
1860         /// Returns a tuple of the exponentiation along with a bool indicating
1861         /// whether an overflow happened.
1862         ///
1863         /// # Examples
1864         ///
1865         /// Basic usage:
1866         ///
1867         /// ```
1868         #[doc = concat!("assert_eq!(3", stringify!($SelfT), ".overflowing_pow(5), (243, false));")]
1869         /// assert_eq!(3u8.overflowing_pow(6), (217, true));
1870         /// ```
1871         #[stable(feature = "no_panic_pow", since = "1.34.0")]
1872         #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
1873         #[must_use = "this returns the result of the operation, \
1874                       without modifying the original"]
1875         #[inline]
1876         pub const fn overflowing_pow(self, mut exp: u32) -> (Self, bool) {
1877             if exp == 0{
1878                 return (1,false);
1879             }
1880             let mut base = self;
1881             let mut acc: Self = 1;
1882             let mut overflown = false;
1883             // Scratch space for storing results of overflowing_mul.
1884             let mut r;
1885
1886             while exp > 1 {
1887                 if (exp & 1) == 1 {
1888                     r = acc.overflowing_mul(base);
1889                     acc = r.0;
1890                     overflown |= r.1;
1891                 }
1892                 exp /= 2;
1893                 r = base.overflowing_mul(base);
1894                 base = r.0;
1895                 overflown |= r.1;
1896             }
1897
1898             // since exp!=0, finally the exp must be 1.
1899             // Deal with the final bit of the exponent separately, since
1900             // squaring the base afterwards is not necessary and may cause a
1901             // needless overflow.
1902             r = acc.overflowing_mul(base);
1903             r.1 |= overflown;
1904
1905             r
1906         }
1907
1908         /// Raises self to the power of `exp`, using exponentiation by squaring.
1909         ///
1910         /// # Examples
1911         ///
1912         /// Basic usage:
1913         ///
1914         /// ```
1915         #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".pow(5), 32);")]
1916         /// ```
1917         #[stable(feature = "rust1", since = "1.0.0")]
1918         #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
1919         #[must_use = "this returns the result of the operation, \
1920                       without modifying the original"]
1921         #[inline]
1922         #[rustc_inherit_overflow_checks]
1923         pub const fn pow(self, mut exp: u32) -> Self {
1924             if exp == 0 {
1925                 return 1;
1926             }
1927             let mut base = self;
1928             let mut acc = 1;
1929
1930             while exp > 1 {
1931                 if (exp & 1) == 1 {
1932                     acc = acc * base;
1933                 }
1934                 exp /= 2;
1935                 base = base * base;
1936             }
1937
1938             // since exp!=0, finally the exp must be 1.
1939             // Deal with the final bit of the exponent separately, since
1940             // squaring the base afterwards is not necessary and may cause a
1941             // needless overflow.
1942             acc * base
1943         }
1944
1945         /// Performs Euclidean division.
1946         ///
1947         /// Since, for the positive integers, all common
1948         /// definitions of division are equal, this
1949         /// is exactly equal to `self / rhs`.
1950         ///
1951         /// # Panics
1952         ///
1953         /// This function will panic if `rhs` is 0.
1954         ///
1955         /// # Examples
1956         ///
1957         /// Basic usage:
1958         ///
1959         /// ```
1960         #[doc = concat!("assert_eq!(7", stringify!($SelfT), ".div_euclid(4), 1); // or any other integer type")]
1961         /// ```
1962         #[stable(feature = "euclidean_division", since = "1.38.0")]
1963         #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
1964         #[must_use = "this returns the result of the operation, \
1965                       without modifying the original"]
1966         #[inline(always)]
1967         #[rustc_inherit_overflow_checks]
1968         pub const fn div_euclid(self, rhs: Self) -> Self {
1969             self / rhs
1970         }
1971
1972
1973         /// Calculates the least remainder of `self (mod rhs)`.
1974         ///
1975         /// Since, for the positive integers, all common
1976         /// definitions of division are equal, this
1977         /// is exactly equal to `self % rhs`.
1978         ///
1979         /// # Panics
1980         ///
1981         /// This function will panic if `rhs` is 0.
1982         ///
1983         /// # Examples
1984         ///
1985         /// Basic usage:
1986         ///
1987         /// ```
1988         #[doc = concat!("assert_eq!(7", stringify!($SelfT), ".rem_euclid(4), 3); // or any other integer type")]
1989         /// ```
1990         #[stable(feature = "euclidean_division", since = "1.38.0")]
1991         #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
1992         #[must_use = "this returns the result of the operation, \
1993                       without modifying the original"]
1994         #[inline(always)]
1995         #[rustc_inherit_overflow_checks]
1996         pub const fn rem_euclid(self, rhs: Self) -> Self {
1997             self % rhs
1998         }
1999
2000         /// Calculates the quotient of `self` and `rhs`, rounding the result towards negative infinity.
2001         ///
2002         /// This is the same as performing `self / rhs` for all unsigned integers.
2003         ///
2004         /// # Panics
2005         ///
2006         /// This function will panic if `rhs` is zero.
2007         ///
2008         /// # Examples
2009         ///
2010         /// Basic usage:
2011         ///
2012         /// ```
2013         /// #![feature(int_roundings)]
2014         #[doc = concat!("assert_eq!(7_", stringify!($SelfT), ".div_floor(4), 1);")]
2015         /// ```
2016         #[unstable(feature = "int_roundings", issue = "88581")]
2017         #[must_use = "this returns the result of the operation, \
2018                       without modifying the original"]
2019         #[inline(always)]
2020         pub const fn div_floor(self, rhs: Self) -> Self {
2021             self / rhs
2022         }
2023
2024         /// Calculates the quotient of `self` and `rhs`, rounding the result towards positive infinity.
2025         ///
2026         /// # Panics
2027         ///
2028         /// This function will panic if `rhs` is zero.
2029         ///
2030         /// ## Overflow behavior
2031         ///
2032         /// On overflow, this function will panic if overflow checks are enabled (default in debug
2033         /// mode) and wrap if overflow checks are disabled (default in release mode).
2034         ///
2035         /// # Examples
2036         ///
2037         /// Basic usage:
2038         ///
2039         /// ```
2040         /// #![feature(int_roundings)]
2041         #[doc = concat!("assert_eq!(7_", stringify!($SelfT), ".div_ceil(4), 2);")]
2042         /// ```
2043         #[unstable(feature = "int_roundings", issue = "88581")]
2044         #[must_use = "this returns the result of the operation, \
2045                       without modifying the original"]
2046         #[inline]
2047         #[rustc_inherit_overflow_checks]
2048         pub const fn div_ceil(self, rhs: Self) -> Self {
2049             let d = self / rhs;
2050             let r = self % rhs;
2051             if r > 0 && rhs > 0 {
2052                 d + 1
2053             } else {
2054                 d
2055             }
2056         }
2057
2058         /// Calculates the smallest value greater than or equal to `self` that
2059         /// is a multiple of `rhs`.
2060         ///
2061         /// # Panics
2062         ///
2063         /// This function will panic if `rhs` is zero.
2064         ///
2065         /// ## Overflow behavior
2066         ///
2067         /// On overflow, this function will panic if overflow checks are enabled (default in debug
2068         /// mode) and wrap if overflow checks are disabled (default in release mode).
2069         ///
2070         /// # Examples
2071         ///
2072         /// Basic usage:
2073         ///
2074         /// ```
2075         /// #![feature(int_roundings)]
2076         #[doc = concat!("assert_eq!(16_", stringify!($SelfT), ".next_multiple_of(8), 16);")]
2077         #[doc = concat!("assert_eq!(23_", stringify!($SelfT), ".next_multiple_of(8), 24);")]
2078         /// ```
2079         #[unstable(feature = "int_roundings", issue = "88581")]
2080         #[must_use = "this returns the result of the operation, \
2081                       without modifying the original"]
2082         #[inline]
2083         #[rustc_inherit_overflow_checks]
2084         pub const fn next_multiple_of(self, rhs: Self) -> Self {
2085             match self % rhs {
2086                 0 => self,
2087                 r => self + (rhs - r)
2088             }
2089         }
2090
2091         /// Calculates the smallest value greater than or equal to `self` that
2092         /// is a multiple of `rhs`. Returns `None` if `rhs` is zero or the
2093         /// operation would result in overflow.
2094         ///
2095         /// # Examples
2096         ///
2097         /// Basic usage:
2098         ///
2099         /// ```
2100         /// #![feature(int_roundings)]
2101         #[doc = concat!("assert_eq!(16_", stringify!($SelfT), ".checked_next_multiple_of(8), Some(16));")]
2102         #[doc = concat!("assert_eq!(23_", stringify!($SelfT), ".checked_next_multiple_of(8), Some(24));")]
2103         #[doc = concat!("assert_eq!(1_", stringify!($SelfT), ".checked_next_multiple_of(0), None);")]
2104         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_next_multiple_of(2), None);")]
2105         /// ```
2106         #[unstable(feature = "int_roundings", issue = "88581")]
2107         #[must_use = "this returns the result of the operation, \
2108                       without modifying the original"]
2109         #[inline]
2110         pub const fn checked_next_multiple_of(self, rhs: Self) -> Option<Self> {
2111             match try_opt!(self.checked_rem(rhs)) {
2112                 0 => Some(self),
2113                 // rhs - r cannot overflow because r is smaller than rhs
2114                 r => self.checked_add(rhs - r)
2115             }
2116         }
2117
2118         /// Returns `true` if and only if `self == 2^k` for some `k`.
2119         ///
2120         /// # Examples
2121         ///
2122         /// Basic usage:
2123         ///
2124         /// ```
2125         #[doc = concat!("assert!(16", stringify!($SelfT), ".is_power_of_two());")]
2126         #[doc = concat!("assert!(!10", stringify!($SelfT), ".is_power_of_two());")]
2127         /// ```
2128         #[must_use]
2129         #[stable(feature = "rust1", since = "1.0.0")]
2130         #[rustc_const_stable(feature = "const_is_power_of_two", since = "1.32.0")]
2131         #[inline(always)]
2132         pub const fn is_power_of_two(self) -> bool {
2133             self.count_ones() == 1
2134         }
2135
2136         // Returns one less than next power of two.
2137         // (For 8u8 next power of two is 8u8 and for 6u8 it is 8u8)
2138         //
2139         // 8u8.one_less_than_next_power_of_two() == 7
2140         // 6u8.one_less_than_next_power_of_two() == 7
2141         //
2142         // This method cannot overflow, as in the `next_power_of_two`
2143         // overflow cases it instead ends up returning the maximum value
2144         // of the type, and can return 0 for 0.
2145         #[inline]
2146         #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
2147         const fn one_less_than_next_power_of_two(self) -> Self {
2148             if self <= 1 { return 0; }
2149
2150             let p = self - 1;
2151             // SAFETY: Because `p > 0`, it cannot consist entirely of leading zeros.
2152             // That means the shift is always in-bounds, and some processors
2153             // (such as intel pre-haswell) have more efficient ctlz
2154             // intrinsics when the argument is non-zero.
2155             let z = unsafe { intrinsics::ctlz_nonzero(p) };
2156             <$SelfT>::MAX >> z
2157         }
2158
2159         /// Returns the smallest power of two greater than or equal to `self`.
2160         ///
2161         /// When return value overflows (i.e., `self > (1 << (N-1))` for type
2162         /// `uN`), it panics in debug mode and the return value is wrapped to 0 in
2163         /// release mode (the only situation in which method can return 0).
2164         ///
2165         /// # Examples
2166         ///
2167         /// Basic usage:
2168         ///
2169         /// ```
2170         #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".next_power_of_two(), 2);")]
2171         #[doc = concat!("assert_eq!(3", stringify!($SelfT), ".next_power_of_two(), 4);")]
2172         /// ```
2173         #[stable(feature = "rust1", since = "1.0.0")]
2174         #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
2175         #[must_use = "this returns the result of the operation, \
2176                       without modifying the original"]
2177         #[inline]
2178         #[rustc_inherit_overflow_checks]
2179         pub const fn next_power_of_two(self) -> Self {
2180             self.one_less_than_next_power_of_two() + 1
2181         }
2182
2183         /// Returns the smallest power of two greater than or equal to `n`. If
2184         /// the next power of two is greater than the type's maximum value,
2185         /// `None` is returned, otherwise the power of two is wrapped in `Some`.
2186         ///
2187         /// # Examples
2188         ///
2189         /// Basic usage:
2190         ///
2191         /// ```
2192         #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".checked_next_power_of_two(), Some(2));")]
2193         #[doc = concat!("assert_eq!(3", stringify!($SelfT), ".checked_next_power_of_two(), Some(4));")]
2194         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_next_power_of_two(), None);")]
2195         /// ```
2196         #[inline]
2197         #[stable(feature = "rust1", since = "1.0.0")]
2198         #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
2199         #[must_use = "this returns the result of the operation, \
2200                       without modifying the original"]
2201         pub const fn checked_next_power_of_two(self) -> Option<Self> {
2202             self.one_less_than_next_power_of_two().checked_add(1)
2203         }
2204
2205         /// Returns the smallest power of two greater than or equal to `n`. If
2206         /// the next power of two is greater than the type's maximum value,
2207         /// the return value is wrapped to `0`.
2208         ///
2209         /// # Examples
2210         ///
2211         /// Basic usage:
2212         ///
2213         /// ```
2214         /// #![feature(wrapping_next_power_of_two)]
2215         ///
2216         #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".wrapping_next_power_of_two(), 2);")]
2217         #[doc = concat!("assert_eq!(3", stringify!($SelfT), ".wrapping_next_power_of_two(), 4);")]
2218         #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.wrapping_next_power_of_two(), 0);")]
2219         /// ```
2220         #[inline]
2221         #[unstable(feature = "wrapping_next_power_of_two", issue = "32463",
2222                    reason = "needs decision on wrapping behaviour")]
2223         #[rustc_const_unstable(feature = "wrapping_next_power_of_two", issue = "32463")]
2224         #[must_use = "this returns the result of the operation, \
2225                       without modifying the original"]
2226         pub const fn wrapping_next_power_of_two(self) -> Self {
2227             self.one_less_than_next_power_of_two().wrapping_add(1)
2228         }
2229
2230         /// Return the memory representation of this integer as a byte array in
2231         /// big-endian (network) byte order.
2232         ///
2233         #[doc = $to_xe_bytes_doc]
2234         ///
2235         /// # Examples
2236         ///
2237         /// ```
2238         #[doc = concat!("let bytes = ", $swap_op, stringify!($SelfT), ".to_be_bytes();")]
2239         #[doc = concat!("assert_eq!(bytes, ", $be_bytes, ");")]
2240         /// ```
2241         #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2242         #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2243         #[must_use = "this returns the result of the operation, \
2244                       without modifying the original"]
2245         #[inline]
2246         pub const fn to_be_bytes(self) -> [u8; mem::size_of::<Self>()] {
2247             self.to_be().to_ne_bytes()
2248         }
2249
2250         /// Return the memory representation of this integer as a byte array in
2251         /// little-endian byte order.
2252         ///
2253         #[doc = $to_xe_bytes_doc]
2254         ///
2255         /// # Examples
2256         ///
2257         /// ```
2258         #[doc = concat!("let bytes = ", $swap_op, stringify!($SelfT), ".to_le_bytes();")]
2259         #[doc = concat!("assert_eq!(bytes, ", $le_bytes, ");")]
2260         /// ```
2261         #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2262         #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2263         #[must_use = "this returns the result of the operation, \
2264                       without modifying the original"]
2265         #[inline]
2266         pub const fn to_le_bytes(self) -> [u8; mem::size_of::<Self>()] {
2267             self.to_le().to_ne_bytes()
2268         }
2269
2270         /// Return the memory representation of this integer as a byte array in
2271         /// native byte order.
2272         ///
2273         /// As the target platform's native endianness is used, portable code
2274         /// should use [`to_be_bytes`] or [`to_le_bytes`], as appropriate,
2275         /// instead.
2276         ///
2277         #[doc = $to_xe_bytes_doc]
2278         ///
2279         /// [`to_be_bytes`]: Self::to_be_bytes
2280         /// [`to_le_bytes`]: Self::to_le_bytes
2281         ///
2282         /// # Examples
2283         ///
2284         /// ```
2285         #[doc = concat!("let bytes = ", $swap_op, stringify!($SelfT), ".to_ne_bytes();")]
2286         /// assert_eq!(
2287         ///     bytes,
2288         ///     if cfg!(target_endian = "big") {
2289         #[doc = concat!("        ", $be_bytes)]
2290         ///     } else {
2291         #[doc = concat!("        ", $le_bytes)]
2292         ///     }
2293         /// );
2294         /// ```
2295         #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2296         #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2297         #[must_use = "this returns the result of the operation, \
2298                       without modifying the original"]
2299         // SAFETY: const sound because integers are plain old datatypes so we can always
2300         // transmute them to arrays of bytes
2301         #[inline]
2302         pub const fn to_ne_bytes(self) -> [u8; mem::size_of::<Self>()] {
2303             // SAFETY: integers are plain old datatypes so we can always transmute them to
2304             // arrays of bytes
2305             unsafe { mem::transmute(self) }
2306         }
2307
2308         /// Create a native endian integer value from its representation
2309         /// as a byte array in big endian.
2310         ///
2311         #[doc = $from_xe_bytes_doc]
2312         ///
2313         /// # Examples
2314         ///
2315         /// ```
2316         #[doc = concat!("let value = ", stringify!($SelfT), "::from_be_bytes(", $be_bytes, ");")]
2317         #[doc = concat!("assert_eq!(value, ", $swap_op, ");")]
2318         /// ```
2319         ///
2320         /// When starting from a slice rather than an array, fallible conversion APIs can be used:
2321         ///
2322         /// ```
2323         #[doc = concat!("fn read_be_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {")]
2324         #[doc = concat!("    let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());")]
2325         ///     *input = rest;
2326         #[doc = concat!("    ", stringify!($SelfT), "::from_be_bytes(int_bytes.try_into().unwrap())")]
2327         /// }
2328         /// ```
2329         #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2330         #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2331         #[must_use]
2332         #[inline]
2333         pub const fn from_be_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
2334             Self::from_be(Self::from_ne_bytes(bytes))
2335         }
2336
2337         /// Create a native endian integer value from its representation
2338         /// as a byte array in little endian.
2339         ///
2340         #[doc = $from_xe_bytes_doc]
2341         ///
2342         /// # Examples
2343         ///
2344         /// ```
2345         #[doc = concat!("let value = ", stringify!($SelfT), "::from_le_bytes(", $le_bytes, ");")]
2346         #[doc = concat!("assert_eq!(value, ", $swap_op, ");")]
2347         /// ```
2348         ///
2349         /// When starting from a slice rather than an array, fallible conversion APIs can be used:
2350         ///
2351         /// ```
2352         #[doc = concat!("fn read_le_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {")]
2353         #[doc = concat!("    let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());")]
2354         ///     *input = rest;
2355         #[doc = concat!("    ", stringify!($SelfT), "::from_le_bytes(int_bytes.try_into().unwrap())")]
2356         /// }
2357         /// ```
2358         #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2359         #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2360         #[must_use]
2361         #[inline]
2362         pub const fn from_le_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
2363             Self::from_le(Self::from_ne_bytes(bytes))
2364         }
2365
2366         /// Create a native endian integer value from its memory representation
2367         /// as a byte array in native endianness.
2368         ///
2369         /// As the target platform's native endianness is used, portable code
2370         /// likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as
2371         /// appropriate instead.
2372         ///
2373         /// [`from_be_bytes`]: Self::from_be_bytes
2374         /// [`from_le_bytes`]: Self::from_le_bytes
2375         ///
2376         #[doc = $from_xe_bytes_doc]
2377         ///
2378         /// # Examples
2379         ///
2380         /// ```
2381         #[doc = concat!("let value = ", stringify!($SelfT), "::from_ne_bytes(if cfg!(target_endian = \"big\") {")]
2382         #[doc = concat!("    ", $be_bytes, "")]
2383         /// } else {
2384         #[doc = concat!("    ", $le_bytes, "")]
2385         /// });
2386         #[doc = concat!("assert_eq!(value, ", $swap_op, ");")]
2387         /// ```
2388         ///
2389         /// When starting from a slice rather than an array, fallible conversion APIs can be used:
2390         ///
2391         /// ```
2392         #[doc = concat!("fn read_ne_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {")]
2393         #[doc = concat!("    let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());")]
2394         ///     *input = rest;
2395         #[doc = concat!("    ", stringify!($SelfT), "::from_ne_bytes(int_bytes.try_into().unwrap())")]
2396         /// }
2397         /// ```
2398         #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2399         #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2400         #[must_use]
2401         // SAFETY: const sound because integers are plain old datatypes so we can always
2402         // transmute to them
2403         #[inline]
2404         pub const fn from_ne_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
2405             // SAFETY: integers are plain old datatypes so we can always transmute to them
2406             unsafe { mem::transmute(bytes) }
2407         }
2408
2409         /// New code should prefer to use
2410         #[doc = concat!("[`", stringify!($SelfT), "::MIN", "`] instead.")]
2411         ///
2412         /// Returns the smallest value that can be represented by this integer type.
2413         #[stable(feature = "rust1", since = "1.0.0")]
2414         #[rustc_promotable]
2415         #[inline(always)]
2416         #[rustc_const_stable(feature = "const_max_value", since = "1.32.0")]
2417         #[deprecated(since = "TBD", note = "replaced by the `MIN` associated constant on this type")]
2418         pub const fn min_value() -> Self { Self::MIN }
2419
2420         /// New code should prefer to use
2421         #[doc = concat!("[`", stringify!($SelfT), "::MAX", "`] instead.")]
2422         ///
2423         /// Returns the largest value that can be represented by this integer type.
2424         #[stable(feature = "rust1", since = "1.0.0")]
2425         #[rustc_promotable]
2426         #[inline(always)]
2427         #[rustc_const_stable(feature = "const_max_value", since = "1.32.0")]
2428         #[deprecated(since = "TBD", note = "replaced by the `MAX` associated constant on this type")]
2429         pub const fn max_value() -> Self { Self::MAX }
2430     }
2431 }