src/libcore/num/mod.rs

   1 // ignore-tidy-filelength
   2
   3 //! Numeric traits and functions for the built-in numeric types.
   4
   5 #![stable(feature = "rust1", since = "1.0.0")]
   6
   7 use crate::convert::{TryFrom, Infallible};
   8 use crate::fmt;
   9 use crate::intrinsics;
  10 use crate::mem;
  11 use crate::ops;
  12 use crate::str::FromStr;
  13
  14 macro_rules! impl_nonzero_fmt {
  15     ( #[$stability: meta] ( $( $Trait: ident ),+ ) for $Ty: ident ) => {
  16         $(
  17             #[$stability]
  18             impl fmt::$Trait for $Ty {
  19                 #[inline]
  20                 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
  21                     self.get().fmt(f)
  22                 }
  23             }
  24         )+
  25     }
  26 }
  27
  28 macro_rules! doc_comment {
  29     ($x:expr, $($tt:tt)*) => {
  30         #[doc = $x]
  31         $($tt)*
  32     };
  33 }
  34
  35 macro_rules! nonzero_integers {
  36     ( $( #[$stability: meta] $Ty: ident($Int: ty); )+ ) => {
  37         $(
  38             doc_comment! {
  39                 concat!("An integer that is known not to equal zero.
  40
  41 This enables some memory layout optimization.
  42 For example, `Option<", stringify!($Ty), ">` is the same size as `", stringify!($Int), "`:
  43
  44 ```rust
  45 use std::mem::size_of;
  46 assert_eq!(size_of::<Option<core::num::", stringify!($Ty), ">>(), size_of::<", stringify!($Int),
  47 ">());
  48 ```"),
  49                 #[$stability]
  50                 #[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
  51                 #[repr(transparent)]
  52                 #[rustc_layout_scalar_valid_range_start(1)]
  53                 #[cfg_attr(not(stage0), rustc_nonnull_optimization_guaranteed)]
  54                 pub struct $Ty($Int);
  55             }
  56
  57             impl $Ty {
  58                 /// Creates a non-zero without checking the value.
  59                 ///
  60                 /// # Safety
  61                 ///
  62                 /// The value must not be zero.
  63                 #[$stability]
  64                 #[inline]
  65                 pub const unsafe fn new_unchecked(n: $Int) -> Self {
  66                     $Ty(n)
  67                 }
  68
  69                 /// Creates a non-zero if the given value is not zero.
  70                 #[$stability]
  71                 #[inline]
  72                 pub fn new(n: $Int) -> Option<Self> {
  73                     if n != 0 {
  74                         Some(unsafe { $Ty(n) })
  75                     } else {
  76                         None
  77                     }
  78                 }
  79
  80                 /// Returns the value as a primitive type.
  81                 #[$stability]
  82                 #[inline]
  83                 pub const fn get(self) -> $Int {
  84                     self.0
  85                 }
  86
  87             }
  88
  89             #[stable(feature = "from_nonzero", since = "1.31.0")]
  90             impl From<$Ty> for $Int {
  91                 fn from(nonzero: $Ty) -> Self {
  92                     nonzero.0
  93                 }
  94             }
  95
  96             impl_nonzero_fmt! {
  97                 #[$stability] (Debug, Display, Binary, Octal, LowerHex, UpperHex) for $Ty
  98             }
  99         )+
 100     }
 101 }
 102
 103 nonzero_integers! {
 104     #[stable(feature = "nonzero", since = "1.28.0")] NonZeroU8(u8);
 105     #[stable(feature = "nonzero", since = "1.28.0")] NonZeroU16(u16);
 106     #[stable(feature = "nonzero", since = "1.28.0")] NonZeroU32(u32);
 107     #[stable(feature = "nonzero", since = "1.28.0")] NonZeroU64(u64);
 108     #[stable(feature = "nonzero", since = "1.28.0")] NonZeroU128(u128);
 109     #[stable(feature = "nonzero", since = "1.28.0")] NonZeroUsize(usize);
 110     #[stable(feature = "signed_nonzero", since = "1.34.0")] NonZeroI8(i8);
 111     #[stable(feature = "signed_nonzero", since = "1.34.0")] NonZeroI16(i16);
 112     #[stable(feature = "signed_nonzero", since = "1.34.0")] NonZeroI32(i32);
 113     #[stable(feature = "signed_nonzero", since = "1.34.0")] NonZeroI64(i64);
 114     #[stable(feature = "signed_nonzero", since = "1.34.0")] NonZeroI128(i128);
 115     #[stable(feature = "signed_nonzero", since = "1.34.0")] NonZeroIsize(isize);
 116 }
 117
 118 macro_rules! from_str_radix_nzint_impl {
 119     ($($t:ty)*) => {$(
 120         #[stable(feature = "nonzero_parse", since = "1.35.0")]
 121         impl FromStr for $t {
 122             type Err = ParseIntError;
 123             fn from_str(src: &str) -> Result<Self, Self::Err> {
 124                 Self::new(from_str_radix(src, 10)?)
 125                     .ok_or(ParseIntError {
 126                         kind: IntErrorKind::Zero
 127                     })
 128             }
 129         }
 130     )*}
 131 }
 132
 133 from_str_radix_nzint_impl! { NonZeroU8 NonZeroU16 NonZeroU32 NonZeroU64 NonZeroU128 NonZeroUsize
 134                              NonZeroI8 NonZeroI16 NonZeroI32 NonZeroI64 NonZeroI128 NonZeroIsize }
 135
 136 /// Provides intentionally-wrapped arithmetic on `T`.
 137 ///
 138 /// Operations like `+` on `u32` values is intended to never overflow,
 139 /// and in some debug configurations overflow is detected and results
 140 /// in a panic. While most arithmetic falls into this category, some
 141 /// code explicitly expects and relies upon modular arithmetic (e.g.,
 142 /// hashing).
 143 ///
 144 /// Wrapping arithmetic can be achieved either through methods like
 145 /// `wrapping_add`, or through the `Wrapping<T>` type, which says that
 146 /// all standard arithmetic operations on the underlying value are
 147 /// intended to have wrapping semantics.
 148 ///
 149 /// The underlying value can be retrieved through the `.0` index of the
 150 /// `Wrapping` tuple.
 151 ///
 152 /// # Examples
 153 ///
 154 /// ```
 155 /// use std::num::Wrapping;
 156 ///
 157 /// let zero = Wrapping(0u32);
 158 /// let one = Wrapping(1u32);
 159 ///
 160 /// assert_eq!(std::u32::MAX, (zero - one).0);
 161 /// ```
 162 #[stable(feature = "rust1", since = "1.0.0")]
 163 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Copy, Default, Hash)]
 164 #[repr(transparent)]
 165 pub struct Wrapping<T>(#[stable(feature = "rust1", since = "1.0.0")]
 166                        pub T);
 167
 168 #[stable(feature = "rust1", since = "1.0.0")]
 169 impl<T: fmt::Debug> fmt::Debug for Wrapping<T> {
 170     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 171         self.0.fmt(f)
 172     }
 173 }
 174
 175 #[stable(feature = "wrapping_display", since = "1.10.0")]
 176 impl<T: fmt::Display> fmt::Display for Wrapping<T> {
 177     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 178         self.0.fmt(f)
 179     }
 180 }
 181
 182 #[stable(feature = "wrapping_fmt", since = "1.11.0")]
 183 impl<T: fmt::Binary> fmt::Binary for Wrapping<T> {
 184     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 185         self.0.fmt(f)
 186     }
 187 }
 188
 189 #[stable(feature = "wrapping_fmt", since = "1.11.0")]
 190 impl<T: fmt::Octal> fmt::Octal for Wrapping<T> {
 191     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 192         self.0.fmt(f)
 193     }
 194 }
 195
 196 #[stable(feature = "wrapping_fmt", since = "1.11.0")]
 197 impl<T: fmt::LowerHex> fmt::LowerHex for Wrapping<T> {
 198     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 199         self.0.fmt(f)
 200     }
 201 }
 202
 203 #[stable(feature = "wrapping_fmt", since = "1.11.0")]
 204 impl<T: fmt::UpperHex> fmt::UpperHex for Wrapping<T> {
 205     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 206         self.0.fmt(f)
 207     }
 208 }
 209
 210 // All these modules are technically private and only exposed for coretests:
 211 pub mod flt2dec;
 212 pub mod dec2flt;
 213 pub mod bignum;
 214 pub mod diy_float;
 215
 216 mod wrapping;
 217
 218 macro_rules! usize_isize_to_xe_bytes_doc {
 219     () => {"
 220
 221 **Note**: This function returns an array of length 2, 4 or 8 bytes
 222 depending on the target pointer size.
 223
 224 "}
 225 }
 226
 227
 228 macro_rules! usize_isize_from_xe_bytes_doc {
 229     () => {"
 230
 231 **Note**: This function takes an array of length 2, 4 or 8 bytes
 232 depending on the target pointer size.
 233
 234 "}
 235 }
 236
 237 // `Int` + `SignedInt` implemented for signed integers
 238 macro_rules! int_impl {
 239     ($SelfT:ty, $ActualT:ident, $UnsignedT:ty, $BITS:expr, $Min:expr, $Max:expr, $Feature:expr,
 240      $EndFeature:expr, $rot:expr, $rot_op:expr, $rot_result:expr, $swap_op:expr, $swapped:expr,
 241      $reversed:expr, $le_bytes:expr, $be_bytes:expr,
 242      $to_xe_bytes_doc:expr, $from_xe_bytes_doc:expr) => {
 243         doc_comment! {
 244             concat!("Returns the smallest value that can be represented by this integer type.
 245
 246 # Examples
 247
 248 Basic usage:
 249
 250 ```
 251 ", $Feature, "assert_eq!(", stringify!($SelfT), "::min_value(), ", stringify!($Min), ");",
 252 $EndFeature, "
 253 ```"),
 254             #[stable(feature = "rust1", since = "1.0.0")]
 255             #[inline]
 256             #[rustc_promotable]
 257             pub const fn min_value() -> Self {
 258                 !0 ^ ((!0 as $UnsignedT) >> 1) as Self
 259             }
 260         }
 261
 262         doc_comment! {
 263             concat!("Returns the largest value that can be represented by this integer type.
 264
 265 # Examples
 266
 267 Basic usage:
 268
 269 ```
 270 ", $Feature, "assert_eq!(", stringify!($SelfT), "::max_value(), ", stringify!($Max), ");",
 271 $EndFeature, "
 272 ```"),
 273             #[stable(feature = "rust1", since = "1.0.0")]
 274             #[inline]
 275             #[rustc_promotable]
 276             pub const fn max_value() -> Self {
 277                 !Self::min_value()
 278             }
 279         }
 280
 281         doc_comment! {
 282             concat!("Converts a string slice in a given base to an integer.
 283
 284 The string is expected to be an optional `+` or `-` sign followed by digits.
 285 Leading and trailing whitespace represent an error. Digits are a subset of these characters,
 286 depending on `radix`:
 287
 288  * `0-9`
 289  * `a-z`
 290  * `A-Z`
 291
 292 # Panics
 293
 294 This function panics if `radix` is not in the range from 2 to 36.
 295
 296 # Examples
 297
 298 Basic usage:
 299
 300 ```
 301 ", $Feature, "assert_eq!(", stringify!($SelfT), "::from_str_radix(\"A\", 16), Ok(10));",
 302 $EndFeature, "
 303 ```"),
 304             #[stable(feature = "rust1", since = "1.0.0")]
 305             pub fn from_str_radix(src: &str, radix: u32) -> Result<Self, ParseIntError> {
 306                 from_str_radix(src, radix)
 307             }
 308         }
 309
 310         doc_comment! {
 311             concat!("Returns the number of ones in the binary representation of `self`.
 312
 313 # Examples
 314
 315 Basic usage:
 316
 317 ```
 318 ", $Feature, "let n = 0b100_0000", stringify!($SelfT), ";
 319
 320 assert_eq!(n.count_ones(), 1);",
 321 $EndFeature, "
 322 ```
 323 "),
 324             #[stable(feature = "rust1", since = "1.0.0")]
 325             #[inline]
 326             pub const fn count_ones(self) -> u32 { (self as $UnsignedT).count_ones() }
 327         }
 328
 329         doc_comment! {
 330             concat!("Returns the number of zeros in the binary representation of `self`.
 331
 332 # Examples
 333
 334 Basic usage:
 335
 336 ```
 337 ", $Feature, "assert_eq!(", stringify!($SelfT), "::max_value().count_zeros(), 1);", $EndFeature, "
 338 ```"),
 339             #[stable(feature = "rust1", since = "1.0.0")]
 340             #[inline]
 341             pub const fn count_zeros(self) -> u32 {
 342                 (!self).count_ones()
 343             }
 344         }
 345
 346         doc_comment! {
 347             concat!("Returns the number of leading zeros in the binary representation of `self`.
 348
 349 # Examples
 350
 351 Basic usage:
 352
 353 ```
 354 ", $Feature, "let n = -1", stringify!($SelfT), ";
 355
 356 assert_eq!(n.leading_zeros(), 0);",
 357 $EndFeature, "
 358 ```"),
 359             #[stable(feature = "rust1", since = "1.0.0")]
 360             #[inline]
 361             pub const fn leading_zeros(self) -> u32 {
 362                 (self as $UnsignedT).leading_zeros()
 363             }
 364         }
 365
 366         doc_comment! {
 367             concat!("Returns the number of trailing zeros in the binary representation of `self`.
 368
 369 # Examples
 370
 371 Basic usage:
 372
 373 ```
 374 ", $Feature, "let n = -4", stringify!($SelfT), ";
 375
 376 assert_eq!(n.trailing_zeros(), 2);",
 377 $EndFeature, "
 378 ```"),
 379             #[stable(feature = "rust1", since = "1.0.0")]
 380             #[inline]
 381             pub const fn trailing_zeros(self) -> u32 {
 382                 (self as $UnsignedT).trailing_zeros()
 383             }
 384         }
 385
 386         doc_comment! {
 387             concat!("Shifts the bits to the left by a specified amount, `n`,
 388 wrapping the truncated bits to the end of the resulting integer.
 389
 390 Please note this isn't the same operation as the `<<` shifting operator!
 391
 392 # Examples
 393
 394 Basic usage:
 395
 396 ```
 397 let n = ", $rot_op, stringify!($SelfT), ";
 398 let m = ", $rot_result, ";
 399
 400 assert_eq!(n.rotate_left(", $rot, "), m);
 401 ```"),
 402             #[stable(feature = "rust1", since = "1.0.0")]
 403             #[must_use = "this returns the result of the operation, \
 404                           without modifying the original"]
 405             #[inline]
 406             pub const fn rotate_left(self, n: u32) -> Self {
 407                 (self as $UnsignedT).rotate_left(n) as Self
 408             }
 409         }
 410
 411         doc_comment! {
 412             concat!("Shifts the bits to the right by a specified amount, `n`,
 413 wrapping the truncated bits to the beginning of the resulting
 414 integer.
 415
 416 Please note this isn't the same operation as the `>>` shifting operator!
 417
 418 # Examples
 419
 420 Basic usage:
 421
 422 ```
 423 let n = ", $rot_result, stringify!($SelfT), ";
 424 let m = ", $rot_op, ";
 425
 426 assert_eq!(n.rotate_right(", $rot, "), m);
 427 ```"),
 428             #[stable(feature = "rust1", since = "1.0.0")]
 429             #[must_use = "this returns the result of the operation, \
 430                           without modifying the original"]
 431             #[inline]
 432             pub const fn rotate_right(self, n: u32) -> Self {
 433                 (self as $UnsignedT).rotate_right(n) as Self
 434             }
 435         }
 436
 437         doc_comment! {
 438             concat!("Reverses the byte order of the integer.
 439
 440 # Examples
 441
 442 Basic usage:
 443
 444 ```
 445 let n = ", $swap_op, stringify!($SelfT), ";
 446
 447 let m = n.swap_bytes();
 448
 449 assert_eq!(m, ", $swapped, ");
 450 ```"),
 451             #[stable(feature = "rust1", since = "1.0.0")]
 452             #[inline]
 453             pub const fn swap_bytes(self) -> Self {
 454                 (self as $UnsignedT).swap_bytes() as Self
 455             }
 456         }
 457
 458         doc_comment! {
 459             concat!("Reverses the bit pattern of the integer.
 460
 461 # Examples
 462
 463 Basic usage:
 464
 465 ```
 466 #![feature(reverse_bits)]
 467
 468 let n = ", $swap_op, stringify!($SelfT), ";
 469 let m = n.reverse_bits();
 470
 471 assert_eq!(m, ", $reversed, ");
 472 ```"),
 473             #[unstable(feature = "reverse_bits", issue = "48763")]
 474             #[rustc_const_unstable(feature = "const_int_conversion")]
 475             #[inline]
 476             pub const fn reverse_bits(self) -> Self {
 477                 (self as $UnsignedT).reverse_bits() as Self
 478             }
 479         }
 480
 481         doc_comment! {
 482             concat!("Converts an integer from big endian to the target's endianness.
 483
 484 On big endian this is a no-op. On little endian the bytes are swapped.
 485
 486 # Examples
 487
 488 Basic usage:
 489
 490 ```
 491 ", $Feature, "let n = 0x1A", stringify!($SelfT), ";
 492
 493 if cfg!(target_endian = \"big\") {
 494     assert_eq!(", stringify!($SelfT), "::from_be(n), n)
 495 } else {
 496     assert_eq!(", stringify!($SelfT), "::from_be(n), n.swap_bytes())
 497 }",
 498 $EndFeature, "
 499 ```"),
 500             #[stable(feature = "rust1", since = "1.0.0")]
 501             #[inline]
 502             pub const fn from_be(x: Self) -> Self {
 503                 #[cfg(target_endian = "big")]
 504                 {
 505                     x
 506                 }
 507                 #[cfg(not(target_endian = "big"))]
 508                 {
 509                     x.swap_bytes()
 510                 }
 511             }
 512         }
 513
 514         doc_comment! {
 515             concat!("Converts an integer from little endian to the target's endianness.
 516
 517 On little endian this is a no-op. On big endian the bytes are swapped.
 518
 519 # Examples
 520
 521 Basic usage:
 522
 523 ```
 524 ", $Feature, "let n = 0x1A", stringify!($SelfT), ";
 525
 526 if cfg!(target_endian = \"little\") {
 527     assert_eq!(", stringify!($SelfT), "::from_le(n), n)
 528 } else {
 529     assert_eq!(", stringify!($SelfT), "::from_le(n), n.swap_bytes())
 530 }",
 531 $EndFeature, "
 532 ```"),
 533             #[stable(feature = "rust1", since = "1.0.0")]
 534             #[inline]
 535             pub const fn from_le(x: Self) -> Self {
 536                 #[cfg(target_endian = "little")]
 537                 {
 538                     x
 539                 }
 540                 #[cfg(not(target_endian = "little"))]
 541                 {
 542                     x.swap_bytes()
 543                 }
 544             }
 545         }
 546
 547         doc_comment! {
 548             concat!("Converts `self` to big endian from the target's endianness.
 549
 550 On big endian this is a no-op. On little endian the bytes are swapped.
 551
 552 # Examples
 553
 554 Basic usage:
 555
 556 ```
 557 ", $Feature, "let n = 0x1A", stringify!($SelfT), ";
 558
 559 if cfg!(target_endian = \"big\") {
 560     assert_eq!(n.to_be(), n)
 561 } else {
 562     assert_eq!(n.to_be(), n.swap_bytes())
 563 }",
 564 $EndFeature, "
 565 ```"),
 566             #[stable(feature = "rust1", since = "1.0.0")]
 567             #[inline]
 568             pub const fn to_be(self) -> Self { // or not to be?
 569                 #[cfg(target_endian = "big")]
 570                 {
 571                     self
 572                 }
 573                 #[cfg(not(target_endian = "big"))]
 574                 {
 575                     self.swap_bytes()
 576                 }
 577             }
 578         }
 579
 580         doc_comment! {
 581             concat!("Converts `self` to little endian from the target's endianness.
 582
 583 On little endian this is a no-op. On big endian the bytes are swapped.
 584
 585 # Examples
 586
 587 Basic usage:
 588
 589 ```
 590 ", $Feature, "let n = 0x1A", stringify!($SelfT), ";
 591
 592 if cfg!(target_endian = \"little\") {
 593     assert_eq!(n.to_le(), n)
 594 } else {
 595     assert_eq!(n.to_le(), n.swap_bytes())
 596 }",
 597 $EndFeature, "
 598 ```"),
 599             #[stable(feature = "rust1", since = "1.0.0")]
 600             #[inline]
 601             pub const fn to_le(self) -> Self {
 602                 #[cfg(target_endian = "little")]
 603                 {
 604                     self
 605                 }
 606                 #[cfg(not(target_endian = "little"))]
 607                 {
 608                     self.swap_bytes()
 609                 }
 610             }
 611         }
 612
 613         doc_comment! {
 614             concat!("Checked integer addition. Computes `self + rhs`, returning `None`
 615 if overflow occurred.
 616
 617 # Examples
 618
 619 Basic usage:
 620
 621 ```
 622 ", $Feature, "assert_eq!((", stringify!($SelfT),
 623 "::max_value() - 2).checked_add(1), Some(", stringify!($SelfT), "::max_value() - 1));
 624 assert_eq!((", stringify!($SelfT), "::max_value() - 2).checked_add(3), None);",
 625 $EndFeature, "
 626 ```"),
 627             #[stable(feature = "rust1", since = "1.0.0")]
 628             #[must_use = "this returns the result of the operation, \
 629                           without modifying the original"]
 630             #[inline]
 631             pub fn checked_add(self, rhs: Self) -> Option<Self> {
 632                 let (a, b) = self.overflowing_add(rhs);
 633                 if b {None} else {Some(a)}
 634             }
 635         }
 636
 637         doc_comment! {
 638             concat!("Checked integer subtraction. Computes `self - rhs`, returning `None` if
 639 overflow occurred.
 640
 641 # Examples
 642
 643 Basic usage:
 644
 645 ```
 646 ", $Feature, "assert_eq!((", stringify!($SelfT),
 647 "::min_value() + 2).checked_sub(1), Some(", stringify!($SelfT), "::min_value() + 1));
 648 assert_eq!((", stringify!($SelfT), "::min_value() + 2).checked_sub(3), None);",
 649 $EndFeature, "
 650 ```"),
 651             #[stable(feature = "rust1", since = "1.0.0")]
 652             #[must_use = "this returns the result of the operation, \
 653                           without modifying the original"]
 654             #[inline]
 655             pub fn checked_sub(self, rhs: Self) -> Option<Self> {
 656                 let (a, b) = self.overflowing_sub(rhs);
 657                 if b {None} else {Some(a)}
 658             }
 659         }
 660
 661         doc_comment! {
 662             concat!("Checked integer multiplication. Computes `self * rhs`, returning `None` if
 663 overflow occurred.
 664
 665 # Examples
 666
 667 Basic usage:
 668
 669 ```
 670 ", $Feature, "assert_eq!(", stringify!($SelfT),
 671 "::max_value().checked_mul(1), Some(", stringify!($SelfT), "::max_value()));
 672 assert_eq!(", stringify!($SelfT), "::max_value().checked_mul(2), None);",
 673 $EndFeature, "
 674 ```"),
 675             #[stable(feature = "rust1", since = "1.0.0")]
 676             #[must_use = "this returns the result of the operation, \
 677                           without modifying the original"]
 678             #[inline]
 679             pub fn checked_mul(self, rhs: Self) -> Option<Self> {
 680                 let (a, b) = self.overflowing_mul(rhs);
 681                 if b {None} else {Some(a)}
 682             }
 683         }
 684
 685         doc_comment! {
 686             concat!("Checked integer division. Computes `self / rhs`, returning `None` if `rhs == 0`
 687 or the division results in overflow.
 688
 689 # Examples
 690
 691 Basic usage:
 692
 693 ```
 694 ", $Feature, "assert_eq!((", stringify!($SelfT),
 695 "::min_value() + 1).checked_div(-1), Some(", stringify!($Max), "));
 696 assert_eq!(", stringify!($SelfT), "::min_value().checked_div(-1), None);
 697 assert_eq!((1", stringify!($SelfT), ").checked_div(0), None);",
 698 $EndFeature, "
 699 ```"),
 700             #[stable(feature = "rust1", since = "1.0.0")]
 701             #[must_use = "this returns the result of the operation, \
 702                           without modifying the original"]
 703             #[inline]
 704             pub fn checked_div(self, rhs: Self) -> Option<Self> {
 705                 if rhs == 0 || (self == Self::min_value() && rhs == -1) {
 706                     None
 707                 } else {
 708                     Some(unsafe { intrinsics::unchecked_div(self, rhs) })
 709                 }
 710             }
 711         }
 712
 713         doc_comment! {
 714             concat!("Checked Euclidean division. Computes `self.div_euclid(rhs)`,
 715 returning `None` if `rhs == 0` or the division results in overflow.
 716
 717 # Examples
 718
 719 Basic usage:
 720
 721 ```
 722 #![feature(euclidean_division)]
 723 assert_eq!((", stringify!($SelfT),
 724 "::min_value() + 1).checked_div_euclid(-1), Some(", stringify!($Max), "));
 725 assert_eq!(", stringify!($SelfT), "::min_value().checked_div_euclid(-1), None);
 726 assert_eq!((1", stringify!($SelfT), ").checked_div_euclid(0), None);
 727 ```"),
 728             #[unstable(feature = "euclidean_division", issue = "49048")]
 729             #[must_use = "this returns the result of the operation, \
 730                           without modifying the original"]
 731             #[inline]
 732             pub fn checked_div_euclid(self, rhs: Self) -> Option<Self> {
 733                 if rhs == 0 || (self == Self::min_value() && rhs == -1) {
 734                     None
 735                 } else {
 736                     Some(self.div_euclid(rhs))
 737                 }
 738             }
 739         }
 740
 741         doc_comment! {
 742             concat!("Checked integer remainder. Computes `self % rhs`, returning `None` if
 743 `rhs == 0` or the division results in overflow.
 744
 745 # Examples
 746
 747 Basic usage:
 748
 749 ```
 750 ", $Feature, "use std::", stringify!($SelfT), ";
 751
 752 assert_eq!(5", stringify!($SelfT), ".checked_rem(2), Some(1));
 753 assert_eq!(5", stringify!($SelfT), ".checked_rem(0), None);
 754 assert_eq!(", stringify!($SelfT), "::MIN.checked_rem(-1), None);",
 755 $EndFeature, "
 756 ```"),
 757             #[stable(feature = "wrapping", since = "1.7.0")]
 758             #[must_use = "this returns the result of the operation, \
 759                           without modifying the original"]
 760             #[inline]
 761             pub fn checked_rem(self, rhs: Self) -> Option<Self> {
 762                 if rhs == 0 || (self == Self::min_value() && rhs == -1) {
 763                     None
 764                 } else {
 765                     Some(unsafe { intrinsics::unchecked_rem(self, rhs) })
 766                 }
 767             }
 768         }
 769
 770         doc_comment! {
 771             concat!("Checked Euclidean remainder. Computes `self.rem_euclid(rhs)`, returning `None`
 772 if `rhs == 0` or the division results in overflow.
 773
 774 # Examples
 775
 776 Basic usage:
 777
 778 ```
 779 #![feature(euclidean_division)]
 780 use std::", stringify!($SelfT), ";
 781
 782 assert_eq!(5", stringify!($SelfT), ".checked_rem_euclid(2), Some(1));
 783 assert_eq!(5", stringify!($SelfT), ".checked_rem_euclid(0), None);
 784 assert_eq!(", stringify!($SelfT), "::MIN.checked_rem_euclid(-1), None);
 785 ```"),
 786             #[unstable(feature = "euclidean_division", issue = "49048")]
 787             #[must_use = "this returns the result of the operation, \
 788                           without modifying the original"]
 789             #[inline]
 790             pub fn checked_rem_euclid(self, rhs: Self) -> Option<Self> {
 791                 if rhs == 0 || (self == Self::min_value() && rhs == -1) {
 792                     None
 793                 } else {
 794                     Some(self.rem_euclid(rhs))
 795                 }
 796             }
 797         }
 798
 799         doc_comment! {
 800             concat!("Checked negation. Computes `-self`, returning `None` if `self == MIN`.
 801
 802 # Examples
 803
 804 Basic usage:
 805
 806 ```
 807 ", $Feature, "use std::", stringify!($SelfT), ";
 808
 809 assert_eq!(5", stringify!($SelfT), ".checked_neg(), Some(-5));
 810 assert_eq!(", stringify!($SelfT), "::MIN.checked_neg(), None);",
 811 $EndFeature, "
 812 ```"),
 813             #[stable(feature = "wrapping", since = "1.7.0")]
 814             #[inline]
 815             pub fn checked_neg(self) -> Option<Self> {
 816                 let (a, b) = self.overflowing_neg();
 817                 if b {None} else {Some(a)}
 818             }
 819         }
 820
 821         doc_comment! {
 822             concat!("Checked shift left. Computes `self << rhs`, returning `None` if `rhs` is larger
 823 than or equal to the number of bits in `self`.
 824
 825 # Examples
 826
 827 Basic usage:
 828
 829 ```
 830 ", $Feature, "assert_eq!(0x1", stringify!($SelfT), ".checked_shl(4), Some(0x10));
 831 assert_eq!(0x1", stringify!($SelfT), ".checked_shl(129), None);",
 832 $EndFeature, "
 833 ```"),
 834             #[stable(feature = "wrapping", since = "1.7.0")]
 835             #[must_use = "this returns the result of the operation, \
 836                           without modifying the original"]
 837             #[inline]
 838             pub fn checked_shl(self, rhs: u32) -> Option<Self> {
 839                 let (a, b) = self.overflowing_shl(rhs);
 840                 if b {None} else {Some(a)}
 841             }
 842         }
 843
 844         doc_comment! {
 845             concat!("Checked shift right. Computes `self >> rhs`, returning `None` if `rhs` is
 846 larger than or equal to the number of bits in `self`.
 847
 848 # Examples
 849
 850 Basic usage:
 851
 852 ```
 853 ", $Feature, "assert_eq!(0x10", stringify!($SelfT), ".checked_shr(4), Some(0x1));
 854 assert_eq!(0x10", stringify!($SelfT), ".checked_shr(128), None);",
 855 $EndFeature, "
 856 ```"),
 857             #[stable(feature = "wrapping", since = "1.7.0")]
 858             #[must_use = "this returns the result of the operation, \
 859                           without modifying the original"]
 860             #[inline]
 861             pub fn checked_shr(self, rhs: u32) -> Option<Self> {
 862                 let (a, b) = self.overflowing_shr(rhs);
 863                 if b {None} else {Some(a)}
 864             }
 865         }
 866
 867         doc_comment! {
 868             concat!("Checked absolute value. Computes `self.abs()`, returning `None` if
 869 `self == MIN`.
 870
 871 # Examples
 872
 873 Basic usage:
 874
 875 ```
 876 ", $Feature, "use std::", stringify!($SelfT), ";
 877
 878 assert_eq!((-5", stringify!($SelfT), ").checked_abs(), Some(5));
 879 assert_eq!(", stringify!($SelfT), "::MIN.checked_abs(), None);",
 880 $EndFeature, "
 881 ```"),
 882             #[stable(feature = "no_panic_abs", since = "1.13.0")]
 883             #[inline]
 884             pub fn checked_abs(self) -> Option<Self> {
 885                 if self.is_negative() {
 886                     self.checked_neg()
 887                 } else {
 888                     Some(self)
 889                 }
 890             }
 891         }
 892
 893         doc_comment! {
 894             concat!("Checked exponentiation. Computes `self.pow(exp)`, returning `None` if
 895 overflow occurred.
 896
 897 # Examples
 898
 899 Basic usage:
 900
 901 ```
 902 ", $Feature, "assert_eq!(8", stringify!($SelfT), ".checked_pow(2), Some(64));
 903 assert_eq!(", stringify!($SelfT), "::max_value().checked_pow(2), None);",
 904 $EndFeature, "
 905 ```"),
 906
 907             #[stable(feature = "no_panic_pow", since = "1.34.0")]
 908             #[must_use = "this returns the result of the operation, \
 909                           without modifying the original"]
 910             #[inline]
 911             pub fn checked_pow(self, mut exp: u32) -> Option<Self> {
 912                 let mut base = self;
 913                 let mut acc: Self = 1;
 914
 915                 while exp > 1 {
 916                     if (exp & 1) == 1 {
 917                         acc = acc.checked_mul(base)?;
 918                     }
 919                     exp /= 2;
 920                     base = base.checked_mul(base)?;
 921                 }
 922
 923                 // Deal with the final bit of the exponent separately, since
 924                 // squaring the base afterwards is not necessary and may cause a
 925                 // needless overflow.
 926                 if exp == 1 {
 927                     acc = acc.checked_mul(base)?;
 928                 }
 929
 930                 Some(acc)
 931             }
 932         }
 933
 934         doc_comment! {
 935             concat!("Saturating integer addition. Computes `self + rhs`, saturating at the numeric
 936 bounds instead of overflowing.
 937
 938 # Examples
 939
 940 Basic usage:
 941
 942 ```
 943 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".saturating_add(1), 101);
 944 assert_eq!(", stringify!($SelfT), "::max_value().saturating_add(100), ", stringify!($SelfT),
 945 "::max_value());",
 946 $EndFeature, "
 947 ```"),
 948
 949             #[stable(feature = "rust1", since = "1.0.0")]
 950             #[rustc_const_unstable(feature = "const_saturating_int_methods")]
 951             #[must_use = "this returns the result of the operation, \
 952                           without modifying the original"]
 953             #[inline]
 954             pub const fn saturating_add(self, rhs: Self) -> Self {
 955                 intrinsics::saturating_add(self, rhs)
 956             }
 957         }
 958
 959
 960         doc_comment! {
 961             concat!("Saturating integer subtraction. Computes `self - rhs`, saturating at the
 962 numeric bounds instead of overflowing.
 963
 964 # Examples
 965
 966 Basic usage:
 967
 968 ```
 969 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".saturating_sub(127), -27);
 970 assert_eq!(", stringify!($SelfT), "::min_value().saturating_sub(100), ", stringify!($SelfT),
 971 "::min_value());",
 972 $EndFeature, "
 973 ```"),
 974             #[stable(feature = "rust1", since = "1.0.0")]
 975             #[rustc_const_unstable(feature = "const_saturating_int_methods")]
 976             #[must_use = "this returns the result of the operation, \
 977                           without modifying the original"]
 978             #[inline]
 979             pub const fn saturating_sub(self, rhs: Self) -> Self {
 980                 intrinsics::saturating_sub(self, rhs)
 981             }
 982         }
 983
 984         doc_comment! {
 985             concat!("Saturating integer negation. Computes `-self`, returning `MAX` if `self == MIN`
 986 instead of overflowing.
 987
 988 # Examples
 989
 990 Basic usage:
 991
 992 ```
 993 ", $Feature, "#![feature(saturating_neg)]
 994 assert_eq!(100", stringify!($SelfT), ".saturating_neg(), -100);
 995 assert_eq!((-100", stringify!($SelfT), ").saturating_neg(), 100);
 996 assert_eq!(", stringify!($SelfT), "::min_value().saturating_neg(), ", stringify!($SelfT),
 997 "::max_value());
 998 assert_eq!(", stringify!($SelfT), "::max_value().saturating_neg(), ", stringify!($SelfT),
 999 "::min_value() + 1);",
1000 $EndFeature, "
1001 ```"),
1002
1003             #[unstable(feature = "saturating_neg", issue = "59983")]
1004             #[inline]
1005             pub fn saturating_neg(self) -> Self {
1006                 intrinsics::saturating_sub(0, self)
1007             }
1008         }
1009
1010         doc_comment! {
1011             concat!("Saturating absolute value. Computes `self.abs()`, returning `MAX` if `self ==
1012 MIN` instead of overflowing.
1013
1014 # Examples
1015
1016 Basic usage:
1017
1018 ```
1019 ", $Feature, "#![feature(saturating_neg)]
1020 assert_eq!(100", stringify!($SelfT), ".saturating_abs(), 100);
1021 assert_eq!((-100", stringify!($SelfT), ").saturating_abs(), 100);
1022 assert_eq!(", stringify!($SelfT), "::min_value().saturating_abs(), ", stringify!($SelfT),
1023 "::max_value());
1024 assert_eq!((", stringify!($SelfT), "::min_value() + 1).saturating_abs(), ", stringify!($SelfT),
1025 "::max_value());",
1026 $EndFeature, "
1027 ```"),
1028
1029             #[unstable(feature = "saturating_neg", issue = "59983")]
1030             #[inline]
1031             pub fn saturating_abs(self) -> Self {
1032                 if self.is_negative() {
1033                     self.saturating_neg()
1034                 } else {
1035                     self
1036                 }
1037             }
1038         }
1039
1040         doc_comment! {
1041             concat!("Saturating integer multiplication. Computes `self * rhs`, saturating at the
1042 numeric bounds instead of overflowing.
1043
1044 # Examples
1045
1046 Basic usage:
1047
1048 ```
1049 ", $Feature, "use std::", stringify!($SelfT), ";
1050
1051 assert_eq!(10", stringify!($SelfT), ".saturating_mul(12), 120);
1052 assert_eq!(", stringify!($SelfT), "::MAX.saturating_mul(10), ", stringify!($SelfT), "::MAX);
1053 assert_eq!(", stringify!($SelfT), "::MIN.saturating_mul(10), ", stringify!($SelfT), "::MIN);",
1054 $EndFeature, "
1055 ```"),
1056             #[stable(feature = "wrapping", since = "1.7.0")]
1057             #[must_use = "this returns the result of the operation, \
1058                           without modifying the original"]
1059             #[inline]
1060             pub fn saturating_mul(self, rhs: Self) -> Self {
1061                 self.checked_mul(rhs).unwrap_or_else(|| {
1062                     if (self < 0 && rhs < 0) || (self > 0 && rhs > 0) {
1063                         Self::max_value()
1064                     } else {
1065                         Self::min_value()
1066                     }
1067                 })
1068             }
1069         }
1070
1071         doc_comment! {
1072             concat!("Saturating integer exponentiation. Computes `self.pow(exp)`,
1073 saturating at the numeric bounds instead of overflowing.
1074
1075 # Examples
1076
1077 Basic usage:
1078
1079 ```
1080 ", $Feature, "use std::", stringify!($SelfT), ";
1081
1082 assert_eq!((-4", stringify!($SelfT), ").saturating_pow(3), -64);
1083 assert_eq!(", stringify!($SelfT), "::MIN.saturating_pow(2), ", stringify!($SelfT), "::MAX);
1084 assert_eq!(", stringify!($SelfT), "::MIN.saturating_pow(3), ", stringify!($SelfT), "::MIN);",
1085 $EndFeature, "
1086 ```"),
1087             #[stable(feature = "no_panic_pow", since = "1.34.0")]
1088             #[must_use = "this returns the result of the operation, \
1089                           without modifying the original"]
1090             #[inline]
1091             pub fn saturating_pow(self, exp: u32) -> Self {
1092                 match self.checked_pow(exp) {
1093                     Some(x) => x,
1094                     None if self < 0 && exp % 2 == 1 => Self::min_value(),
1095                     None => Self::max_value(),
1096                 }
1097             }
1098         }
1099
1100         doc_comment! {
1101             concat!("Wrapping (modular) addition. Computes `self + rhs`, wrapping around at the
1102 boundary of the type.
1103
1104 # Examples
1105
1106 Basic usage:
1107
1108 ```
1109 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".wrapping_add(27), 127);
1110 assert_eq!(", stringify!($SelfT), "::max_value().wrapping_add(2), ", stringify!($SelfT),
1111 "::min_value() + 1);",
1112 $EndFeature, "
1113 ```"),
1114             #[stable(feature = "rust1", since = "1.0.0")]
1115             #[must_use = "this returns the result of the operation, \
1116                           without modifying the original"]
1117             #[inline]
1118             pub const fn wrapping_add(self, rhs: Self) -> Self {
1119                 intrinsics::overflowing_add(self, rhs)
1120             }
1121         }
1122
1123         doc_comment! {
1124             concat!("Wrapping (modular) subtraction. Computes `self - rhs`, wrapping around at the
1125 boundary of the type.
1126
1127 # Examples
1128
1129 Basic usage:
1130
1131 ```
1132 ", $Feature, "assert_eq!(0", stringify!($SelfT), ".wrapping_sub(127), -127);
1133 assert_eq!((-2", stringify!($SelfT), ").wrapping_sub(", stringify!($SelfT), "::max_value()), ",
1134 stringify!($SelfT), "::max_value());",
1135 $EndFeature, "
1136 ```"),
1137             #[stable(feature = "rust1", since = "1.0.0")]
1138             #[must_use = "this returns the result of the operation, \
1139                           without modifying the original"]
1140             #[inline]
1141             pub const fn wrapping_sub(self, rhs: Self) -> Self {
1142                 intrinsics::overflowing_sub(self, rhs)
1143             }
1144         }
1145
1146         doc_comment! {
1147             concat!("Wrapping (modular) multiplication. Computes `self * rhs`, wrapping around at
1148 the boundary of the type.
1149
1150 # Examples
1151
1152 Basic usage:
1153
1154 ```
1155 ", $Feature, "assert_eq!(10", stringify!($SelfT), ".wrapping_mul(12), 120);
1156 assert_eq!(11i8.wrapping_mul(12), -124);",
1157 $EndFeature, "
1158 ```"),
1159             #[stable(feature = "rust1", since = "1.0.0")]
1160             #[must_use = "this returns the result of the operation, \
1161                           without modifying the original"]
1162             #[inline]
1163             pub const fn wrapping_mul(self, rhs: Self) -> Self {
1164                 intrinsics::overflowing_mul(self, rhs)
1165             }
1166         }
1167
1168         doc_comment! {
1169             concat!("Wrapping (modular) division. Computes `self / rhs`, wrapping around at the
1170 boundary of the type.
1171
1172 The only case where such wrapping can occur is when one divides `MIN / -1` on a signed type (where
1173 `MIN` is the negative minimal value for the type); this is equivalent to `-MIN`, a positive value
1174 that is too large to represent in the type. In such a case, this function returns `MIN` itself.
1175
1176 # Panics
1177
1178 This function will panic if `rhs` is 0.
1179
1180 # Examples
1181
1182 Basic usage:
1183
1184 ```
1185 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".wrapping_div(10), 10);
1186 assert_eq!((-128i8).wrapping_div(-1), -128);",
1187 $EndFeature, "
1188 ```"),
1189             #[stable(feature = "num_wrapping", since = "1.2.0")]
1190             #[must_use = "this returns the result of the operation, \
1191                           without modifying the original"]
1192             #[inline]
1193             pub fn wrapping_div(self, rhs: Self) -> Self {
1194                 self.overflowing_div(rhs).0
1195             }
1196         }
1197
1198         doc_comment! {
1199             concat!("Wrapping Euclidean division. Computes `self.div_euclid(rhs)`,
1200 wrapping around at the boundary of the type.
1201
1202 Wrapping will only occur in `MIN / -1` on a signed type (where `MIN` is the negative minimal value
1203 for the type). This is equivalent to `-MIN`, a positive value that is too large to represent in the
1204 type. In this case, this method returns `MIN` itself.
1205
1206 # Panics
1207
1208 This function will panic if `rhs` is 0.
1209
1210 # Examples
1211
1212 Basic usage:
1213
1214 ```
1215 #![feature(euclidean_division)]
1216 assert_eq!(100", stringify!($SelfT), ".wrapping_div_euclid(10), 10);
1217 assert_eq!((-128i8).wrapping_div_euclid(-1), -128);
1218 ```"),
1219             #[unstable(feature = "euclidean_division", issue = "49048")]
1220             #[must_use = "this returns the result of the operation, \
1221                           without modifying the original"]
1222             #[inline]
1223             pub fn wrapping_div_euclid(self, rhs: Self) -> Self {
1224                 self.overflowing_div_euclid(rhs).0
1225             }
1226         }
1227
1228         doc_comment! {
1229             concat!("Wrapping (modular) remainder. Computes `self % rhs`, wrapping around at the
1230 boundary of the type.
1231
1232 Such wrap-around never actually occurs mathematically; implementation artifacts make `x % y`
1233 invalid for `MIN / -1` on a signed type (where `MIN` is the negative minimal value). In such a case,
1234 this function returns `0`.
1235
1236 # Panics
1237
1238 This function will panic if `rhs` is 0.
1239
1240 # Examples
1241
1242 Basic usage:
1243
1244 ```
1245 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".wrapping_rem(10), 0);
1246 assert_eq!((-128i8).wrapping_rem(-1), 0);",
1247 $EndFeature, "
1248 ```"),
1249             #[stable(feature = "num_wrapping", since = "1.2.0")]
1250             #[must_use = "this returns the result of the operation, \
1251                           without modifying the original"]
1252             #[inline]
1253             pub fn wrapping_rem(self, rhs: Self) -> Self {
1254                 self.overflowing_rem(rhs).0
1255             }
1256         }
1257
1258         doc_comment! {
1259             concat!("Wrapping Euclidean remainder. Computes `self.rem_euclid(rhs)`, wrapping around
1260 at the boundary of the type.
1261
1262 Wrapping will only occur in `MIN % -1` on a signed type (where `MIN` is the negative minimal value
1263 for the type). In this case, this method returns 0.
1264
1265 # Panics
1266
1267 This function will panic if `rhs` is 0.
1268
1269 # Examples
1270
1271 Basic usage:
1272
1273 ```
1274 #![feature(euclidean_division)]
1275 assert_eq!(100", stringify!($SelfT), ".wrapping_rem_euclid(10), 0);
1276 assert_eq!((-128i8).wrapping_rem_euclid(-1), 0);
1277 ```"),
1278             #[unstable(feature = "euclidean_division", issue = "49048")]
1279             #[must_use = "this returns the result of the operation, \
1280                           without modifying the original"]
1281             #[inline]
1282             pub fn wrapping_rem_euclid(self, rhs: Self) -> Self {
1283                 self.overflowing_rem_euclid(rhs).0
1284             }
1285         }
1286
1287         doc_comment! {
1288             concat!("Wrapping (modular) negation. Computes `-self`, wrapping around at the boundary
1289 of the type.
1290
1291 The only case where such wrapping can occur is when one negates `MIN` on a signed type (where `MIN`
1292 is the negative minimal value for the type); this is a positive value that is too large to represent
1293 in the type. In such a case, this function returns `MIN` itself.
1294
1295 # Examples
1296
1297 Basic usage:
1298
1299 ```
1300 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".wrapping_neg(), -100);
1301 assert_eq!(", stringify!($SelfT), "::min_value().wrapping_neg(), ", stringify!($SelfT),
1302 "::min_value());",
1303 $EndFeature, "
1304 ```"),
1305             #[stable(feature = "num_wrapping", since = "1.2.0")]
1306             #[inline]
1307             pub const fn wrapping_neg(self) -> Self {
1308                 self.overflowing_neg().0
1309             }
1310         }
1311
1312         doc_comment! {
1313             concat!("Panic-free bitwise shift-left; yields `self << mask(rhs)`, where `mask` removes
1314 any high-order bits of `rhs` that would cause the shift to exceed the bitwidth of the type.
1315
1316 Note that this is *not* the same as a rotate-left; the RHS of a wrapping shift-left is restricted to
1317 the range of the type, rather than the bits shifted out of the LHS being returned to the other end.
1318 The primitive integer types all implement a `rotate_left` function, which may be what you want
1319 instead.
1320
1321 # Examples
1322
1323 Basic usage:
1324
1325 ```
1326 ", $Feature, "assert_eq!((-1", stringify!($SelfT), ").wrapping_shl(7), -128);
1327 assert_eq!((-1", stringify!($SelfT), ").wrapping_shl(128), -1);",
1328 $EndFeature, "
1329 ```"),
1330             #[stable(feature = "num_wrapping", since = "1.2.0")]
1331             #[must_use = "this returns the result of the operation, \
1332                           without modifying the original"]
1333             #[inline]
1334             pub const fn wrapping_shl(self, rhs: u32) -> Self {
1335                 unsafe {
1336                     intrinsics::unchecked_shl(self, (rhs & ($BITS - 1)) as $SelfT)
1337                 }
1338             }
1339         }
1340
1341         doc_comment! {
1342             concat!("Panic-free bitwise shift-right; yields `self >> mask(rhs)`, where `mask`
1343 removes any high-order bits of `rhs` that would cause the shift to exceed the bitwidth of the type.
1344
1345 Note that this is *not* the same as a rotate-right; the RHS of a wrapping shift-right is restricted
1346 to the range of the type, rather than the bits shifted out of the LHS being returned to the other
1347 end. The primitive integer types all implement a `rotate_right` function, which may be what you want
1348 instead.
1349
1350 # Examples
1351
1352 Basic usage:
1353
1354 ```
1355 ", $Feature, "assert_eq!((-128", stringify!($SelfT), ").wrapping_shr(7), -1);
1356 assert_eq!((-128i16).wrapping_shr(64), -128);",
1357 $EndFeature, "
1358 ```"),
1359             #[stable(feature = "num_wrapping", since = "1.2.0")]
1360             #[must_use = "this returns the result of the operation, \
1361                           without modifying the original"]
1362             #[inline]
1363             pub const fn wrapping_shr(self, rhs: u32) -> Self {
1364                 unsafe {
1365                     intrinsics::unchecked_shr(self, (rhs & ($BITS - 1)) as $SelfT)
1366                 }
1367             }
1368         }
1369
1370         doc_comment! {
1371             concat!("Wrapping (modular) absolute value. Computes `self.abs()`, wrapping around at
1372 the boundary of the type.
1373
1374 The only case where such wrapping can occur is when one takes the absolute value of the negative
1375 minimal value for the type this is a positive value that is too large to represent in the type. In
1376 such a case, this function returns `MIN` itself.
1377
1378 # Examples
1379
1380 Basic usage:
1381
1382 ```
1383 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".wrapping_abs(), 100);
1384 assert_eq!((-100", stringify!($SelfT), ").wrapping_abs(), 100);
1385 assert_eq!(", stringify!($SelfT), "::min_value().wrapping_abs(), ", stringify!($SelfT),
1386 "::min_value());
1387 assert_eq!((-128i8).wrapping_abs() as u8, 128);",
1388 $EndFeature, "
1389 ```"),
1390             #[stable(feature = "no_panic_abs", since = "1.13.0")]
1391             #[inline]
1392             pub fn wrapping_abs(self) -> Self {
1393                 if self.is_negative() {
1394                     self.wrapping_neg()
1395                 } else {
1396                     self
1397                 }
1398             }
1399         }
1400
1401         doc_comment! {
1402             concat!("Wrapping (modular) exponentiation. Computes `self.pow(exp)`,
1403 wrapping around at the boundary of the type.
1404
1405 # Examples
1406
1407 Basic usage:
1408
1409 ```
1410 ", $Feature, "assert_eq!(3", stringify!($SelfT), ".wrapping_pow(4), 81);
1411 assert_eq!(3i8.wrapping_pow(5), -13);
1412 assert_eq!(3i8.wrapping_pow(6), -39);",
1413 $EndFeature, "
1414 ```"),
1415             #[stable(feature = "no_panic_pow", since = "1.34.0")]
1416             #[must_use = "this returns the result of the operation, \
1417                           without modifying the original"]
1418             #[inline]
1419             pub fn wrapping_pow(self, mut exp: u32) -> Self {
1420                 let mut base = self;
1421                 let mut acc: Self = 1;
1422
1423                 while exp > 1 {
1424                     if (exp & 1) == 1 {
1425                         acc = acc.wrapping_mul(base);
1426                     }
1427                     exp /= 2;
1428                     base = base.wrapping_mul(base);
1429                 }
1430
1431                 // Deal with the final bit of the exponent separately, since
1432                 // squaring the base afterwards is not necessary and may cause a
1433                 // needless overflow.
1434                 if exp == 1 {
1435                     acc = acc.wrapping_mul(base);
1436                 }
1437
1438                 acc
1439             }
1440         }
1441
1442         doc_comment! {
1443             concat!("Calculates `self` + `rhs`
1444
1445 Returns a tuple of the addition along with a boolean indicating whether an arithmetic overflow would
1446 occur. If an overflow would have occurred then the wrapped value is returned.
1447
1448 # Examples
1449
1450 Basic usage:
1451
1452 ```
1453 ", $Feature, "use std::", stringify!($SelfT), ";
1454
1455 assert_eq!(5", stringify!($SelfT), ".overflowing_add(2), (7, false));
1456 assert_eq!(", stringify!($SelfT), "::MAX.overflowing_add(1), (", stringify!($SelfT),
1457 "::MIN, true));", $EndFeature, "
1458 ```"),
1459             #[stable(feature = "wrapping", since = "1.7.0")]
1460             #[must_use = "this returns the result of the operation, \
1461                           without modifying the original"]
1462             #[inline]
1463             pub const fn overflowing_add(self, rhs: Self) -> (Self, bool) {
1464                 let (a, b) = intrinsics::add_with_overflow(self as $ActualT, rhs as $ActualT);
1465                 (a as Self, b)
1466             }
1467         }
1468
1469         doc_comment! {
1470             concat!("Calculates `self` - `rhs`
1471
1472 Returns a tuple of the subtraction along with a boolean indicating whether an arithmetic overflow
1473 would occur. If an overflow would have occurred then the wrapped value is returned.
1474
1475 # Examples
1476
1477 Basic usage:
1478
1479 ```
1480 ", $Feature, "use std::", stringify!($SelfT), ";
1481
1482 assert_eq!(5", stringify!($SelfT), ".overflowing_sub(2), (3, false));
1483 assert_eq!(", stringify!($SelfT), "::MIN.overflowing_sub(1), (", stringify!($SelfT),
1484 "::MAX, true));", $EndFeature, "
1485 ```"),
1486             #[stable(feature = "wrapping", since = "1.7.0")]
1487             #[must_use = "this returns the result of the operation, \
1488                           without modifying the original"]
1489             #[inline]
1490             pub const fn overflowing_sub(self, rhs: Self) -> (Self, bool) {
1491                 let (a, b) = intrinsics::sub_with_overflow(self as $ActualT, rhs as $ActualT);
1492                 (a as Self, b)
1493             }
1494         }
1495
1496         doc_comment! {
1497             concat!("Calculates the multiplication of `self` and `rhs`.
1498
1499 Returns a tuple of the multiplication along with a boolean indicating whether an arithmetic overflow
1500 would occur. If an overflow would have occurred then the wrapped value is returned.
1501
1502 # Examples
1503
1504 Basic usage:
1505
1506 ```
1507 ", $Feature, "assert_eq!(5", stringify!($SelfT), ".overflowing_mul(2), (10, false));
1508 assert_eq!(1_000_000_000i32.overflowing_mul(10), (1410065408, true));",
1509 $EndFeature, "
1510 ```"),
1511             #[stable(feature = "wrapping", since = "1.7.0")]
1512             #[must_use = "this returns the result of the operation, \
1513                           without modifying the original"]
1514             #[inline]
1515             pub const fn overflowing_mul(self, rhs: Self) -> (Self, bool) {
1516                 let (a, b) = intrinsics::mul_with_overflow(self as $ActualT, rhs as $ActualT);
1517                 (a as Self, b)
1518             }
1519         }
1520
1521         doc_comment! {
1522             concat!("Calculates the divisor when `self` is divided by `rhs`.
1523
1524 Returns a tuple of the divisor along with a boolean indicating whether an arithmetic overflow would
1525 occur. If an overflow would occur then self is returned.
1526
1527 # Panics
1528
1529 This function will panic if `rhs` is 0.
1530
1531 # Examples
1532
1533 Basic usage:
1534
1535 ```
1536 ", $Feature, "use std::", stringify!($SelfT), ";
1537
1538 assert_eq!(5", stringify!($SelfT), ".overflowing_div(2), (2, false));
1539 assert_eq!(", stringify!($SelfT), "::MIN.overflowing_div(-1), (", stringify!($SelfT),
1540 "::MIN, true));",
1541 $EndFeature, "
1542 ```"),
1543             #[inline]
1544             #[stable(feature = "wrapping", since = "1.7.0")]
1545             #[must_use = "this returns the result of the operation, \
1546                           without modifying the original"]
1547             pub fn overflowing_div(self, rhs: Self) -> (Self, bool) {
1548                 if self == Self::min_value() && rhs == -1 {
1549                     (self, true)
1550                 } else {
1551                     (self / rhs, false)
1552                 }
1553             }
1554         }
1555
1556         doc_comment! {
1557             concat!("Calculates the quotient of Euclidean division `self.div_euclid(rhs)`.
1558
1559 Returns a tuple of the divisor along with a boolean indicating whether an arithmetic overflow would
1560 occur. If an overflow would occur then `self` is returned.
1561
1562 # Panics
1563
1564 This function will panic if `rhs` is 0.
1565
1566 # Examples
1567
1568 Basic usage:
1569
1570 ```
1571 #![feature(euclidean_division)]
1572 use std::", stringify!($SelfT), ";
1573
1574 assert_eq!(5", stringify!($SelfT), ".overflowing_div_euclid(2), (2, false));
1575 assert_eq!(", stringify!($SelfT), "::MIN.overflowing_div_euclid(-1), (", stringify!($SelfT),
1576 "::MIN, true));
1577 ```"),
1578             #[inline]
1579             #[unstable(feature = "euclidean_division", issue = "49048")]
1580             #[must_use = "this returns the result of the operation, \
1581                           without modifying the original"]
1582             pub fn overflowing_div_euclid(self, rhs: Self) -> (Self, bool) {
1583                 if self == Self::min_value() && rhs == -1 {
1584                     (self, true)
1585                 } else {
1586                     (self.div_euclid(rhs), false)
1587                 }
1588             }
1589         }
1590
1591         doc_comment! {
1592             concat!("Calculates the remainder when `self` is divided by `rhs`.
1593
1594 Returns a tuple of the remainder after dividing along with a boolean indicating whether an
1595 arithmetic overflow would occur. If an overflow would occur then 0 is returned.
1596
1597 # Panics
1598
1599 This function will panic if `rhs` is 0.
1600
1601 # Examples
1602
1603 Basic usage:
1604
1605 ```
1606 ", $Feature, "use std::", stringify!($SelfT), ";
1607
1608 assert_eq!(5", stringify!($SelfT), ".overflowing_rem(2), (1, false));
1609 assert_eq!(", stringify!($SelfT), "::MIN.overflowing_rem(-1), (0, true));",
1610 $EndFeature, "
1611 ```"),
1612             #[inline]
1613             #[stable(feature = "wrapping", since = "1.7.0")]
1614             #[must_use = "this returns the result of the operation, \
1615                           without modifying the original"]
1616             pub fn overflowing_rem(self, rhs: Self) -> (Self, bool) {
1617                 if self == Self::min_value() && rhs == -1 {
1618                     (0, true)
1619                 } else {
1620                     (self % rhs, false)
1621                 }
1622             }
1623         }
1624
1625
1626         doc_comment! {
1627             concat!("Overflowing Euclidean remainder. Calculates `self.rem_euclid(rhs)`.
1628
1629 Returns a tuple of the remainder after dividing along with a boolean indicating whether an
1630 arithmetic overflow would occur. If an overflow would occur then 0 is returned.
1631
1632 # Panics
1633
1634 This function will panic if `rhs` is 0.
1635
1636 # Examples
1637
1638 Basic usage:
1639
1640 ```
1641 #![feature(euclidean_division)]
1642 use std::", stringify!($SelfT), ";
1643
1644 assert_eq!(5", stringify!($SelfT), ".overflowing_rem_euclid(2), (1, false));
1645 assert_eq!(", stringify!($SelfT), "::MIN.overflowing_rem_euclid(-1), (0, true));
1646 ```"),
1647             #[unstable(feature = "euclidean_division", issue = "49048")]
1648             #[must_use = "this returns the result of the operation, \
1649                           without modifying the original"]
1650             #[inline]
1651             pub fn overflowing_rem_euclid(self, rhs: Self) -> (Self, bool) {
1652                 if self == Self::min_value() && rhs == -1 {
1653                     (0, true)
1654                 } else {
1655                     (self.rem_euclid(rhs), false)
1656                 }
1657             }
1658         }
1659
1660
1661         doc_comment! {
1662             concat!("Negates self, overflowing if this is equal to the minimum value.
1663
1664 Returns a tuple of the negated version of self along with a boolean indicating whether an overflow
1665 happened. If `self` is the minimum value (e.g., `i32::MIN` for values of type `i32`), then the
1666 minimum value will be returned again and `true` will be returned for an overflow happening.
1667
1668 # Examples
1669
1670 Basic usage:
1671
1672 ```
1673 ", $Feature, "use std::", stringify!($SelfT), ";
1674
1675 assert_eq!(2", stringify!($SelfT), ".overflowing_neg(), (-2, false));
1676 assert_eq!(", stringify!($SelfT), "::MIN.overflowing_neg(), (", stringify!($SelfT),
1677 "::MIN, true));", $EndFeature, "
1678 ```"),
1679             #[inline]
1680             #[stable(feature = "wrapping", since = "1.7.0")]
1681             pub const fn overflowing_neg(self) -> (Self, bool) {
1682                 ((!self).wrapping_add(1), self == Self::min_value())
1683             }
1684         }
1685
1686         doc_comment! {
1687             concat!("Shifts self left by `rhs` bits.
1688
1689 Returns a tuple of the shifted version of self along with a boolean indicating whether the shift
1690 value was larger than or equal to the number of bits. If the shift value is too large, then value is
1691 masked (N-1) where N is the number of bits, and this value is then used to perform the shift.
1692
1693 # Examples
1694
1695 Basic usage:
1696
1697 ```
1698 ", $Feature, "assert_eq!(0x1", stringify!($SelfT),".overflowing_shl(4), (0x10, false));
1699 assert_eq!(0x1i32.overflowing_shl(36), (0x10, true));",
1700 $EndFeature, "
1701 ```"),
1702             #[stable(feature = "wrapping", since = "1.7.0")]
1703             #[must_use = "this returns the result of the operation, \
1704                           without modifying the original"]
1705             #[inline]
1706             pub const fn overflowing_shl(self, rhs: u32) -> (Self, bool) {
1707                 (self.wrapping_shl(rhs), (rhs > ($BITS - 1)))
1708             }
1709         }
1710
1711         doc_comment! {
1712             concat!("Shifts self right by `rhs` bits.
1713
1714 Returns a tuple of the shifted version of self along with a boolean indicating whether the shift
1715 value was larger than or equal to the number of bits. If the shift value is too large, then value is
1716 masked (N-1) where N is the number of bits, and this value is then used to perform the shift.
1717
1718 # Examples
1719
1720 Basic usage:
1721
1722 ```
1723 ", $Feature, "assert_eq!(0x10", stringify!($SelfT), ".overflowing_shr(4), (0x1, false));
1724 assert_eq!(0x10i32.overflowing_shr(36), (0x1, true));",
1725 $EndFeature, "
1726 ```"),
1727             #[stable(feature = "wrapping", since = "1.7.0")]
1728             #[must_use = "this returns the result of the operation, \
1729                           without modifying the original"]
1730             #[inline]
1731             pub const fn overflowing_shr(self, rhs: u32) -> (Self, bool) {
1732                 (self.wrapping_shr(rhs), (rhs > ($BITS - 1)))
1733             }
1734         }
1735
1736         doc_comment! {
1737             concat!("Computes the absolute value of `self`.
1738
1739 Returns a tuple of the absolute version of self along with a boolean indicating whether an overflow
1740 happened. If self is the minimum value (e.g., ", stringify!($SelfT), "::MIN for values of type
1741  ", stringify!($SelfT), "), then the minimum value will be returned again and true will be returned
1742 for an overflow happening.
1743
1744 # Examples
1745
1746 Basic usage:
1747
1748 ```
1749 ", $Feature, "assert_eq!(10", stringify!($SelfT), ".overflowing_abs(), (10, false));
1750 assert_eq!((-10", stringify!($SelfT), ").overflowing_abs(), (10, false));
1751 assert_eq!((", stringify!($SelfT), "::min_value()).overflowing_abs(), (", stringify!($SelfT),
1752 "::min_value(), true));",
1753 $EndFeature, "
1754 ```"),
1755             #[stable(feature = "no_panic_abs", since = "1.13.0")]
1756             #[inline]
1757             pub fn overflowing_abs(self) -> (Self, bool) {
1758                 if self.is_negative() {
1759                     self.overflowing_neg()
1760                 } else {
1761                     (self, false)
1762                 }
1763             }
1764         }
1765
1766         doc_comment! {
1767             concat!("Raises self to the power of `exp`, using exponentiation by squaring.
1768
1769 Returns a tuple of the exponentiation along with a bool indicating
1770 whether an overflow happened.
1771
1772 # Examples
1773
1774 Basic usage:
1775
1776 ```
1777 ", $Feature, "assert_eq!(3", stringify!($SelfT), ".overflowing_pow(4), (81, false));
1778 assert_eq!(3i8.overflowing_pow(5), (-13, true));",
1779 $EndFeature, "
1780 ```"),
1781             #[stable(feature = "no_panic_pow", since = "1.34.0")]
1782             #[must_use = "this returns the result of the operation, \
1783                           without modifying the original"]
1784             #[inline]
1785             pub fn overflowing_pow(self, mut exp: u32) -> (Self, bool) {
1786                 let mut base = self;
1787                 let mut acc: Self = 1;
1788                 let mut overflown = false;
1789                 // Scratch space for storing results of overflowing_mul.
1790                 let mut r;
1791
1792                 while exp > 1 {
1793                     if (exp & 1) == 1 {
1794                         r = acc.overflowing_mul(base);
1795                         acc = r.0;
1796                         overflown |= r.1;
1797                     }
1798                     exp /= 2;
1799                     r = base.overflowing_mul(base);
1800                     base = r.0;
1801                     overflown |= r.1;
1802                 }
1803
1804                 // Deal with the final bit of the exponent separately, since
1805                 // squaring the base afterwards is not necessary and may cause a
1806                 // needless overflow.
1807                 if exp == 1 {
1808                     r = acc.overflowing_mul(base);
1809                     acc = r.0;
1810                     overflown |= r.1;
1811                 }
1812
1813                 (acc, overflown)
1814             }
1815         }
1816
1817         doc_comment! {
1818             concat!("Raises self to the power of `exp`, using exponentiation by squaring.
1819
1820 # Examples
1821
1822 Basic usage:
1823
1824 ```
1825 ", $Feature, "let x: ", stringify!($SelfT), " = 2; // or any other integer type
1826
1827 assert_eq!(x.pow(5), 32);",
1828 $EndFeature, "
1829 ```"),
1830             #[stable(feature = "rust1", since = "1.0.0")]
1831             #[must_use = "this returns the result of the operation, \
1832                           without modifying the original"]
1833             #[inline]
1834             #[rustc_inherit_overflow_checks]
1835             pub fn pow(self, mut exp: u32) -> Self {
1836                 let mut base = self;
1837                 let mut acc = 1;
1838
1839                 while exp > 1 {
1840                     if (exp & 1) == 1 {
1841                         acc = acc * base;
1842                     }
1843                     exp /= 2;
1844                     base = base * base;
1845                 }
1846
1847                 // Deal with the final bit of the exponent separately, since
1848                 // squaring the base afterwards is not necessary and may cause a
1849                 // needless overflow.
1850                 if exp == 1 {
1851                     acc = acc * base;
1852                 }
1853
1854                 acc
1855             }
1856         }
1857
1858         doc_comment! {
1859             concat!("Calculates the quotient of Euclidean division of `self` by `rhs`.
1860
1861 This computes the integer `n` such that `self = n * rhs + self.rem_euclid(rhs)`,
1862 with `0 <= self.rem_euclid(rhs) < rhs`.
1863
1864 In other words, the result is `self / rhs` rounded to the integer `n`
1865 such that `self >= n * rhs`.
1866 If `self > 0`, this is equal to round towards zero (the default in Rust);
1867 if `self < 0`, this is equal to round towards +/- infinity.
1868
1869 # Panics
1870
1871 This function will panic if `rhs` is 0.
1872
1873 # Examples
1874
1875 Basic usage:
1876
1877 ```
1878 #![feature(euclidean_division)]
1879 let a: ", stringify!($SelfT), " = 7; // or any other integer type
1880 let b = 4;
1881
1882 assert_eq!(a.div_euclid(b), 1); // 7 >= 4 * 1
1883 assert_eq!(a.div_euclid(-b), -1); // 7 >= -4 * -1
1884 assert_eq!((-a).div_euclid(b), -2); // -7 >= 4 * -2
1885 assert_eq!((-a).div_euclid(-b), 2); // -7 >= -4 * 2
1886 ```"),
1887             #[unstable(feature = "euclidean_division", issue = "49048")]
1888             #[must_use = "this returns the result of the operation, \
1889                           without modifying the original"]
1890             #[inline]
1891             #[rustc_inherit_overflow_checks]
1892             pub fn div_euclid(self, rhs: Self) -> Self {
1893                 let q = self / rhs;
1894                 if self % rhs < 0 {
1895                     return if rhs > 0 { q - 1 } else { q + 1 }
1896                 }
1897                 q
1898             }
1899         }
1900
1901
1902         doc_comment! {
1903             concat!("Calculates the least nonnegative remainder of `self (mod rhs)`.
1904
1905 This is done as if by the Euclidean division algorithm -- given
1906 `r = self.rem_euclid(rhs)`, `self = rhs * self.div_euclid(rhs) + r`, and
1907 `0 <= r < abs(rhs)`.
1908
1909 # Panics
1910
1911 This function will panic if `rhs` is 0.
1912
1913 # Examples
1914
1915 Basic usage:
1916
1917 ```
1918 #![feature(euclidean_division)]
1919 let a: ", stringify!($SelfT), " = 7; // or any other integer type
1920 let b = 4;
1921
1922 assert_eq!(a.rem_euclid(b), 3);
1923 assert_eq!((-a).rem_euclid(b), 1);
1924 assert_eq!(a.rem_euclid(-b), 3);
1925 assert_eq!((-a).rem_euclid(-b), 1);
1926 ```"),
1927             #[unstable(feature = "euclidean_division", issue = "49048")]
1928             #[must_use = "this returns the result of the operation, \
1929                           without modifying the original"]
1930             #[inline]
1931             #[rustc_inherit_overflow_checks]
1932             pub fn rem_euclid(self, rhs: Self) -> Self {
1933                 let r = self % rhs;
1934                 if r < 0 {
1935                     if rhs < 0 {
1936                         r - rhs
1937                     } else {
1938                         r + rhs
1939                     }
1940                 } else {
1941                     r
1942                 }
1943             }
1944         }
1945
1946         doc_comment! {
1947             concat!("Computes the absolute value of `self`.
1948
1949 # Overflow behavior
1950
1951 The absolute value of `", stringify!($SelfT), "::min_value()` cannot be represented as an
1952 `", stringify!($SelfT), "`, and attempting to calculate it will cause an overflow. This means that
1953 code in debug mode will trigger a panic on this case and optimized code will return `",
1954 stringify!($SelfT), "::min_value()` without a panic.
1955
1956 # Examples
1957
1958 Basic usage:
1959
1960 ```
1961 ", $Feature, "assert_eq!(10", stringify!($SelfT), ".abs(), 10);
1962 assert_eq!((-10", stringify!($SelfT), ").abs(), 10);",
1963 $EndFeature, "
1964 ```"),
1965             #[stable(feature = "rust1", since = "1.0.0")]
1966             #[inline]
1967             #[rustc_inherit_overflow_checks]
1968             pub fn abs(self) -> Self {
1969                 if self.is_negative() {
1970                     // Note that the #[inline] above means that the overflow
1971                     // semantics of this negation depend on the crate we're being
1972                     // inlined into.
1973                     -self
1974                 } else {
1975                     self
1976                 }
1977             }
1978         }
1979
1980         doc_comment! {
1981             concat!("Returns a number representing sign of `self`.
1982
1983  - `0` if the number is zero
1984  - `1` if the number is positive
1985  - `-1` if the number is negative
1986
1987 # Examples
1988
1989 Basic usage:
1990
1991 ```
1992 ", $Feature, "assert_eq!(10", stringify!($SelfT), ".signum(), 1);
1993 assert_eq!(0", stringify!($SelfT), ".signum(), 0);
1994 assert_eq!((-10", stringify!($SelfT), ").signum(), -1);",
1995 $EndFeature, "
1996 ```"),
1997             #[stable(feature = "rust1", since = "1.0.0")]
1998             #[inline]
1999             pub fn signum(self) -> Self {
2000                 match self {
2001                     n if n > 0 =>  1,
2002                     0          =>  0,
2003                     _          => -1,
2004                 }
2005             }
2006         }
2007
2008         doc_comment! {
2009             concat!("Returns `true` if `self` is positive and `false` if the number is zero or
2010 negative.
2011
2012 # Examples
2013
2014 Basic usage:
2015
2016 ```
2017 ", $Feature, "assert!(10", stringify!($SelfT), ".is_positive());
2018 assert!(!(-10", stringify!($SelfT), ").is_positive());",
2019 $EndFeature, "
2020 ```"),
2021             #[stable(feature = "rust1", since = "1.0.0")]
2022             #[inline]
2023             pub const fn is_positive(self) -> bool { self > 0 }
2024         }
2025
2026         doc_comment! {
2027             concat!("Returns `true` if `self` is negative and `false` if the number is zero or
2028 positive.
2029
2030 # Examples
2031
2032 Basic usage:
2033
2034 ```
2035 ", $Feature, "assert!((-10", stringify!($SelfT), ").is_negative());
2036 assert!(!10", stringify!($SelfT), ".is_negative());",
2037 $EndFeature, "
2038 ```"),
2039             #[stable(feature = "rust1", since = "1.0.0")]
2040             #[inline]
2041             pub const fn is_negative(self) -> bool { self < 0 }
2042         }
2043
2044         doc_comment! {
2045             concat!("Return the memory representation of this integer as a byte array in
2046 big-endian (network) byte order.
2047 ",
2048 $to_xe_bytes_doc,
2049 "
2050 # Examples
2051
2052 ```
2053 let bytes = ", $swap_op, stringify!($SelfT), ".to_be_bytes();
2054 assert_eq!(bytes, ", $be_bytes, ");
2055 ```"),
2056             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2057             #[rustc_const_unstable(feature = "const_int_conversion")]
2058             #[inline]
2059             pub const fn to_be_bytes(self) -> [u8; mem::size_of::<Self>()] {
2060                 self.to_be().to_ne_bytes()
2061             }
2062         }
2063
2064 doc_comment! {
2065             concat!("Return the memory representation of this integer as a byte array in
2066 little-endian byte order.
2067 ",
2068 $to_xe_bytes_doc,
2069 "
2070 # Examples
2071
2072 ```
2073 let bytes = ", $swap_op, stringify!($SelfT), ".to_le_bytes();
2074 assert_eq!(bytes, ", $le_bytes, ");
2075 ```"),
2076             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2077             #[rustc_const_unstable(feature = "const_int_conversion")]
2078             #[inline]
2079             pub const fn to_le_bytes(self) -> [u8; mem::size_of::<Self>()] {
2080                 self.to_le().to_ne_bytes()
2081             }
2082         }
2083
2084         doc_comment! {
2085             concat!("
2086 Return the memory representation of this integer as a byte array in
2087 native byte order.
2088
2089 As the target platform's native endianness is used, portable code
2090 should use [`to_be_bytes`] or [`to_le_bytes`], as appropriate,
2091 instead.
2092 ",
2093 $to_xe_bytes_doc,
2094 "
2095 [`to_be_bytes`]: #method.to_be_bytes
2096 [`to_le_bytes`]: #method.to_le_bytes
2097
2098 # Examples
2099
2100 ```
2101 let bytes = ", $swap_op, stringify!($SelfT), ".to_ne_bytes();
2102 assert_eq!(bytes, if cfg!(target_endian = \"big\") {
2103         ", $be_bytes, "
2104     } else {
2105         ", $le_bytes, "
2106     });
2107 ```"),
2108             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2109             #[rustc_const_unstable(feature = "const_int_conversion")]
2110             #[inline]
2111             pub const fn to_ne_bytes(self) -> [u8; mem::size_of::<Self>()] {
2112                 unsafe { mem::transmute(self) }
2113             }
2114         }
2115
2116 doc_comment! {
2117             concat!("Create an integer value from its representation as a byte array in
2118 big endian.
2119 ",
2120 $from_xe_bytes_doc,
2121 "
2122 # Examples
2123
2124 ```
2125 let value = ", stringify!($SelfT), "::from_be_bytes(", $be_bytes, ");
2126 assert_eq!(value, ", $swap_op, ");
2127 ```
2128
2129 When starting from a slice rather than an array, fallible conversion APIs can be used:
2130
2131 ```
2132 use std::convert::TryInto;
2133
2134 fn read_be_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {
2135     let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());
2136     *input = rest;
2137     ", stringify!($SelfT), "::from_be_bytes(int_bytes.try_into().unwrap())
2138 }
2139 ```"),
2140             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2141             #[rustc_const_unstable(feature = "const_int_conversion")]
2142             #[inline]
2143             pub const fn from_be_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
2144                 Self::from_be(Self::from_ne_bytes(bytes))
2145             }
2146         }
2147
2148 doc_comment! {
2149             concat!("
2150 Create an integer value from its representation as a byte array in
2151 little endian.
2152 ",
2153 $from_xe_bytes_doc,
2154 "
2155 # Examples
2156
2157 ```
2158 let value = ", stringify!($SelfT), "::from_le_bytes(", $le_bytes, ");
2159 assert_eq!(value, ", $swap_op, ");
2160 ```
2161
2162 When starting from a slice rather than an array, fallible conversion APIs can be used:
2163
2164 ```
2165 use std::convert::TryInto;
2166
2167 fn read_le_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {
2168     let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());
2169     *input = rest;
2170     ", stringify!($SelfT), "::from_le_bytes(int_bytes.try_into().unwrap())
2171 }
2172 ```"),
2173             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2174             #[rustc_const_unstable(feature = "const_int_conversion")]
2175             #[inline]
2176             pub const fn from_le_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
2177                 Self::from_le(Self::from_ne_bytes(bytes))
2178             }
2179         }
2180
2181         doc_comment! {
2182             concat!("Create an integer value from its memory representation as a byte
2183 array in native endianness.
2184
2185 As the target platform's native endianness is used, portable code
2186 likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as
2187 appropriate instead.
2188
2189 [`from_be_bytes`]: #method.from_be_bytes
2190 [`from_le_bytes`]: #method.from_le_bytes
2191 ",
2192 $from_xe_bytes_doc,
2193 "
2194 # Examples
2195
2196 ```
2197 let value = ", stringify!($SelfT), "::from_ne_bytes(if cfg!(target_endian = \"big\") {
2198         ", $be_bytes, "
2199     } else {
2200         ", $le_bytes, "
2201     });
2202 assert_eq!(value, ", $swap_op, ");
2203 ```
2204
2205 When starting from a slice rather than an array, fallible conversion APIs can be used:
2206
2207 ```
2208 use std::convert::TryInto;
2209
2210 fn read_ne_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {
2211     let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());
2212     *input = rest;
2213     ", stringify!($SelfT), "::from_ne_bytes(int_bytes.try_into().unwrap())
2214 }
2215 ```"),
2216             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2217             #[rustc_const_unstable(feature = "const_int_conversion")]
2218             #[inline]
2219             pub const fn from_ne_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
2220                 unsafe { mem::transmute(bytes) }
2221             }
2222         }
2223     }
2224 }
2225
2226 #[lang = "i8"]
2227 impl i8 {
2228     int_impl! { i8, i8, u8, 8, -128, 127, "", "", 2, "-0x7e", "0xa", "0x12", "0x12", "0x48",
2229         "[0x12]", "[0x12]", "", "" }
2230 }
2231
2232 #[lang = "i16"]
2233 impl i16 {
2234     int_impl! { i16, i16, u16, 16, -32768, 32767, "", "", 4, "-0x5ffd", "0x3a", "0x1234", "0x3412",
2235         "0x2c48", "[0x34, 0x12]", "[0x12, 0x34]", "", "" }
2236 }
2237
2238 #[lang = "i32"]
2239 impl i32 {
2240     int_impl! { i32, i32, u32, 32, -2147483648, 2147483647, "", "", 8, "0x10000b3", "0xb301",
2241         "0x12345678", "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]",
2242         "[0x12, 0x34, 0x56, 0x78]", "", "" }
2243 }
2244
2245 #[lang = "i64"]
2246 impl i64 {
2247     int_impl! { i64, i64, u64, 64, -9223372036854775808, 9223372036854775807, "", "", 12,
2248          "0xaa00000000006e1", "0x6e10aa", "0x1234567890123456", "0x5634129078563412",
2249          "0x6a2c48091e6a2c48", "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
2250          "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]", "", "" }
2251 }
2252
2253 #[lang = "i128"]
2254 impl i128 {
2255     int_impl! { i128, i128, u128, 128, -170141183460469231731687303715884105728,
2256         170141183460469231731687303715884105727, "", "", 16,
2257         "0x13f40000000000000000000000004f76", "0x4f7613f4", "0x12345678901234567890123456789012",
2258         "0x12907856341290785634129078563412", "0x48091e6a2c48091e6a2c48091e6a2c48",
2259         "[0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, \
2260           0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
2261         "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56, \
2262           0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12]", "", "" }
2263 }
2264
2265 #[cfg(target_pointer_width = "16")]
2266 #[lang = "isize"]
2267 impl isize {
2268     int_impl! { isize, i16, u16, 16, -32768, 32767, "", "", 4, "-0x5ffd", "0x3a", "0x1234",
2269         "0x3412", "0x2c48", "[0x34, 0x12]", "[0x12, 0x34]",
2270         usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
2271 }
2272
2273 #[cfg(target_pointer_width = "32")]
2274 #[lang = "isize"]
2275 impl isize {
2276     int_impl! { isize, i32, u32, 32, -2147483648, 2147483647, "", "", 8, "0x10000b3", "0xb301",
2277         "0x12345678", "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]",
2278         "[0x12, 0x34, 0x56, 0x78]",
2279         usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
2280 }
2281
2282 #[cfg(target_pointer_width = "64")]
2283 #[lang = "isize"]
2284 impl isize {
2285     int_impl! { isize, i64, u64, 64, -9223372036854775808, 9223372036854775807, "", "",
2286         12, "0xaa00000000006e1", "0x6e10aa",  "0x1234567890123456", "0x5634129078563412",
2287          "0x6a2c48091e6a2c48", "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
2288          "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
2289          usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
2290 }
2291
2292 // `Int` + `UnsignedInt` implemented for unsigned integers
2293 macro_rules! uint_impl {
2294     ($SelfT:ty, $ActualT:ty, $BITS:expr, $MaxV:expr, $Feature:expr, $EndFeature:expr,
2295         $rot:expr, $rot_op:expr, $rot_result:expr, $swap_op:expr, $swapped:expr,
2296         $reversed:expr, $le_bytes:expr, $be_bytes:expr,
2297         $to_xe_bytes_doc:expr, $from_xe_bytes_doc:expr) => {
2298         doc_comment! {
2299             concat!("Returns the smallest value that can be represented by this integer type.
2300
2301 # Examples
2302
2303 Basic usage:
2304
2305 ```
2306 ", $Feature, "assert_eq!(", stringify!($SelfT), "::min_value(), 0);", $EndFeature, "
2307 ```"),
2308             #[stable(feature = "rust1", since = "1.0.0")]
2309             #[rustc_promotable]
2310             #[inline]
2311             pub const fn min_value() -> Self { 0 }
2312         }
2313
2314         doc_comment! {
2315             concat!("Returns the largest value that can be represented by this integer type.
2316
2317 # Examples
2318
2319 Basic usage:
2320
2321 ```
2322 ", $Feature, "assert_eq!(", stringify!($SelfT), "::max_value(), ",
2323 stringify!($MaxV), ");", $EndFeature, "
2324 ```"),
2325             #[stable(feature = "rust1", since = "1.0.0")]
2326             #[rustc_promotable]
2327             #[inline]
2328             pub const fn max_value() -> Self { !0 }
2329         }
2330
2331         doc_comment! {
2332             concat!("Converts a string slice in a given base to an integer.
2333
2334 The string is expected to be an optional `+` sign
2335 followed by digits.
2336 Leading and trailing whitespace represent an error.
2337 Digits are a subset of these characters, depending on `radix`:
2338
2339 * `0-9`
2340 * `a-z`
2341 * `A-Z`
2342
2343 # Panics
2344
2345 This function panics if `radix` is not in the range from 2 to 36.
2346
2347 # Examples
2348
2349 Basic usage:
2350
2351 ```
2352 ", $Feature, "assert_eq!(", stringify!($SelfT), "::from_str_radix(\"A\", 16), Ok(10));",
2353 $EndFeature, "
2354 ```"),
2355             #[stable(feature = "rust1", since = "1.0.0")]
2356             pub fn from_str_radix(src: &str, radix: u32) -> Result<Self, ParseIntError> {
2357                 from_str_radix(src, radix)
2358             }
2359         }
2360
2361         doc_comment! {
2362             concat!("Returns the number of ones in the binary representation of `self`.
2363
2364 # Examples
2365
2366 Basic usage:
2367
2368 ```
2369 ", $Feature, "let n = 0b01001100", stringify!($SelfT), ";
2370
2371 assert_eq!(n.count_ones(), 3);", $EndFeature, "
2372 ```"),
2373             #[stable(feature = "rust1", since = "1.0.0")]
2374             #[inline]
2375             pub const fn count_ones(self) -> u32 {
2376                 intrinsics::ctpop(self as $ActualT) as u32
2377             }
2378         }
2379
2380         doc_comment! {
2381             concat!("Returns the number of zeros in the binary representation of `self`.
2382
2383 # Examples
2384
2385 Basic usage:
2386
2387 ```
2388 ", $Feature, "assert_eq!(", stringify!($SelfT), "::max_value().count_zeros(), 0);", $EndFeature, "
2389 ```"),
2390             #[stable(feature = "rust1", since = "1.0.0")]
2391             #[inline]
2392             pub const fn count_zeros(self) -> u32 {
2393                 (!self).count_ones()
2394             }
2395         }
2396
2397         doc_comment! {
2398             concat!("Returns the number of leading zeros in the binary representation of `self`.
2399
2400 # Examples
2401
2402 Basic usage:
2403
2404 ```
2405 ", $Feature, "let n = ", stringify!($SelfT), "::max_value() >> 2;
2406
2407 assert_eq!(n.leading_zeros(), 2);", $EndFeature, "
2408 ```"),
2409             #[stable(feature = "rust1", since = "1.0.0")]
2410             #[inline]
2411             pub const fn leading_zeros(self) -> u32 {
2412                 intrinsics::ctlz(self as $ActualT) as u32
2413             }
2414         }
2415
2416         doc_comment! {
2417             concat!("Returns the number of trailing zeros in the binary representation
2418 of `self`.
2419
2420 # Examples
2421
2422 Basic usage:
2423
2424 ```
2425 ", $Feature, "let n = 0b0101000", stringify!($SelfT), ";
2426
2427 assert_eq!(n.trailing_zeros(), 3);", $EndFeature, "
2428 ```"),
2429             #[stable(feature = "rust1", since = "1.0.0")]
2430             #[inline]
2431             pub const fn trailing_zeros(self) -> u32 {
2432                 intrinsics::cttz(self) as u32
2433             }
2434         }
2435
2436         doc_comment! {
2437             concat!("Shifts the bits to the left by a specified amount, `n`,
2438 wrapping the truncated bits to the end of the resulting integer.
2439
2440 Please note this isn't the same operation as the `<<` shifting operator!
2441
2442 # Examples
2443
2444 Basic usage:
2445
2446 ```
2447 let n = ", $rot_op, stringify!($SelfT), ";
2448 let m = ", $rot_result, ";
2449
2450 assert_eq!(n.rotate_left(", $rot, "), m);
2451 ```"),
2452             #[stable(feature = "rust1", since = "1.0.0")]
2453             #[must_use = "this returns the result of the operation, \
2454                           without modifying the original"]
2455             #[inline]
2456             pub const fn rotate_left(self, n: u32) -> Self {
2457                 intrinsics::rotate_left(self, n as $SelfT)
2458             }
2459         }
2460
2461         doc_comment! {
2462             concat!("Shifts the bits to the right by a specified amount, `n`,
2463 wrapping the truncated bits to the beginning of the resulting
2464 integer.
2465
2466 Please note this isn't the same operation as the `>>` shifting operator!
2467
2468 # Examples
2469
2470 Basic usage:
2471
2472 ```
2473 let n = ", $rot_result, stringify!($SelfT), ";
2474 let m = ", $rot_op, ";
2475
2476 assert_eq!(n.rotate_right(", $rot, "), m);
2477 ```"),
2478             #[stable(feature = "rust1", since = "1.0.0")]
2479             #[must_use = "this returns the result of the operation, \
2480                           without modifying the original"]
2481             #[inline]
2482             pub const fn rotate_right(self, n: u32) -> Self {
2483                 intrinsics::rotate_right(self, n as $SelfT)
2484             }
2485         }
2486
2487         doc_comment! {
2488             concat!("
2489 Reverses the byte order of the integer.
2490
2491 # Examples
2492
2493 Basic usage:
2494
2495 ```
2496 let n = ", $swap_op, stringify!($SelfT), ";
2497 let m = n.swap_bytes();
2498
2499 assert_eq!(m, ", $swapped, ");
2500 ```"),
2501             #[stable(feature = "rust1", since = "1.0.0")]
2502             #[inline]
2503             pub const fn swap_bytes(self) -> Self {
2504                 intrinsics::bswap(self as $ActualT) as Self
2505             }
2506         }
2507
2508         doc_comment! {
2509             concat!("Reverses the bit pattern of the integer.
2510
2511 # Examples
2512
2513 Basic usage:
2514
2515 ```
2516 #![feature(reverse_bits)]
2517
2518 let n = ", $swap_op, stringify!($SelfT), ";
2519 let m = n.reverse_bits();
2520
2521 assert_eq!(m, ", $reversed, ");
2522 ```"),
2523             #[unstable(feature = "reverse_bits", issue = "48763")]
2524             #[inline]
2525             pub const fn reverse_bits(self) -> Self {
2526                 intrinsics::bitreverse(self as $ActualT) as Self
2527             }
2528         }
2529
2530         doc_comment! {
2531             concat!("Converts an integer from big endian to the target's endianness.
2532
2533 On big endian this is a no-op. On little endian the bytes are
2534 swapped.
2535
2536 # Examples
2537
2538 Basic usage:
2539
2540 ```
2541 ", $Feature, "let n = 0x1A", stringify!($SelfT), ";
2542
2543 if cfg!(target_endian = \"big\") {
2544     assert_eq!(", stringify!($SelfT), "::from_be(n), n)
2545 } else {
2546     assert_eq!(", stringify!($SelfT), "::from_be(n), n.swap_bytes())
2547 }", $EndFeature, "
2548 ```"),
2549             #[stable(feature = "rust1", since = "1.0.0")]
2550             #[inline]
2551             pub const fn from_be(x: Self) -> Self {
2552                 #[cfg(target_endian = "big")]
2553                 {
2554                     x
2555                 }
2556                 #[cfg(not(target_endian = "big"))]
2557                 {
2558                     x.swap_bytes()
2559                 }
2560             }
2561         }
2562
2563         doc_comment! {
2564             concat!("Converts an integer from little endian to the target's endianness.
2565
2566 On little endian this is a no-op. On big endian the bytes are
2567 swapped.
2568
2569 # Examples
2570
2571 Basic usage:
2572
2573 ```
2574 ", $Feature, "let n = 0x1A", stringify!($SelfT), ";
2575
2576 if cfg!(target_endian = \"little\") {
2577     assert_eq!(", stringify!($SelfT), "::from_le(n), n)
2578 } else {
2579     assert_eq!(", stringify!($SelfT), "::from_le(n), n.swap_bytes())
2580 }", $EndFeature, "
2581 ```"),
2582             #[stable(feature = "rust1", since = "1.0.0")]
2583             #[inline]
2584             pub const fn from_le(x: Self) -> Self {
2585                 #[cfg(target_endian = "little")]
2586                 {
2587                     x
2588                 }
2589                 #[cfg(not(target_endian = "little"))]
2590                 {
2591                     x.swap_bytes()
2592                 }
2593             }
2594         }
2595
2596         doc_comment! {
2597             concat!("Converts `self` to big endian from the target's endianness.
2598
2599 On big endian this is a no-op. On little endian the bytes are
2600 swapped.
2601
2602 # Examples
2603
2604 Basic usage:
2605
2606 ```
2607 ", $Feature, "let n = 0x1A", stringify!($SelfT), ";
2608
2609 if cfg!(target_endian = \"big\") {
2610     assert_eq!(n.to_be(), n)
2611 } else {
2612     assert_eq!(n.to_be(), n.swap_bytes())
2613 }", $EndFeature, "
2614 ```"),
2615             #[stable(feature = "rust1", since = "1.0.0")]
2616             #[inline]
2617             pub const fn to_be(self) -> Self { // or not to be?
2618                 #[cfg(target_endian = "big")]
2619                 {
2620                     self
2621                 }
2622                 #[cfg(not(target_endian = "big"))]
2623                 {
2624                     self.swap_bytes()
2625                 }
2626             }
2627         }
2628
2629         doc_comment! {
2630             concat!("Converts `self` to little endian from the target's endianness.
2631
2632 On little endian this is a no-op. On big endian the bytes are
2633 swapped.
2634
2635 # Examples
2636
2637 Basic usage:
2638
2639 ```
2640 ", $Feature, "let n = 0x1A", stringify!($SelfT), ";
2641
2642 if cfg!(target_endian = \"little\") {
2643     assert_eq!(n.to_le(), n)
2644 } else {
2645     assert_eq!(n.to_le(), n.swap_bytes())
2646 }", $EndFeature, "
2647 ```"),
2648             #[stable(feature = "rust1", since = "1.0.0")]
2649             #[inline]
2650             pub const fn to_le(self) -> Self {
2651                 #[cfg(target_endian = "little")]
2652                 {
2653                     self
2654                 }
2655                 #[cfg(not(target_endian = "little"))]
2656                 {
2657                     self.swap_bytes()
2658                 }
2659             }
2660         }
2661
2662         doc_comment! {
2663             concat!("Checked integer addition. Computes `self + rhs`, returning `None`
2664 if overflow occurred.
2665
2666 # Examples
2667
2668 Basic usage:
2669
2670 ```
2671 ", $Feature, "assert_eq!((", stringify!($SelfT), "::max_value() - 2).checked_add(1), ",
2672 "Some(", stringify!($SelfT), "::max_value() - 1));
2673 assert_eq!((", stringify!($SelfT), "::max_value() - 2).checked_add(3), None);", $EndFeature, "
2674 ```"),
2675             #[stable(feature = "rust1", since = "1.0.0")]
2676             #[must_use = "this returns the result of the operation, \
2677                           without modifying the original"]
2678             #[inline]
2679             pub fn checked_add(self, rhs: Self) -> Option<Self> {
2680                 let (a, b) = self.overflowing_add(rhs);
2681                 if b {None} else {Some(a)}
2682             }
2683         }
2684
2685         doc_comment! {
2686             concat!("Checked integer subtraction. Computes `self - rhs`, returning
2687 `None` if overflow occurred.
2688
2689 # Examples
2690
2691 Basic usage:
2692
2693 ```
2694 ", $Feature, "assert_eq!(1", stringify!($SelfT), ".checked_sub(1), Some(0));
2695 assert_eq!(0", stringify!($SelfT), ".checked_sub(1), None);", $EndFeature, "
2696 ```"),
2697             #[stable(feature = "rust1", since = "1.0.0")]
2698             #[must_use = "this returns the result of the operation, \
2699                           without modifying the original"]
2700             #[inline]
2701             pub fn checked_sub(self, rhs: Self) -> Option<Self> {
2702                 let (a, b) = self.overflowing_sub(rhs);
2703                 if b {None} else {Some(a)}
2704             }
2705         }
2706
2707         doc_comment! {
2708             concat!("Checked integer multiplication. Computes `self * rhs`, returning
2709 `None` if overflow occurred.
2710
2711 # Examples
2712
2713 Basic usage:
2714
2715 ```
2716 ", $Feature, "assert_eq!(5", stringify!($SelfT), ".checked_mul(1), Some(5));
2717 assert_eq!(", stringify!($SelfT), "::max_value().checked_mul(2), None);", $EndFeature, "
2718 ```"),
2719             #[stable(feature = "rust1", since = "1.0.0")]
2720             #[must_use = "this returns the result of the operation, \
2721                           without modifying the original"]
2722             #[inline]
2723             pub fn checked_mul(self, rhs: Self) -> Option<Self> {
2724                 let (a, b) = self.overflowing_mul(rhs);
2725                 if b {None} else {Some(a)}
2726             }
2727         }
2728
2729         doc_comment! {
2730             concat!("Checked integer division. Computes `self / rhs`, returning `None`
2731 if `rhs == 0`.
2732
2733 # Examples
2734
2735 Basic usage:
2736
2737 ```
2738 ", $Feature, "assert_eq!(128", stringify!($SelfT), ".checked_div(2), Some(64));
2739 assert_eq!(1", stringify!($SelfT), ".checked_div(0), None);", $EndFeature, "
2740 ```"),
2741             #[stable(feature = "rust1", since = "1.0.0")]
2742             #[must_use = "this returns the result of the operation, \
2743                           without modifying the original"]
2744             #[inline]
2745             pub fn checked_div(self, rhs: Self) -> Option<Self> {
2746                 match rhs {
2747                     0 => None,
2748                     rhs => Some(unsafe { intrinsics::unchecked_div(self, rhs) }),
2749                 }
2750             }
2751         }
2752
2753         doc_comment! {
2754             concat!("Checked Euclidean division. Computes `self.div_euclid(rhs)`, returning `None`
2755 if `rhs == 0`.
2756
2757 # Examples
2758
2759 Basic usage:
2760
2761 ```
2762 #![feature(euclidean_division)]
2763 assert_eq!(128", stringify!($SelfT), ".checked_div_euclid(2), Some(64));
2764 assert_eq!(1", stringify!($SelfT), ".checked_div_euclid(0), None);
2765 ```"),
2766             #[unstable(feature = "euclidean_division", issue = "49048")]
2767             #[must_use = "this returns the result of the operation, \
2768                           without modifying the original"]
2769             #[inline]
2770             pub fn checked_div_euclid(self, rhs: Self) -> Option<Self> {
2771                 if rhs == 0 {
2772                     None
2773                 } else {
2774                     Some(self.div_euclid(rhs))
2775                 }
2776             }
2777         }
2778
2779
2780         doc_comment! {
2781             concat!("Checked integer remainder. Computes `self % rhs`, returning `None`
2782 if `rhs == 0`.
2783
2784 # Examples
2785
2786 Basic usage:
2787
2788 ```
2789 ", $Feature, "assert_eq!(5", stringify!($SelfT), ".checked_rem(2), Some(1));
2790 assert_eq!(5", stringify!($SelfT), ".checked_rem(0), None);", $EndFeature, "
2791 ```"),
2792             #[stable(feature = "wrapping", since = "1.7.0")]
2793             #[must_use = "this returns the result of the operation, \
2794                           without modifying the original"]
2795             #[inline]
2796             pub fn checked_rem(self, rhs: Self) -> Option<Self> {
2797                 if rhs == 0 {
2798                     None
2799                 } else {
2800                     Some(unsafe { intrinsics::unchecked_rem(self, rhs) })
2801                 }
2802             }
2803         }
2804
2805         doc_comment! {
2806             concat!("Checked Euclidean modulo. Computes `self.rem_euclid(rhs)`, returning `None`
2807 if `rhs == 0`.
2808
2809 # Examples
2810
2811 Basic usage:
2812
2813 ```
2814 #![feature(euclidean_division)]
2815 assert_eq!(5", stringify!($SelfT), ".checked_rem_euclid(2), Some(1));
2816 assert_eq!(5", stringify!($SelfT), ".checked_rem_euclid(0), None);
2817 ```"),
2818             #[unstable(feature = "euclidean_division", issue = "49048")]
2819             #[must_use = "this returns the result of the operation, \
2820                           without modifying the original"]
2821             #[inline]
2822             pub fn checked_rem_euclid(self, rhs: Self) -> Option<Self> {
2823                 if rhs == 0 {
2824                     None
2825                 } else {
2826                     Some(self.rem_euclid(rhs))
2827                 }
2828             }
2829         }
2830
2831         doc_comment! {
2832             concat!("Checked negation. Computes `-self`, returning `None` unless `self ==
2833 0`.
2834
2835 Note that negating any positive integer will overflow.
2836
2837 # Examples
2838
2839 Basic usage:
2840
2841 ```
2842 ", $Feature, "assert_eq!(0", stringify!($SelfT), ".checked_neg(), Some(0));
2843 assert_eq!(1", stringify!($SelfT), ".checked_neg(), None);", $EndFeature, "
2844 ```"),
2845             #[stable(feature = "wrapping", since = "1.7.0")]
2846             #[inline]
2847             pub fn checked_neg(self) -> Option<Self> {
2848                 let (a, b) = self.overflowing_neg();
2849                 if b {None} else {Some(a)}
2850             }
2851         }
2852
2853         doc_comment! {
2854             concat!("Checked shift left. Computes `self << rhs`, returning `None`
2855 if `rhs` is larger than or equal to the number of bits in `self`.
2856
2857 # Examples
2858
2859 Basic usage:
2860
2861 ```
2862 ", $Feature, "assert_eq!(0x1", stringify!($SelfT), ".checked_shl(4), Some(0x10));
2863 assert_eq!(0x10", stringify!($SelfT), ".checked_shl(129), None);", $EndFeature, "
2864 ```"),
2865             #[stable(feature = "wrapping", since = "1.7.0")]
2866             #[must_use = "this returns the result of the operation, \
2867                           without modifying the original"]
2868             #[inline]
2869             pub fn checked_shl(self, rhs: u32) -> Option<Self> {
2870                 let (a, b) = self.overflowing_shl(rhs);
2871                 if b {None} else {Some(a)}
2872             }
2873         }
2874
2875         doc_comment! {
2876             concat!("Checked shift right. Computes `self >> rhs`, returning `None`
2877 if `rhs` is larger than or equal to the number of bits in `self`.
2878
2879 # Examples
2880
2881 Basic usage:
2882
2883 ```
2884 ", $Feature, "assert_eq!(0x10", stringify!($SelfT), ".checked_shr(4), Some(0x1));
2885 assert_eq!(0x10", stringify!($SelfT), ".checked_shr(129), None);", $EndFeature, "
2886 ```"),
2887             #[stable(feature = "wrapping", since = "1.7.0")]
2888             #[must_use = "this returns the result of the operation, \
2889                           without modifying the original"]
2890             #[inline]
2891             pub fn checked_shr(self, rhs: u32) -> Option<Self> {
2892                 let (a, b) = self.overflowing_shr(rhs);
2893                 if b {None} else {Some(a)}
2894             }
2895         }
2896
2897         doc_comment! {
2898             concat!("Checked exponentiation. Computes `self.pow(exp)`, returning `None` if
2899 overflow occurred.
2900
2901 # Examples
2902
2903 Basic usage:
2904
2905 ```
2906 ", $Feature, "assert_eq!(2", stringify!($SelfT), ".checked_pow(5), Some(32));
2907 assert_eq!(", stringify!($SelfT), "::max_value().checked_pow(2), None);", $EndFeature, "
2908 ```"),
2909             #[stable(feature = "no_panic_pow", since = "1.34.0")]
2910             #[must_use = "this returns the result of the operation, \
2911                           without modifying the original"]
2912             #[inline]
2913             pub fn checked_pow(self, mut exp: u32) -> Option<Self> {
2914                 let mut base = self;
2915                 let mut acc: Self = 1;
2916
2917                 while exp > 1 {
2918                     if (exp & 1) == 1 {
2919                         acc = acc.checked_mul(base)?;
2920                     }
2921                     exp /= 2;
2922                     base = base.checked_mul(base)?;
2923                 }
2924
2925                 // Deal with the final bit of the exponent separately, since
2926                 // squaring the base afterwards is not necessary and may cause a
2927                 // needless overflow.
2928                 if exp == 1 {
2929                     acc = acc.checked_mul(base)?;
2930                 }
2931
2932                 Some(acc)
2933             }
2934         }
2935
2936         doc_comment! {
2937             concat!("Saturating integer addition. Computes `self + rhs`, saturating at
2938 the numeric bounds instead of overflowing.
2939
2940 # Examples
2941
2942 Basic usage:
2943
2944 ```
2945 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".saturating_add(1), 101);
2946 assert_eq!(200u8.saturating_add(127), 255);", $EndFeature, "
2947 ```"),
2948
2949             #[stable(feature = "rust1", since = "1.0.0")]
2950             #[must_use = "this returns the result of the operation, \
2951                           without modifying the original"]
2952             #[rustc_const_unstable(feature = "const_saturating_int_methods")]
2953             #[inline]
2954             pub const fn saturating_add(self, rhs: Self) -> Self {
2955                 intrinsics::saturating_add(self, rhs)
2956             }
2957         }
2958
2959         doc_comment! {
2960             concat!("Saturating integer subtraction. Computes `self - rhs`, saturating
2961 at the numeric bounds instead of overflowing.
2962
2963 # Examples
2964
2965 Basic usage:
2966
2967 ```
2968 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".saturating_sub(27), 73);
2969 assert_eq!(13", stringify!($SelfT), ".saturating_sub(127), 0);", $EndFeature, "
2970 ```"),
2971             #[stable(feature = "rust1", since = "1.0.0")]
2972             #[must_use = "this returns the result of the operation, \
2973                           without modifying the original"]
2974             #[rustc_const_unstable(feature = "const_saturating_int_methods")]
2975             #[inline]
2976             pub const fn saturating_sub(self, rhs: Self) -> Self {
2977                 intrinsics::saturating_sub(self, rhs)
2978             }
2979         }
2980
2981         doc_comment! {
2982             concat!("Saturating integer multiplication. Computes `self * rhs`,
2983 saturating at the numeric bounds instead of overflowing.
2984
2985 # Examples
2986
2987 Basic usage:
2988
2989 ```
2990 ", $Feature, "use std::", stringify!($SelfT), ";
2991
2992 assert_eq!(2", stringify!($SelfT), ".saturating_mul(10), 20);
2993 assert_eq!((", stringify!($SelfT), "::MAX).saturating_mul(10), ", stringify!($SelfT),
2994 "::MAX);", $EndFeature, "
2995 ```"),
2996             #[stable(feature = "wrapping", since = "1.7.0")]
2997             #[must_use = "this returns the result of the operation, \
2998                           without modifying the original"]
2999             #[inline]
3000             pub fn saturating_mul(self, rhs: Self) -> Self {
3001                 self.checked_mul(rhs).unwrap_or(Self::max_value())
3002             }
3003         }
3004
3005         doc_comment! {
3006             concat!("Saturating integer exponentiation. Computes `self.pow(exp)`,
3007 saturating at the numeric bounds instead of overflowing.
3008
3009 # Examples
3010
3011 Basic usage:
3012
3013 ```
3014 ", $Feature, "use std::", stringify!($SelfT), ";
3015
3016 assert_eq!(4", stringify!($SelfT), ".saturating_pow(3), 64);
3017 assert_eq!(", stringify!($SelfT), "::MAX.saturating_pow(2), ", stringify!($SelfT), "::MAX);",
3018 $EndFeature, "
3019 ```"),
3020             #[stable(feature = "no_panic_pow", since = "1.34.0")]
3021             #[must_use = "this returns the result of the operation, \
3022                           without modifying the original"]
3023             #[inline]
3024             pub fn saturating_pow(self, exp: u32) -> Self {
3025                 match self.checked_pow(exp) {
3026                     Some(x) => x,
3027                     None => Self::max_value(),
3028                 }
3029             }
3030         }
3031
3032         doc_comment! {
3033             concat!("Wrapping (modular) addition. Computes `self + rhs`,
3034 wrapping around at the boundary of the type.
3035
3036 # Examples
3037
3038 Basic usage:
3039
3040 ```
3041 ", $Feature, "assert_eq!(200", stringify!($SelfT), ".wrapping_add(55), 255);
3042 assert_eq!(200", stringify!($SelfT), ".wrapping_add(", stringify!($SelfT), "::max_value()), 199);",
3043 $EndFeature, "
3044 ```"),
3045             #[stable(feature = "rust1", since = "1.0.0")]
3046             #[must_use = "this returns the result of the operation, \
3047                           without modifying the original"]
3048             #[inline]
3049             pub const fn wrapping_add(self, rhs: Self) -> Self {
3050                 intrinsics::overflowing_add(self, rhs)
3051             }
3052         }
3053
3054         doc_comment! {
3055             concat!("Wrapping (modular) subtraction. Computes `self - rhs`,
3056 wrapping around at the boundary of the type.
3057
3058 # Examples
3059
3060 Basic usage:
3061
3062 ```
3063 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".wrapping_sub(100), 0);
3064 assert_eq!(100", stringify!($SelfT), ".wrapping_sub(", stringify!($SelfT), "::max_value()), 101);",
3065 $EndFeature, "
3066 ```"),
3067             #[stable(feature = "rust1", since = "1.0.0")]
3068             #[must_use = "this returns the result of the operation, \
3069                           without modifying the original"]
3070             #[inline]
3071             pub const fn wrapping_sub(self, rhs: Self) -> Self {
3072                 intrinsics::overflowing_sub(self, rhs)
3073             }
3074         }
3075
3076         /// Wrapping (modular) multiplication. Computes `self *
3077         /// rhs`, wrapping around at the boundary of the type.
3078         ///
3079         /// # Examples
3080         ///
3081         /// Basic usage:
3082         ///
3083         /// Please note that this example is shared between integer types.
3084         /// Which explains why `u8` is used here.
3085         ///
3086         /// ```
3087         /// assert_eq!(10u8.wrapping_mul(12), 120);
3088         /// assert_eq!(25u8.wrapping_mul(12), 44);
3089         /// ```
3090         #[stable(feature = "rust1", since = "1.0.0")]
3091         #[must_use = "this returns the result of the operation, \
3092                           without modifying the original"]
3093         #[inline]
3094         pub const fn wrapping_mul(self, rhs: Self) -> Self {
3095             intrinsics::overflowing_mul(self, rhs)
3096         }
3097
3098         doc_comment! {
3099             concat!("Wrapping (modular) division. Computes `self / rhs`.
3100 Wrapped division on unsigned types is just normal division.
3101 There's no way wrapping could ever happen.
3102 This function exists, so that all operations
3103 are accounted for in the wrapping operations.
3104
3105 # Examples
3106
3107 Basic usage:
3108
3109 ```
3110 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".wrapping_div(10), 10);", $EndFeature, "
3111 ```"),
3112             #[stable(feature = "num_wrapping", since = "1.2.0")]
3113             #[must_use = "this returns the result of the operation, \
3114                           without modifying the original"]
3115             #[inline]
3116             pub fn wrapping_div(self, rhs: Self) -> Self {
3117                 self / rhs
3118             }
3119         }
3120
3121         doc_comment! {
3122             concat!("Wrapping Euclidean division. Computes `self.div_euclid(rhs)`.
3123 Wrapped division on unsigned types is just normal division.
3124 There's no way wrapping could ever happen.
3125 This function exists, so that all operations
3126 are accounted for in the wrapping operations.
3127 Since, for the positive integers, all common
3128 definitions of division are equal, this
3129 is exactly equal to `self.wrapping_div(rhs)`.
3130
3131 # Examples
3132
3133 Basic usage:
3134
3135 ```
3136 #![feature(euclidean_division)]
3137 assert_eq!(100", stringify!($SelfT), ".wrapping_div_euclid(10), 10);
3138 ```"),
3139             #[unstable(feature = "euclidean_division", issue = "49048")]
3140             #[must_use = "this returns the result of the operation, \
3141                           without modifying the original"]
3142             #[inline]
3143             pub fn wrapping_div_euclid(self, rhs: Self) -> Self {
3144                 self / rhs
3145             }
3146         }
3147
3148         doc_comment! {
3149             concat!("Wrapping (modular) remainder. Computes `self % rhs`.
3150 Wrapped remainder calculation on unsigned types is
3151 just the regular remainder calculation.
3152 There's no way wrapping could ever happen.
3153 This function exists, so that all operations
3154 are accounted for in the wrapping operations.
3155
3156 # Examples
3157
3158 Basic usage:
3159
3160 ```
3161 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".wrapping_rem(10), 0);", $EndFeature, "
3162 ```"),
3163             #[stable(feature = "num_wrapping", since = "1.2.0")]
3164             #[must_use = "this returns the result of the operation, \
3165                           without modifying the original"]
3166             #[inline]
3167             pub fn wrapping_rem(self, rhs: Self) -> Self {
3168                 self % rhs
3169             }
3170         }
3171
3172         doc_comment! {
3173             concat!("Wrapping Euclidean modulo. Computes `self.rem_euclid(rhs)`.
3174 Wrapped modulo calculation on unsigned types is
3175 just the regular remainder calculation.
3176 There's no way wrapping could ever happen.
3177 This function exists, so that all operations
3178 are accounted for in the wrapping operations.
3179 Since, for the positive integers, all common
3180 definitions of division are equal, this
3181 is exactly equal to `self.wrapping_rem(rhs)`.
3182
3183 # Examples
3184
3185 Basic usage:
3186
3187 ```
3188 #![feature(euclidean_division)]
3189 assert_eq!(100", stringify!($SelfT), ".wrapping_rem_euclid(10), 0);
3190 ```"),
3191             #[unstable(feature = "euclidean_division", issue = "49048")]
3192             #[must_use = "this returns the result of the operation, \
3193                           without modifying the original"]
3194             #[inline]
3195             pub fn wrapping_rem_euclid(self, rhs: Self) -> Self {
3196                 self % rhs
3197             }
3198         }
3199
3200         /// Wrapping (modular) negation. Computes `-self`,
3201         /// wrapping around at the boundary of the type.
3202         ///
3203         /// Since unsigned types do not have negative equivalents
3204         /// all applications of this function will wrap (except for `-0`).
3205         /// For values smaller than the corresponding signed type's maximum
3206         /// the result is the same as casting the corresponding signed value.
3207         /// Any larger values are equivalent to `MAX + 1 - (val - MAX - 1)` where
3208         /// `MAX` is the corresponding signed type's maximum.
3209         ///
3210         /// # Examples
3211         ///
3212         /// Basic usage:
3213         ///
3214         /// Please note that this example is shared between integer types.
3215         /// Which explains why `i8` is used here.
3216         ///
3217         /// ```
3218         /// assert_eq!(100i8.wrapping_neg(), -100);
3219         /// assert_eq!((-128i8).wrapping_neg(), -128);
3220         /// ```
3221         #[stable(feature = "num_wrapping", since = "1.2.0")]
3222         #[inline]
3223         pub const fn wrapping_neg(self) -> Self {
3224             self.overflowing_neg().0
3225         }
3226
3227         doc_comment! {
3228             concat!("Panic-free bitwise shift-left; yields `self << mask(rhs)`,
3229 where `mask` removes any high-order bits of `rhs` that
3230 would cause the shift to exceed the bitwidth of the type.
3231
3232 Note that this is *not* the same as a rotate-left; the
3233 RHS of a wrapping shift-left is restricted to the range
3234 of the type, rather than the bits shifted out of the LHS
3235 being returned to the other end. The primitive integer
3236 types all implement a `rotate_left` function, which may
3237 be what you want instead.
3238
3239 # Examples
3240
3241 Basic usage:
3242
3243 ```
3244 ", $Feature, "assert_eq!(1", stringify!($SelfT), ".wrapping_shl(7), 128);
3245 assert_eq!(1", stringify!($SelfT), ".wrapping_shl(128), 1);", $EndFeature, "
3246 ```"),
3247             #[stable(feature = "num_wrapping", since = "1.2.0")]
3248             #[must_use = "this returns the result of the operation, \
3249                           without modifying the original"]
3250             #[inline]
3251             pub const fn wrapping_shl(self, rhs: u32) -> Self {
3252                 unsafe {
3253                     intrinsics::unchecked_shl(self, (rhs & ($BITS - 1)) as $SelfT)
3254                 }
3255             }
3256         }
3257
3258         doc_comment! {
3259             concat!("Panic-free bitwise shift-right; yields `self >> mask(rhs)`,
3260 where `mask` removes any high-order bits of `rhs` that
3261 would cause the shift to exceed the bitwidth of the type.
3262
3263 Note that this is *not* the same as a rotate-right; the
3264 RHS of a wrapping shift-right is restricted to the range
3265 of the type, rather than the bits shifted out of the LHS
3266 being returned to the other end. The primitive integer
3267 types all implement a `rotate_right` function, which may
3268 be what you want instead.
3269
3270 # Examples
3271
3272 Basic usage:
3273
3274 ```
3275 ", $Feature, "assert_eq!(128", stringify!($SelfT), ".wrapping_shr(7), 1);
3276 assert_eq!(128", stringify!($SelfT), ".wrapping_shr(128), 128);", $EndFeature, "
3277 ```"),
3278             #[stable(feature = "num_wrapping", since = "1.2.0")]
3279             #[must_use = "this returns the result of the operation, \
3280                           without modifying the original"]
3281             #[inline]
3282             pub const fn wrapping_shr(self, rhs: u32) -> Self {
3283                 unsafe {
3284                     intrinsics::unchecked_shr(self, (rhs & ($BITS - 1)) as $SelfT)
3285                 }
3286             }
3287         }
3288
3289         doc_comment! {
3290             concat!("Wrapping (modular) exponentiation. Computes `self.pow(exp)`,
3291 wrapping around at the boundary of the type.
3292
3293 # Examples
3294
3295 Basic usage:
3296
3297 ```
3298 ", $Feature, "assert_eq!(3", stringify!($SelfT), ".wrapping_pow(5), 243);
3299 assert_eq!(3u8.wrapping_pow(6), 217);", $EndFeature, "
3300 ```"),
3301             #[stable(feature = "no_panic_pow", since = "1.34.0")]
3302             #[must_use = "this returns the result of the operation, \
3303                           without modifying the original"]
3304             #[inline]
3305             pub fn wrapping_pow(self, mut exp: u32) -> Self {
3306                 let mut base = self;
3307                 let mut acc: Self = 1;
3308
3309                 while exp > 1 {
3310                     if (exp & 1) == 1 {
3311                         acc = acc.wrapping_mul(base);
3312                     }
3313                     exp /= 2;
3314                     base = base.wrapping_mul(base);
3315                 }
3316
3317                 // Deal with the final bit of the exponent separately, since
3318                 // squaring the base afterwards is not necessary and may cause a
3319                 // needless overflow.
3320                 if exp == 1 {
3321                     acc = acc.wrapping_mul(base);
3322                 }
3323
3324                 acc
3325             }
3326         }
3327
3328         doc_comment! {
3329             concat!("Calculates `self` + `rhs`
3330
3331 Returns a tuple of the addition along with a boolean indicating
3332 whether an arithmetic overflow would occur. If an overflow would
3333 have occurred then the wrapped value is returned.
3334
3335 # Examples
3336
3337 Basic usage
3338
3339 ```
3340 ", $Feature, "use std::", stringify!($SelfT), ";
3341
3342 assert_eq!(5", stringify!($SelfT), ".overflowing_add(2), (7, false));
3343 assert_eq!(", stringify!($SelfT), "::MAX.overflowing_add(1), (0, true));", $EndFeature, "
3344 ```"),
3345             #[stable(feature = "wrapping", since = "1.7.0")]
3346             #[must_use = "this returns the result of the operation, \
3347                           without modifying the original"]
3348             #[inline]
3349             pub const fn overflowing_add(self, rhs: Self) -> (Self, bool) {
3350                 let (a, b) = intrinsics::add_with_overflow(self as $ActualT, rhs as $ActualT);
3351                 (a as Self, b)
3352             }
3353         }
3354
3355         doc_comment! {
3356             concat!("Calculates `self` - `rhs`
3357
3358 Returns a tuple of the subtraction along with a boolean indicating
3359 whether an arithmetic overflow would occur. If an overflow would
3360 have occurred then the wrapped value is returned.
3361
3362 # Examples
3363
3364 Basic usage
3365
3366 ```
3367 ", $Feature, "use std::", stringify!($SelfT), ";
3368
3369 assert_eq!(5", stringify!($SelfT), ".overflowing_sub(2), (3, false));
3370 assert_eq!(0", stringify!($SelfT), ".overflowing_sub(1), (", stringify!($SelfT), "::MAX, true));",
3371 $EndFeature, "
3372 ```"),
3373             #[stable(feature = "wrapping", since = "1.7.0")]
3374             #[must_use = "this returns the result of the operation, \
3375                           without modifying the original"]
3376             #[inline]
3377             pub const fn overflowing_sub(self, rhs: Self) -> (Self, bool) {
3378                 let (a, b) = intrinsics::sub_with_overflow(self as $ActualT, rhs as $ActualT);
3379                 (a as Self, b)
3380             }
3381         }
3382
3383         /// Calculates the multiplication of `self` and `rhs`.
3384         ///
3385         /// Returns a tuple of the multiplication along with a boolean
3386         /// indicating whether an arithmetic overflow would occur. If an
3387         /// overflow would have occurred then the wrapped value is returned.
3388         ///
3389         /// # Examples
3390         ///
3391         /// Basic usage:
3392         ///
3393         /// Please note that this example is shared between integer types.
3394         /// Which explains why `u32` is used here.
3395         ///
3396         /// ```
3397         /// assert_eq!(5u32.overflowing_mul(2), (10, false));
3398         /// assert_eq!(1_000_000_000u32.overflowing_mul(10), (1410065408, true));
3399         /// ```
3400         #[stable(feature = "wrapping", since = "1.7.0")]
3401         #[must_use = "this returns the result of the operation, \
3402                           without modifying the original"]
3403         #[inline]
3404         pub const fn overflowing_mul(self, rhs: Self) -> (Self, bool) {
3405             let (a, b) = intrinsics::mul_with_overflow(self as $ActualT, rhs as $ActualT);
3406             (a as Self, b)
3407         }
3408
3409         doc_comment! {
3410             concat!("Calculates the divisor when `self` is divided by `rhs`.
3411
3412 Returns a tuple of the divisor along with a boolean indicating
3413 whether an arithmetic overflow would occur. Note that for unsigned
3414 integers overflow never occurs, so the second value is always
3415 `false`.
3416
3417 # Panics
3418
3419 This function will panic if `rhs` is 0.
3420
3421 # Examples
3422
3423 Basic usage
3424
3425 ```
3426 ", $Feature, "assert_eq!(5", stringify!($SelfT), ".overflowing_div(2), (2, false));", $EndFeature, "
3427 ```"),
3428             #[inline]
3429             #[stable(feature = "wrapping", since = "1.7.0")]
3430             #[must_use = "this returns the result of the operation, \
3431                           without modifying the original"]
3432             pub fn overflowing_div(self, rhs: Self) -> (Self, bool) {
3433                 (self / rhs, false)
3434             }
3435         }
3436
3437         doc_comment! {
3438             concat!("Calculates the quotient of Euclidean division `self.div_euclid(rhs)`.
3439
3440 Returns a tuple of the divisor along with a boolean indicating
3441 whether an arithmetic overflow would occur. Note that for unsigned
3442 integers overflow never occurs, so the second value is always
3443 `false`.
3444 Since, for the positive integers, all common
3445 definitions of division are equal, this
3446 is exactly equal to `self.overflowing_div(rhs)`.
3447
3448 # Panics
3449
3450 This function will panic if `rhs` is 0.
3451
3452 # Examples
3453
3454 Basic usage
3455
3456 ```
3457 #![feature(euclidean_division)]
3458 assert_eq!(5", stringify!($SelfT), ".overflowing_div_euclid(2), (2, false));
3459 ```"),
3460             #[inline]
3461             #[unstable(feature = "euclidean_division", issue = "49048")]
3462             #[must_use = "this returns the result of the operation, \
3463                           without modifying the original"]
3464             pub fn overflowing_div_euclid(self, rhs: Self) -> (Self, bool) {
3465                 (self / rhs, false)
3466             }
3467         }
3468
3469         doc_comment! {
3470             concat!("Calculates the remainder when `self` is divided by `rhs`.
3471
3472 Returns a tuple of the remainder after dividing along with a boolean
3473 indicating whether an arithmetic overflow would occur. Note that for
3474 unsigned integers overflow never occurs, so the second value is
3475 always `false`.
3476
3477 # Panics
3478
3479 This function will panic if `rhs` is 0.
3480
3481 # Examples
3482
3483 Basic usage
3484
3485 ```
3486 ", $Feature, "assert_eq!(5", stringify!($SelfT), ".overflowing_rem(2), (1, false));", $EndFeature, "
3487 ```"),
3488             #[inline]
3489             #[stable(feature = "wrapping", since = "1.7.0")]
3490             #[must_use = "this returns the result of the operation, \
3491                           without modifying the original"]
3492             pub fn overflowing_rem(self, rhs: Self) -> (Self, bool) {
3493                 (self % rhs, false)
3494             }
3495         }
3496
3497         doc_comment! {
3498             concat!("Calculates the remainder `self.rem_euclid(rhs)` as if by Euclidean division.
3499
3500 Returns a tuple of the modulo after dividing along with a boolean
3501 indicating whether an arithmetic overflow would occur. Note that for
3502 unsigned integers overflow never occurs, so the second value is
3503 always `false`.
3504 Since, for the positive integers, all common
3505 definitions of division are equal, this operation
3506 is exactly equal to `self.overflowing_rem(rhs)`.
3507
3508 # Panics
3509
3510 This function will panic if `rhs` is 0.
3511
3512 # Examples
3513
3514 Basic usage
3515
3516 ```
3517 #![feature(euclidean_division)]
3518 assert_eq!(5", stringify!($SelfT), ".overflowing_rem_euclid(2), (1, false));
3519 ```"),
3520             #[inline]
3521             #[unstable(feature = "euclidean_division", issue = "49048")]
3522             #[must_use = "this returns the result of the operation, \
3523                           without modifying the original"]
3524             pub fn overflowing_rem_euclid(self, rhs: Self) -> (Self, bool) {
3525                 (self % rhs, false)
3526             }
3527         }
3528
3529         doc_comment! {
3530             concat!("Negates self in an overflowing fashion.
3531
3532 Returns `!self + 1` using wrapping operations to return the value
3533 that represents the negation of this unsigned value. Note that for
3534 positive unsigned values overflow always occurs, but negating 0 does
3535 not overflow.
3536
3537 # Examples
3538
3539 Basic usage
3540
3541 ```
3542 ", $Feature, "assert_eq!(0", stringify!($SelfT), ".overflowing_neg(), (0, false));
3543 assert_eq!(2", stringify!($SelfT), ".overflowing_neg(), (-2i32 as ", stringify!($SelfT),
3544 ", true));", $EndFeature, "
3545 ```"),
3546             #[inline]
3547             #[stable(feature = "wrapping", since = "1.7.0")]
3548             pub const fn overflowing_neg(self) -> (Self, bool) {
3549                 ((!self).wrapping_add(1), self != 0)
3550             }
3551         }
3552
3553         doc_comment! {
3554             concat!("Shifts self left by `rhs` bits.
3555
3556 Returns a tuple of the shifted version of self along with a boolean
3557 indicating whether the shift value was larger than or equal to the
3558 number of bits. If the shift value is too large, then value is
3559 masked (N-1) where N is the number of bits, and this value is then
3560 used to perform the shift.
3561
3562 # Examples
3563
3564 Basic usage
3565
3566 ```
3567 ", $Feature, "assert_eq!(0x1", stringify!($SelfT), ".overflowing_shl(4), (0x10, false));
3568 assert_eq!(0x1", stringify!($SelfT), ".overflowing_shl(132), (0x10, true));", $EndFeature, "
3569 ```"),
3570             #[stable(feature = "wrapping", since = "1.7.0")]
3571             #[must_use = "this returns the result of the operation, \
3572                           without modifying the original"]
3573             #[inline]
3574             pub const fn overflowing_shl(self, rhs: u32) -> (Self, bool) {
3575                 (self.wrapping_shl(rhs), (rhs > ($BITS - 1)))
3576             }
3577         }
3578
3579         doc_comment! {
3580             concat!("Shifts self right by `rhs` bits.
3581
3582 Returns a tuple of the shifted version of self along with a boolean
3583 indicating whether the shift value was larger than or equal to the
3584 number of bits. If the shift value is too large, then value is
3585 masked (N-1) where N is the number of bits, and this value is then
3586 used to perform the shift.
3587
3588 # Examples
3589
3590 Basic usage
3591
3592 ```
3593 ", $Feature, "assert_eq!(0x10", stringify!($SelfT), ".overflowing_shr(4), (0x1, false));
3594 assert_eq!(0x10", stringify!($SelfT), ".overflowing_shr(132), (0x1, true));", $EndFeature, "
3595 ```"),
3596             #[stable(feature = "wrapping", since = "1.7.0")]
3597             #[must_use = "this returns the result of the operation, \
3598                           without modifying the original"]
3599             #[inline]
3600             pub const fn overflowing_shr(self, rhs: u32) -> (Self, bool) {
3601                 (self.wrapping_shr(rhs), (rhs > ($BITS - 1)))
3602             }
3603         }
3604
3605         doc_comment! {
3606             concat!("Raises self to the power of `exp`, using exponentiation by squaring.
3607
3608 Returns a tuple of the exponentiation along with a bool indicating
3609 whether an overflow happened.
3610
3611 # Examples
3612
3613 Basic usage:
3614
3615 ```
3616 ", $Feature, "assert_eq!(3", stringify!($SelfT), ".overflowing_pow(5), (243, false));
3617 assert_eq!(3u8.overflowing_pow(6), (217, true));", $EndFeature, "
3618 ```"),
3619             #[stable(feature = "no_panic_pow", since = "1.34.0")]
3620             #[must_use = "this returns the result of the operation, \
3621                           without modifying the original"]
3622             #[inline]
3623             pub fn overflowing_pow(self, mut exp: u32) -> (Self, bool) {
3624                 let mut base = self;
3625                 let mut acc: Self = 1;
3626                 let mut overflown = false;
3627                 // Scratch space for storing results of overflowing_mul.
3628                 let mut r;
3629
3630                 while exp > 1 {
3631                     if (exp & 1) == 1 {
3632                         r = acc.overflowing_mul(base);
3633                         acc = r.0;
3634                         overflown |= r.1;
3635                     }
3636                     exp /= 2;
3637                     r = base.overflowing_mul(base);
3638                     base = r.0;
3639                     overflown |= r.1;
3640                 }
3641
3642                 // Deal with the final bit of the exponent separately, since
3643                 // squaring the base afterwards is not necessary and may cause a
3644                 // needless overflow.
3645                 if exp == 1 {
3646                     r = acc.overflowing_mul(base);
3647                     acc = r.0;
3648                     overflown |= r.1;
3649                 }
3650
3651                 (acc, overflown)
3652             }
3653         }
3654
3655         doc_comment! {
3656             concat!("Raises self to the power of `exp`, using exponentiation by squaring.
3657
3658 # Examples
3659
3660 Basic usage:
3661
3662 ```
3663 ", $Feature, "assert_eq!(2", stringify!($SelfT), ".pow(5), 32);", $EndFeature, "
3664 ```"),
3665         #[stable(feature = "rust1", since = "1.0.0")]
3666         #[must_use = "this returns the result of the operation, \
3667                           without modifying the original"]
3668         #[inline]
3669         #[rustc_inherit_overflow_checks]
3670         pub fn pow(self, mut exp: u32) -> Self {
3671             let mut base = self;
3672             let mut acc = 1;
3673
3674             while exp > 1 {
3675                 if (exp & 1) == 1 {
3676                     acc = acc * base;
3677                 }
3678                 exp /= 2;
3679                 base = base * base;
3680             }
3681
3682             // Deal with the final bit of the exponent separately, since
3683             // squaring the base afterwards is not necessary and may cause a
3684             // needless overflow.
3685             if exp == 1 {
3686                 acc = acc * base;
3687             }
3688
3689             acc
3690         }
3691     }
3692
3693             doc_comment! {
3694             concat!("Performs Euclidean division.
3695
3696 Since, for the positive integers, all common
3697 definitions of division are equal, this
3698 is exactly equal to `self / rhs`.
3699
3700 # Examples
3701
3702 Basic usage:
3703
3704 ```
3705 #![feature(euclidean_division)]
3706 assert_eq!(7", stringify!($SelfT), ".div_euclid(4), 1); // or any other integer type
3707 ```"),
3708             #[unstable(feature = "euclidean_division", issue = "49048")]
3709             #[must_use = "this returns the result of the operation, \
3710                           without modifying the original"]
3711             #[inline]
3712             #[rustc_inherit_overflow_checks]
3713             pub fn div_euclid(self, rhs: Self) -> Self {
3714                 self / rhs
3715             }
3716         }
3717
3718
3719         doc_comment! {
3720             concat!("Calculates the least remainder of `self (mod rhs)`.
3721
3722 Since, for the positive integers, all common
3723 definitions of division are equal, this
3724 is exactly equal to `self % rhs`.
3725
3726 # Examples
3727
3728 Basic usage:
3729
3730 ```
3731 #![feature(euclidean_division)]
3732 assert_eq!(7", stringify!($SelfT), ".rem_euclid(4), 3); // or any other integer type
3733 ```"),
3734             #[unstable(feature = "euclidean_division", issue = "49048")]
3735             #[must_use = "this returns the result of the operation, \
3736                           without modifying the original"]
3737             #[inline]
3738             #[rustc_inherit_overflow_checks]
3739             pub fn rem_euclid(self, rhs: Self) -> Self {
3740                 self % rhs
3741             }
3742         }
3743
3744         doc_comment! {
3745             concat!("Returns `true` if and only if `self == 2^k` for some `k`.
3746
3747 # Examples
3748
3749 Basic usage:
3750
3751 ```
3752 ", $Feature, "assert!(16", stringify!($SelfT), ".is_power_of_two());
3753 assert!(!10", stringify!($SelfT), ".is_power_of_two());", $EndFeature, "
3754 ```"),
3755             #[stable(feature = "rust1", since = "1.0.0")]
3756             #[inline]
3757             pub fn is_power_of_two(self) -> bool {
3758                 (self.wrapping_sub(1)) & self == 0 && !(self == 0)
3759             }
3760         }
3761
3762         // Returns one less than next power of two.
3763         // (For 8u8 next power of two is 8u8 and for 6u8 it is 8u8)
3764         //
3765         // 8u8.one_less_than_next_power_of_two() == 7
3766         // 6u8.one_less_than_next_power_of_two() == 7
3767         //
3768         // This method cannot overflow, as in the `next_power_of_two`
3769         // overflow cases it instead ends up returning the maximum value
3770         // of the type, and can return 0 for 0.
3771         #[inline]
3772         fn one_less_than_next_power_of_two(self) -> Self {
3773             if self <= 1 { return 0; }
3774
3775             // Because `p > 0`, it cannot consist entirely of leading zeros.
3776             // That means the shift is always in-bounds, and some processors
3777             // (such as intel pre-haswell) have more efficient ctlz
3778             // intrinsics when the argument is non-zero.
3779             let p = self - 1;
3780             let z = unsafe { intrinsics::ctlz_nonzero(p) };
3781             <$SelfT>::max_value() >> z
3782         }
3783
3784         doc_comment! {
3785             concat!("Returns the smallest power of two greater than or equal to `self`.
3786
3787 When return value overflows (i.e., `self > (1 << (N-1))` for type
3788 `uN`), it panics in debug mode and return value is wrapped to 0 in
3789 release mode (the only situation in which method can return 0).
3790
3791 # Examples
3792
3793 Basic usage:
3794
3795 ```
3796 ", $Feature, "assert_eq!(2", stringify!($SelfT), ".next_power_of_two(), 2);
3797 assert_eq!(3", stringify!($SelfT), ".next_power_of_two(), 4);", $EndFeature, "
3798 ```"),
3799             #[stable(feature = "rust1", since = "1.0.0")]
3800             #[inline]
3801             pub fn next_power_of_two(self) -> Self {
3802                 // Call the trait to get overflow checks
3803                 ops::Add::add(self.one_less_than_next_power_of_two(), 1)
3804             }
3805         }
3806
3807         doc_comment! {
3808             concat!("Returns the smallest power of two greater than or equal to `n`. If
3809 the next power of two is greater than the type's maximum value,
3810 `None` is returned, otherwise the power of two is wrapped in `Some`.
3811
3812 # Examples
3813
3814 Basic usage:
3815
3816 ```
3817 ", $Feature, "assert_eq!(2", stringify!($SelfT),
3818 ".checked_next_power_of_two(), Some(2));
3819 assert_eq!(3", stringify!($SelfT), ".checked_next_power_of_two(), Some(4));
3820 assert_eq!(", stringify!($SelfT), "::max_value().checked_next_power_of_two(), None);",
3821 $EndFeature, "
3822 ```"),
3823             #[inline]
3824             #[stable(feature = "rust1", since = "1.0.0")]
3825             pub fn checked_next_power_of_two(self) -> Option<Self> {
3826                 self.one_less_than_next_power_of_two().checked_add(1)
3827             }
3828         }
3829
3830         doc_comment! {
3831             concat!("Returns the smallest power of two greater than or equal to `n`. If
3832 the next power of two is greater than the type's maximum value,
3833 the return value is wrapped to `0`.
3834
3835 # Examples
3836
3837 Basic usage:
3838
3839 ```
3840 #![feature(wrapping_next_power_of_two)]
3841 ", $Feature, "
3842 assert_eq!(2", stringify!($SelfT), ".wrapping_next_power_of_two(), 2);
3843 assert_eq!(3", stringify!($SelfT), ".wrapping_next_power_of_two(), 4);
3844 assert_eq!(", stringify!($SelfT), "::max_value().wrapping_next_power_of_two(), 0);",
3845 $EndFeature, "
3846 ```"),
3847             #[unstable(feature = "wrapping_next_power_of_two", issue = "32463",
3848                        reason = "needs decision on wrapping behaviour")]
3849             pub fn wrapping_next_power_of_two(self) -> Self {
3850                 self.one_less_than_next_power_of_two().wrapping_add(1)
3851             }
3852         }
3853
3854         doc_comment! {
3855             concat!("Return the memory representation of this integer as a byte array in
3856 big-endian (network) byte order.
3857 ",
3858 $to_xe_bytes_doc,
3859 "
3860 # Examples
3861
3862 ```
3863 let bytes = ", $swap_op, stringify!($SelfT), ".to_be_bytes();
3864 assert_eq!(bytes, ", $be_bytes, ");
3865 ```"),
3866             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
3867             #[rustc_const_unstable(feature = "const_int_conversion")]
3868             #[inline]
3869             pub const fn to_be_bytes(self) -> [u8; mem::size_of::<Self>()] {
3870                 self.to_be().to_ne_bytes()
3871             }
3872         }
3873
3874         doc_comment! {
3875             concat!("Return the memory representation of this integer as a byte array in
3876 little-endian byte order.
3877 ",
3878 $to_xe_bytes_doc,
3879 "
3880 # Examples
3881
3882 ```
3883 let bytes = ", $swap_op, stringify!($SelfT), ".to_le_bytes();
3884 assert_eq!(bytes, ", $le_bytes, ");
3885 ```"),
3886             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
3887             #[rustc_const_unstable(feature = "const_int_conversion")]
3888             #[inline]
3889             pub const fn to_le_bytes(self) -> [u8; mem::size_of::<Self>()] {
3890                 self.to_le().to_ne_bytes()
3891             }
3892         }
3893
3894         doc_comment! {
3895             concat!("
3896 Return the memory representation of this integer as a byte array in
3897 native byte order.
3898
3899 As the target platform's native endianness is used, portable code
3900 should use [`to_be_bytes`] or [`to_le_bytes`], as appropriate,
3901 instead.
3902 ",
3903 $to_xe_bytes_doc,
3904 "
3905 [`to_be_bytes`]: #method.to_be_bytes
3906 [`to_le_bytes`]: #method.to_le_bytes
3907
3908 # Examples
3909
3910 ```
3911 let bytes = ", $swap_op, stringify!($SelfT), ".to_ne_bytes();
3912 assert_eq!(bytes, if cfg!(target_endian = \"big\") {
3913         ", $be_bytes, "
3914     } else {
3915         ", $le_bytes, "
3916     });
3917 ```"),
3918             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
3919             #[rustc_const_unstable(feature = "const_int_conversion")]
3920             #[inline]
3921             pub const fn to_ne_bytes(self) -> [u8; mem::size_of::<Self>()] {
3922                 unsafe { mem::transmute(self) }
3923             }
3924         }
3925
3926         doc_comment! {
3927             concat!("Create an integer value from its representation as a byte array in
3928 big endian.
3929 ",
3930 $from_xe_bytes_doc,
3931 "
3932 # Examples
3933
3934 ```
3935 let value = ", stringify!($SelfT), "::from_be_bytes(", $be_bytes, ");
3936 assert_eq!(value, ", $swap_op, ");
3937 ```
3938
3939 When starting from a slice rather than an array, fallible conversion APIs can be used:
3940
3941 ```
3942 use std::convert::TryInto;
3943
3944 fn read_be_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {
3945     let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());
3946     *input = rest;
3947     ", stringify!($SelfT), "::from_be_bytes(int_bytes.try_into().unwrap())
3948 }
3949 ```"),
3950             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
3951             #[rustc_const_unstable(feature = "const_int_conversion")]
3952             #[inline]
3953             pub const fn from_be_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
3954                 Self::from_be(Self::from_ne_bytes(bytes))
3955             }
3956         }
3957
3958         doc_comment! {
3959             concat!("
3960 Create an integer value from its representation as a byte array in
3961 little endian.
3962 ",
3963 $from_xe_bytes_doc,
3964 "
3965 # Examples
3966
3967 ```
3968 let value = ", stringify!($SelfT), "::from_le_bytes(", $le_bytes, ");
3969 assert_eq!(value, ", $swap_op, ");
3970 ```
3971
3972 When starting from a slice rather than an array, fallible conversion APIs can be used:
3973
3974 ```
3975 use std::convert::TryInto;
3976
3977 fn read_le_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {
3978     let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());
3979     *input = rest;
3980     ", stringify!($SelfT), "::from_le_bytes(int_bytes.try_into().unwrap())
3981 }
3982 ```"),
3983             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
3984             #[rustc_const_unstable(feature = "const_int_conversion")]
3985             #[inline]
3986             pub const fn from_le_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
3987                 Self::from_le(Self::from_ne_bytes(bytes))
3988             }
3989         }
3990
3991         doc_comment! {
3992             concat!("Create an integer value from its memory representation as a byte
3993 array in native endianness.
3994
3995 As the target platform's native endianness is used, portable code
3996 likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as
3997 appropriate instead.
3998
3999 [`from_be_bytes`]: #method.from_be_bytes
4000 [`from_le_bytes`]: #method.from_le_bytes
4001 ",
4002 $from_xe_bytes_doc,
4003 "
4004 # Examples
4005
4006 ```
4007 let value = ", stringify!($SelfT), "::from_ne_bytes(if cfg!(target_endian = \"big\") {
4008         ", $be_bytes, "
4009     } else {
4010         ", $le_bytes, "
4011     });
4012 assert_eq!(value, ", $swap_op, ");
4013 ```
4014
4015 When starting from a slice rather than an array, fallible conversion APIs can be used:
4016
4017 ```
4018 use std::convert::TryInto;
4019
4020 fn read_ne_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {
4021     let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());
4022     *input = rest;
4023     ", stringify!($SelfT), "::from_ne_bytes(int_bytes.try_into().unwrap())
4024 }
4025 ```"),
4026             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
4027             #[rustc_const_unstable(feature = "const_int_conversion")]
4028             #[inline]
4029             pub const fn from_ne_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
4030                 unsafe { mem::transmute(bytes) }
4031             }
4032         }
4033     }
4034 }
4035
4036 #[lang = "u8"]
4037 impl u8 {
4038     uint_impl! { u8, u8, 8, 255, "", "", 2, "0x82", "0xa", "0x12", "0x12", "0x48", "[0x12]",
4039         "[0x12]", "", "" }
4040
4041
4042     /// Checks if the value is within the ASCII range.
4043     ///
4044     /// # Examples
4045     ///
4046     /// ```
4047     /// let ascii = 97u8;
4048     /// let non_ascii = 150u8;
4049     ///
4050     /// assert!(ascii.is_ascii());
4051     /// assert!(!non_ascii.is_ascii());
4052     /// ```
4053     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4054     #[inline]
4055     pub fn is_ascii(&self) -> bool {
4056         *self & 128 == 0
4057     }
4058
4059     /// Makes a copy of the value in its ASCII upper case equivalent.
4060     ///
4061     /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
4062     /// but non-ASCII letters are unchanged.
4063     ///
4064     /// To uppercase the value in-place, use [`make_ascii_uppercase`].
4065     ///
4066     /// # Examples
4067     ///
4068     /// ```
4069     /// let lowercase_a = 97u8;
4070     ///
4071     /// assert_eq!(65, lowercase_a.to_ascii_uppercase());
4072     /// ```
4073     ///
4074     /// [`make_ascii_uppercase`]: #method.make_ascii_uppercase
4075     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4076     #[inline]
4077     pub fn to_ascii_uppercase(&self) -> u8 {
4078         // Unset the fith bit if this is a lowercase letter
4079         *self & !((self.is_ascii_lowercase() as u8) << 5)
4080     }
4081
4082     /// Makes a copy of the value in its ASCII lower case equivalent.
4083     ///
4084     /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
4085     /// but non-ASCII letters are unchanged.
4086     ///
4087     /// To lowercase the value in-place, use [`make_ascii_lowercase`].
4088     ///
4089     /// # Examples
4090     ///
4091     /// ```
4092     /// let uppercase_a = 65u8;
4093     ///
4094     /// assert_eq!(97, uppercase_a.to_ascii_lowercase());
4095     /// ```
4096     ///
4097     /// [`make_ascii_lowercase`]: #method.make_ascii_lowercase
4098     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4099     #[inline]
4100     pub fn to_ascii_lowercase(&self) -> u8 {
4101         // Set the fith bit if this is an uppercase letter
4102         *self | ((self.is_ascii_uppercase() as u8) << 5)
4103     }
4104
4105     /// Checks that two values are an ASCII case-insensitive match.
4106     ///
4107     /// This is equivalent to `to_ascii_lowercase(a) == to_ascii_lowercase(b)`.
4108     ///
4109     /// # Examples
4110     ///
4111     /// ```
4112     /// let lowercase_a = 97u8;
4113     /// let uppercase_a = 65u8;
4114     ///
4115     /// assert!(lowercase_a.eq_ignore_ascii_case(&uppercase_a));
4116     /// ```
4117     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4118     #[inline]
4119     pub fn eq_ignore_ascii_case(&self, other: &u8) -> bool {
4120         self.to_ascii_lowercase() == other.to_ascii_lowercase()
4121     }
4122
4123     /// Converts this value to its ASCII upper case equivalent in-place.
4124     ///
4125     /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
4126     /// but non-ASCII letters are unchanged.
4127     ///
4128     /// To return a new uppercased value without modifying the existing one, use
4129     /// [`to_ascii_uppercase`].
4130     ///
4131     /// # Examples
4132     ///
4133     /// ```
4134     /// let mut byte = b'a';
4135     ///
4136     /// byte.make_ascii_uppercase();
4137     ///
4138     /// assert_eq!(b'A', byte);
4139     /// ```
4140     ///
4141     /// [`to_ascii_uppercase`]: #method.to_ascii_uppercase
4142     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4143     #[inline]
4144     pub fn make_ascii_uppercase(&mut self) {
4145         *self = self.to_ascii_uppercase();
4146     }
4147
4148     /// Converts this value to its ASCII lower case equivalent in-place.
4149     ///
4150     /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
4151     /// but non-ASCII letters are unchanged.
4152     ///
4153     /// To return a new lowercased value without modifying the existing one, use
4154     /// [`to_ascii_lowercase`].
4155     ///
4156     /// # Examples
4157     ///
4158     /// ```
4159     /// let mut byte = b'A';
4160     ///
4161     /// byte.make_ascii_lowercase();
4162     ///
4163     /// assert_eq!(b'a', byte);
4164     /// ```
4165     ///
4166     /// [`to_ascii_lowercase`]: #method.to_ascii_lowercase
4167     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4168     #[inline]
4169     pub fn make_ascii_lowercase(&mut self) {
4170         *self = self.to_ascii_lowercase();
4171     }
4172
4173     /// Checks if the value is an ASCII alphabetic character:
4174     ///
4175     /// - U+0041 'A' ... U+005A 'Z', or
4176     /// - U+0061 'a' ... U+007A 'z'.
4177     ///
4178     /// # Examples
4179     ///
4180     /// ```
4181     /// let uppercase_a = b'A';
4182     /// let uppercase_g = b'G';
4183     /// let a = b'a';
4184     /// let g = b'g';
4185     /// let zero = b'0';
4186     /// let percent = b'%';
4187     /// let space = b' ';
4188     /// let lf = b'\n';
4189     /// let esc = 0x1b_u8;
4190     ///
4191     /// assert!(uppercase_a.is_ascii_alphabetic());
4192     /// assert!(uppercase_g.is_ascii_alphabetic());
4193     /// assert!(a.is_ascii_alphabetic());
4194     /// assert!(g.is_ascii_alphabetic());
4195     /// assert!(!zero.is_ascii_alphabetic());
4196     /// assert!(!percent.is_ascii_alphabetic());
4197     /// assert!(!space.is_ascii_alphabetic());
4198     /// assert!(!lf.is_ascii_alphabetic());
4199     /// assert!(!esc.is_ascii_alphabetic());
4200     /// ```
4201     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4202     #[inline]
4203     pub fn is_ascii_alphabetic(&self) -> bool {
4204         match *self {
4205             b'A'..=b'Z' | b'a'..=b'z' => true,
4206             _ => false
4207         }
4208     }
4209
4210     /// Checks if the value is an ASCII uppercase character:
4211     /// U+0041 'A' ... U+005A 'Z'.
4212     ///
4213     /// # Examples
4214     ///
4215     /// ```
4216     /// let uppercase_a = b'A';
4217     /// let uppercase_g = b'G';
4218     /// let a = b'a';
4219     /// let g = b'g';
4220     /// let zero = b'0';
4221     /// let percent = b'%';
4222     /// let space = b' ';
4223     /// let lf = b'\n';
4224     /// let esc = 0x1b_u8;
4225     ///
4226     /// assert!(uppercase_a.is_ascii_uppercase());
4227     /// assert!(uppercase_g.is_ascii_uppercase());
4228     /// assert!(!a.is_ascii_uppercase());
4229     /// assert!(!g.is_ascii_uppercase());
4230     /// assert!(!zero.is_ascii_uppercase());
4231     /// assert!(!percent.is_ascii_uppercase());
4232     /// assert!(!space.is_ascii_uppercase());
4233     /// assert!(!lf.is_ascii_uppercase());
4234     /// assert!(!esc.is_ascii_uppercase());
4235     /// ```
4236     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4237     #[inline]
4238     pub fn is_ascii_uppercase(&self) -> bool {
4239         match *self {
4240             b'A'..=b'Z' => true,
4241             _ => false
4242         }
4243     }
4244
4245     /// Checks if the value is an ASCII lowercase character:
4246     /// U+0061 'a' ... U+007A 'z'.
4247     ///
4248     /// # Examples
4249     ///
4250     /// ```
4251     /// let uppercase_a = b'A';
4252     /// let uppercase_g = b'G';
4253     /// let a = b'a';
4254     /// let g = b'g';
4255     /// let zero = b'0';
4256     /// let percent = b'%';
4257     /// let space = b' ';
4258     /// let lf = b'\n';
4259     /// let esc = 0x1b_u8;
4260     ///
4261     /// assert!(!uppercase_a.is_ascii_lowercase());
4262     /// assert!(!uppercase_g.is_ascii_lowercase());
4263     /// assert!(a.is_ascii_lowercase());
4264     /// assert!(g.is_ascii_lowercase());
4265     /// assert!(!zero.is_ascii_lowercase());
4266     /// assert!(!percent.is_ascii_lowercase());
4267     /// assert!(!space.is_ascii_lowercase());
4268     /// assert!(!lf.is_ascii_lowercase());
4269     /// assert!(!esc.is_ascii_lowercase());
4270     /// ```
4271     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4272     #[inline]
4273     pub fn is_ascii_lowercase(&self) -> bool {
4274         match *self {
4275             b'a'..=b'z' => true,
4276             _ => false
4277         }
4278     }
4279
4280     /// Checks if the value is an ASCII alphanumeric character:
4281     ///
4282     /// - U+0041 'A' ... U+005A 'Z', or
4283     /// - U+0061 'a' ... U+007A 'z', or
4284     /// - U+0030 '0' ... U+0039 '9'.
4285     ///
4286     /// # Examples
4287     ///
4288     /// ```
4289     /// let uppercase_a = b'A';
4290     /// let uppercase_g = b'G';
4291     /// let a = b'a';
4292     /// let g = b'g';
4293     /// let zero = b'0';
4294     /// let percent = b'%';
4295     /// let space = b' ';
4296     /// let lf = b'\n';
4297     /// let esc = 0x1b_u8;
4298     ///
4299     /// assert!(uppercase_a.is_ascii_alphanumeric());
4300     /// assert!(uppercase_g.is_ascii_alphanumeric());
4301     /// assert!(a.is_ascii_alphanumeric());
4302     /// assert!(g.is_ascii_alphanumeric());
4303     /// assert!(zero.is_ascii_alphanumeric());
4304     /// assert!(!percent.is_ascii_alphanumeric());
4305     /// assert!(!space.is_ascii_alphanumeric());
4306     /// assert!(!lf.is_ascii_alphanumeric());
4307     /// assert!(!esc.is_ascii_alphanumeric());
4308     /// ```
4309     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4310     #[inline]
4311     pub fn is_ascii_alphanumeric(&self) -> bool {
4312         match *self {
4313             b'0'..=b'9' | b'A'..=b'Z' | b'a'..=b'z' => true,
4314             _ => false
4315         }
4316     }
4317
4318     /// Checks if the value is an ASCII decimal digit:
4319     /// U+0030 '0' ... U+0039 '9'.
4320     ///
4321     /// # Examples
4322     ///
4323     /// ```
4324     /// let uppercase_a = b'A';
4325     /// let uppercase_g = b'G';
4326     /// let a = b'a';
4327     /// let g = b'g';
4328     /// let zero = b'0';
4329     /// let percent = b'%';
4330     /// let space = b' ';
4331     /// let lf = b'\n';
4332     /// let esc = 0x1b_u8;
4333     ///
4334     /// assert!(!uppercase_a.is_ascii_digit());
4335     /// assert!(!uppercase_g.is_ascii_digit());
4336     /// assert!(!a.is_ascii_digit());
4337     /// assert!(!g.is_ascii_digit());
4338     /// assert!(zero.is_ascii_digit());
4339     /// assert!(!percent.is_ascii_digit());
4340     /// assert!(!space.is_ascii_digit());
4341     /// assert!(!lf.is_ascii_digit());
4342     /// assert!(!esc.is_ascii_digit());
4343     /// ```
4344     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4345     #[inline]
4346     pub fn is_ascii_digit(&self) -> bool {
4347         match *self {
4348             b'0'..=b'9' => true,
4349             _ => false
4350         }
4351     }
4352
4353     /// Checks if the value is an ASCII hexadecimal digit:
4354     ///
4355     /// - U+0030 '0' ... U+0039 '9', or
4356     /// - U+0041 'A' ... U+0046 'F', or
4357     /// - U+0061 'a' ... U+0066 'f'.
4358     ///
4359     /// # Examples
4360     ///
4361     /// ```
4362     /// let uppercase_a = b'A';
4363     /// let uppercase_g = b'G';
4364     /// let a = b'a';
4365     /// let g = b'g';
4366     /// let zero = b'0';
4367     /// let percent = b'%';
4368     /// let space = b' ';
4369     /// let lf = b'\n';
4370     /// let esc = 0x1b_u8;
4371     ///
4372     /// assert!(uppercase_a.is_ascii_hexdigit());
4373     /// assert!(!uppercase_g.is_ascii_hexdigit());
4374     /// assert!(a.is_ascii_hexdigit());
4375     /// assert!(!g.is_ascii_hexdigit());
4376     /// assert!(zero.is_ascii_hexdigit());
4377     /// assert!(!percent.is_ascii_hexdigit());
4378     /// assert!(!space.is_ascii_hexdigit());
4379     /// assert!(!lf.is_ascii_hexdigit());
4380     /// assert!(!esc.is_ascii_hexdigit());
4381     /// ```
4382     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4383     #[inline]
4384     pub fn is_ascii_hexdigit(&self) -> bool {
4385         match *self {
4386             b'0'..=b'9' | b'A'..=b'F' | b'a'..=b'f' => true,
4387             _ => false
4388         }
4389     }
4390
4391     /// Checks if the value is an ASCII punctuation character:
4392     ///
4393     /// - U+0021 ... U+002F `! " # $ % & ' ( ) * + , - . /`, or
4394     /// - U+003A ... U+0040 `: ; < = > ? @`, or
4395     /// - U+005B ... U+0060 ``[ \ ] ^ _ ` ``, or
4396     /// - U+007B ... U+007E `{ | } ~`
4397     ///
4398     /// # Examples
4399     ///
4400     /// ```
4401     /// let uppercase_a = b'A';
4402     /// let uppercase_g = b'G';
4403     /// let a = b'a';
4404     /// let g = b'g';
4405     /// let zero = b'0';
4406     /// let percent = b'%';
4407     /// let space = b' ';
4408     /// let lf = b'\n';
4409     /// let esc = 0x1b_u8;
4410     ///
4411     /// assert!(!uppercase_a.is_ascii_punctuation());
4412     /// assert!(!uppercase_g.is_ascii_punctuation());
4413     /// assert!(!a.is_ascii_punctuation());
4414     /// assert!(!g.is_ascii_punctuation());
4415     /// assert!(!zero.is_ascii_punctuation());
4416     /// assert!(percent.is_ascii_punctuation());
4417     /// assert!(!space.is_ascii_punctuation());
4418     /// assert!(!lf.is_ascii_punctuation());
4419     /// assert!(!esc.is_ascii_punctuation());
4420     /// ```
4421     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4422     #[inline]
4423     pub fn is_ascii_punctuation(&self) -> bool {
4424         match *self {
4425             b'!'..=b'/' | b':'..=b'@' | b'['..=b'`' | b'{'..=b'~' => true,
4426             _ => false
4427         }
4428     }
4429
4430     /// Checks if the value is an ASCII graphic character:
4431     /// U+0021 '!' ... U+007E '~'.
4432     ///
4433     /// # Examples
4434     ///
4435     /// ```
4436     /// let uppercase_a = b'A';
4437     /// let uppercase_g = b'G';
4438     /// let a = b'a';
4439     /// let g = b'g';
4440     /// let zero = b'0';
4441     /// let percent = b'%';
4442     /// let space = b' ';
4443     /// let lf = b'\n';
4444     /// let esc = 0x1b_u8;
4445     ///
4446     /// assert!(uppercase_a.is_ascii_graphic());
4447     /// assert!(uppercase_g.is_ascii_graphic());
4448     /// assert!(a.is_ascii_graphic());
4449     /// assert!(g.is_ascii_graphic());
4450     /// assert!(zero.is_ascii_graphic());
4451     /// assert!(percent.is_ascii_graphic());
4452     /// assert!(!space.is_ascii_graphic());
4453     /// assert!(!lf.is_ascii_graphic());
4454     /// assert!(!esc.is_ascii_graphic());
4455     /// ```
4456     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4457     #[inline]
4458     pub fn is_ascii_graphic(&self) -> bool {
4459         match *self {
4460             b'!'..=b'~' => true,
4461             _ => false
4462         }
4463     }
4464
4465     /// Checks if the value is an ASCII whitespace character:
4466     /// U+0020 SPACE, U+0009 HORIZONTAL TAB, U+000A LINE FEED,
4467     /// U+000C FORM FEED, or U+000D CARRIAGE RETURN.
4468     ///
4469     /// Rust uses the WhatWG Infra Standard's [definition of ASCII
4470     /// whitespace][infra-aw]. There are several other definitions in
4471     /// wide use. For instance, [the POSIX locale][pct] includes
4472     /// U+000B VERTICAL TAB as well as all the above characters,
4473     /// but—from the very same specification—[the default rule for
4474     /// "field splitting" in the Bourne shell][bfs] considers *only*
4475     /// SPACE, HORIZONTAL TAB, and LINE FEED as whitespace.
4476     ///
4477     /// If you are writing a program that will process an existing
4478     /// file format, check what that format's definition of whitespace is
4479     /// before using this function.
4480     ///
4481     /// [infra-aw]: https://infra.spec.whatwg.org/#ascii-whitespace
4482     /// [pct]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html#tag_07_03_01
4483     /// [bfs]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_05
4484     ///
4485     /// # Examples
4486     ///
4487     /// ```
4488     /// let uppercase_a = b'A';
4489     /// let uppercase_g = b'G';
4490     /// let a = b'a';
4491     /// let g = b'g';
4492     /// let zero = b'0';
4493     /// let percent = b'%';
4494     /// let space = b' ';
4495     /// let lf = b'\n';
4496     /// let esc = 0x1b_u8;
4497     ///
4498     /// assert!(!uppercase_a.is_ascii_whitespace());
4499     /// assert!(!uppercase_g.is_ascii_whitespace());
4500     /// assert!(!a.is_ascii_whitespace());
4501     /// assert!(!g.is_ascii_whitespace());
4502     /// assert!(!zero.is_ascii_whitespace());
4503     /// assert!(!percent.is_ascii_whitespace());
4504     /// assert!(space.is_ascii_whitespace());
4505     /// assert!(lf.is_ascii_whitespace());
4506     /// assert!(!esc.is_ascii_whitespace());
4507     /// ```
4508     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4509     #[inline]
4510     pub fn is_ascii_whitespace(&self) -> bool {
4511         match *self {
4512             b'\t' | b'\n' | b'\x0C' | b'\r' | b' ' => true,
4513             _ => false
4514         }
4515     }
4516
4517     /// Checks if the value is an ASCII control character:
4518     /// U+0000 NUL ... U+001F UNIT SEPARATOR, or U+007F DELETE.
4519     /// Note that most ASCII whitespace characters are control
4520     /// characters, but SPACE is not.
4521     ///
4522     /// # Examples
4523     ///
4524     /// ```
4525     /// let uppercase_a = b'A';
4526     /// let uppercase_g = b'G';
4527     /// let a = b'a';
4528     /// let g = b'g';
4529     /// let zero = b'0';
4530     /// let percent = b'%';
4531     /// let space = b' ';
4532     /// let lf = b'\n';
4533     /// let esc = 0x1b_u8;
4534     ///
4535     /// assert!(!uppercase_a.is_ascii_control());
4536     /// assert!(!uppercase_g.is_ascii_control());
4537     /// assert!(!a.is_ascii_control());
4538     /// assert!(!g.is_ascii_control());
4539     /// assert!(!zero.is_ascii_control());
4540     /// assert!(!percent.is_ascii_control());
4541     /// assert!(!space.is_ascii_control());
4542     /// assert!(lf.is_ascii_control());
4543     /// assert!(esc.is_ascii_control());
4544     /// ```
4545     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4546     #[inline]
4547     pub fn is_ascii_control(&self) -> bool {
4548         match *self {
4549             b'\0'..=b'\x1F' | b'\x7F' => true,
4550             _ => false
4551         }
4552     }
4553 }
4554
4555 #[lang = "u16"]
4556 impl u16 {
4557     uint_impl! { u16, u16, 16, 65535, "", "", 4, "0xa003", "0x3a", "0x1234", "0x3412", "0x2c48",
4558         "[0x34, 0x12]", "[0x12, 0x34]", "", "" }
4559 }
4560
4561 #[lang = "u32"]
4562 impl u32 {
4563     uint_impl! { u32, u32, 32, 4294967295, "", "", 8, "0x10000b3", "0xb301", "0x12345678",
4564         "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]", "[0x12, 0x34, 0x56, 0x78]", "", "" }
4565 }
4566
4567 #[lang = "u64"]
4568 impl u64 {
4569     uint_impl! { u64, u64, 64, 18446744073709551615, "", "", 12, "0xaa00000000006e1", "0x6e10aa",
4570         "0x1234567890123456", "0x5634129078563412", "0x6a2c48091e6a2c48",
4571         "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
4572         "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
4573         "", ""}
4574 }
4575
4576 #[lang = "u128"]
4577 impl u128 {
4578     uint_impl! { u128, u128, 128, 340282366920938463463374607431768211455, "", "", 16,
4579         "0x13f40000000000000000000000004f76", "0x4f7613f4", "0x12345678901234567890123456789012",
4580         "0x12907856341290785634129078563412", "0x48091e6a2c48091e6a2c48091e6a2c48",
4581         "[0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, \
4582           0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
4583         "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56, \
4584           0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12]",
4585          "", ""}
4586 }
4587
4588 #[cfg(target_pointer_width = "16")]
4589 #[lang = "usize"]
4590 impl usize {
4591     uint_impl! { usize, u16, 16, 65535, "", "", 4, "0xa003", "0x3a", "0x1234", "0x3412", "0x2c48",
4592         "[0x34, 0x12]", "[0x12, 0x34]",
4593         usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
4594 }
4595 #[cfg(target_pointer_width = "32")]
4596 #[lang = "usize"]
4597 impl usize {
4598     uint_impl! { usize, u32, 32, 4294967295, "", "", 8, "0x10000b3", "0xb301", "0x12345678",
4599         "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]", "[0x12, 0x34, 0x56, 0x78]",
4600         usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
4601 }
4602
4603 #[cfg(target_pointer_width = "64")]
4604 #[lang = "usize"]
4605 impl usize {
4606     uint_impl! { usize, u64, 64, 18446744073709551615, "", "", 12, "0xaa00000000006e1", "0x6e10aa",
4607         "0x1234567890123456", "0x5634129078563412", "0x6a2c48091e6a2c48",
4608         "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
4609          "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
4610         usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
4611 }
4612
4613 /// A classification of floating point numbers.
4614 ///
4615 /// This `enum` is used as the return type for [`f32::classify`] and [`f64::classify`]. See
4616 /// their documentation for more.
4617 ///
4618 /// [`f32::classify`]: ../../std/primitive.f32.html#method.classify
4619 /// [`f64::classify`]: ../../std/primitive.f64.html#method.classify
4620 ///
4621 /// # Examples
4622 ///
4623 /// ```
4624 /// use std::num::FpCategory;
4625 /// use std::f32;
4626 ///
4627 /// let num = 12.4_f32;
4628 /// let inf = f32::INFINITY;
4629 /// let zero = 0f32;
4630 /// let sub: f32 = 1.1754942e-38;
4631 /// let nan = f32::NAN;
4632 ///
4633 /// assert_eq!(num.classify(), FpCategory::Normal);
4634 /// assert_eq!(inf.classify(), FpCategory::Infinite);
4635 /// assert_eq!(zero.classify(), FpCategory::Zero);
4636 /// assert_eq!(nan.classify(), FpCategory::Nan);
4637 /// assert_eq!(sub.classify(), FpCategory::Subnormal);
4638 /// ```
4639 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
4640 #[stable(feature = "rust1", since = "1.0.0")]
4641 pub enum FpCategory {
4642     /// "Not a Number", often obtained by dividing by zero.
4643     #[stable(feature = "rust1", since = "1.0.0")]
4644     Nan,
4645
4646     /// Positive or negative infinity.
4647     #[stable(feature = "rust1", since = "1.0.0")]
4648     Infinite,
4649
4650     /// Positive or negative zero.
4651     #[stable(feature = "rust1", since = "1.0.0")]
4652     Zero,
4653
4654     /// De-normalized floating point representation (less precise than `Normal`).
4655     #[stable(feature = "rust1", since = "1.0.0")]
4656     Subnormal,
4657
4658     /// A regular floating point number.
4659     #[stable(feature = "rust1", since = "1.0.0")]
4660     Normal,
4661 }
4662
4663 macro_rules! from_str_radix_int_impl {
4664     ($($t:ty)*) => {$(
4665         #[stable(feature = "rust1", since = "1.0.0")]
4666         impl FromStr for $t {
4667             type Err = ParseIntError;
4668             fn from_str(src: &str) -> Result<Self, ParseIntError> {
4669                 from_str_radix(src, 10)
4670             }
4671         }
4672     )*}
4673 }
4674 from_str_radix_int_impl! { isize i8 i16 i32 i64 i128 usize u8 u16 u32 u64 u128 }
4675
4676 /// The error type returned when a checked integral type conversion fails.
4677 #[stable(feature = "try_from", since = "1.34.0")]
4678 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
4679 pub struct TryFromIntError(());
4680
4681 impl TryFromIntError {
4682     #[unstable(feature = "int_error_internals",
4683                reason = "available through Error trait and this method should \
4684                          not be exposed publicly",
4685                issue = "0")]
4686     #[doc(hidden)]
4687     pub fn __description(&self) -> &str {
4688         "out of range integral type conversion attempted"
4689     }
4690 }
4691
4692 #[stable(feature = "try_from", since = "1.34.0")]
4693 impl fmt::Display for TryFromIntError {
4694     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
4695         self.__description().fmt(fmt)
4696     }
4697 }
4698
4699 #[stable(feature = "try_from", since = "1.34.0")]
4700 impl From<Infallible> for TryFromIntError {
4701     fn from(x: Infallible) -> TryFromIntError {
4702         match x {}
4703     }
4704 }
4705
4706 #[unstable(feature = "never_type", issue = "35121")]
4707 impl From<!> for TryFromIntError {
4708     fn from(never: !) -> TryFromIntError {
4709         // Match rather than coerce to make sure that code like
4710         // `From<Infallible> for TryFromIntError` above will keep working
4711         // when `Infallible` becomes an alias to `!`.
4712         match never {}
4713     }
4714 }
4715
4716 // no possible bounds violation
4717 macro_rules! try_from_unbounded {
4718     ($source:ty, $($target:ty),*) => {$(
4719         #[stable(feature = "try_from", since = "1.34.0")]
4720         impl TryFrom<$source> for $target {
4721             type Error = TryFromIntError;
4722
4723             /// Try to create the target number type from a source
4724             /// number type. This returns an error if the source value
4725             /// is outside of the range of the target type.
4726             #[inline]
4727             fn try_from(value: $source) -> Result<Self, Self::Error> {
4728                 Ok(value as $target)
4729             }
4730         }
4731     )*}
4732 }
4733
4734 // only negative bounds
4735 macro_rules! try_from_lower_bounded {
4736     ($source:ty, $($target:ty),*) => {$(
4737         #[stable(feature = "try_from", since = "1.34.0")]
4738         impl TryFrom<$source> for $target {
4739             type Error = TryFromIntError;
4740
4741             /// Try to create the target number type from a source
4742             /// number type. This returns an error if the source value
4743             /// is outside of the range of the target type.
4744             #[inline]
4745             fn try_from(u: $source) -> Result<$target, TryFromIntError> {
4746                 if u >= 0 {
4747                     Ok(u as $target)
4748                 } else {
4749                     Err(TryFromIntError(()))
4750                 }
4751             }
4752         }
4753     )*}
4754 }
4755
4756 // unsigned to signed (only positive bound)
4757 macro_rules! try_from_upper_bounded {
4758     ($source:ty, $($target:ty),*) => {$(
4759         #[stable(feature = "try_from", since = "1.34.0")]
4760         impl TryFrom<$source> for $target {
4761             type Error = TryFromIntError;
4762
4763             /// Try to create the target number type from a source
4764             /// number type. This returns an error if the source value
4765             /// is outside of the range of the target type.
4766             #[inline]
4767             fn try_from(u: $source) -> Result<$target, TryFromIntError> {
4768                 if u > (<$target>::max_value() as $source) {
4769                     Err(TryFromIntError(()))
4770                 } else {
4771                     Ok(u as $target)
4772                 }
4773             }
4774         }
4775     )*}
4776 }
4777
4778 // all other cases
4779 macro_rules! try_from_both_bounded {
4780     ($source:ty, $($target:ty),*) => {$(
4781         #[stable(feature = "try_from", since = "1.34.0")]
4782         impl TryFrom<$source> for $target {
4783             type Error = TryFromIntError;
4784
4785             /// Try to create the target number type from a source
4786             /// number type. This returns an error if the source value
4787             /// is outside of the range of the target type.
4788             #[inline]
4789             fn try_from(u: $source) -> Result<$target, TryFromIntError> {
4790                 let min = <$target>::min_value() as $source;
4791                 let max = <$target>::max_value() as $source;
4792                 if u < min || u > max {
4793                     Err(TryFromIntError(()))
4794                 } else {
4795                     Ok(u as $target)
4796                 }
4797             }
4798         }
4799     )*}
4800 }
4801
4802 macro_rules! rev {
4803     ($mac:ident, $source:ty, $($target:ty),*) => {$(
4804         $mac!($target, $source);
4805     )*}
4806 }
4807
4808 // intra-sign conversions
4809 try_from_upper_bounded!(u16, u8);
4810 try_from_upper_bounded!(u32, u16, u8);
4811 try_from_upper_bounded!(u64, u32, u16, u8);
4812 try_from_upper_bounded!(u128, u64, u32, u16, u8);
4813
4814 try_from_both_bounded!(i16, i8);
4815 try_from_both_bounded!(i32, i16, i8);
4816 try_from_both_bounded!(i64, i32, i16, i8);
4817 try_from_both_bounded!(i128, i64, i32, i16, i8);
4818
4819 // unsigned-to-signed
4820 try_from_upper_bounded!(u8, i8);
4821 try_from_upper_bounded!(u16, i8, i16);
4822 try_from_upper_bounded!(u32, i8, i16, i32);
4823 try_from_upper_bounded!(u64, i8, i16, i32, i64);
4824 try_from_upper_bounded!(u128, i8, i16, i32, i64, i128);
4825
4826 // signed-to-unsigned
4827 try_from_lower_bounded!(i8, u8, u16, u32, u64, u128);
4828 try_from_lower_bounded!(i16, u16, u32, u64, u128);
4829 try_from_lower_bounded!(i32, u32, u64, u128);
4830 try_from_lower_bounded!(i64, u64, u128);
4831 try_from_lower_bounded!(i128, u128);
4832 try_from_both_bounded!(i16, u8);
4833 try_from_both_bounded!(i32, u16, u8);
4834 try_from_both_bounded!(i64, u32, u16, u8);
4835 try_from_both_bounded!(i128, u64, u32, u16, u8);
4836
4837 // usize/isize
4838 try_from_upper_bounded!(usize, isize);
4839 try_from_lower_bounded!(isize, usize);
4840
4841 #[cfg(target_pointer_width = "16")]
4842 mod ptr_try_from_impls {
4843     use super::TryFromIntError;
4844     use crate::convert::TryFrom;
4845
4846     try_from_upper_bounded!(usize, u8);
4847     try_from_unbounded!(usize, u16, u32, u64, u128);
4848     try_from_upper_bounded!(usize, i8, i16);
4849     try_from_unbounded!(usize, i32, i64, i128);
4850
4851     try_from_both_bounded!(isize, u8);
4852     try_from_lower_bounded!(isize, u16, u32, u64, u128);
4853     try_from_both_bounded!(isize, i8);
4854     try_from_unbounded!(isize, i16, i32, i64, i128);
4855
4856     rev!(try_from_upper_bounded, usize, u32, u64, u128);
4857     rev!(try_from_lower_bounded, usize, i8, i16);
4858     rev!(try_from_both_bounded, usize, i32, i64, i128);
4859
4860     rev!(try_from_upper_bounded, isize, u16, u32, u64, u128);
4861     rev!(try_from_both_bounded, isize, i32, i64, i128);
4862 }
4863
4864 #[cfg(target_pointer_width = "32")]
4865 mod ptr_try_from_impls {
4866     use super::TryFromIntError;
4867     use crate::convert::TryFrom;
4868
4869     try_from_upper_bounded!(usize, u8, u16);
4870     try_from_unbounded!(usize, u32, u64, u128);
4871     try_from_upper_bounded!(usize, i8, i16, i32);
4872     try_from_unbounded!(usize, i64, i128);
4873
4874     try_from_both_bounded!(isize, u8, u16);
4875     try_from_lower_bounded!(isize, u32, u64, u128);
4876     try_from_both_bounded!(isize, i8, i16);
4877     try_from_unbounded!(isize, i32, i64, i128);
4878
4879     rev!(try_from_unbounded, usize, u32);
4880     rev!(try_from_upper_bounded, usize, u64, u128);
4881     rev!(try_from_lower_bounded, usize, i8, i16, i32);
4882     rev!(try_from_both_bounded, usize, i64, i128);
4883
4884     rev!(try_from_unbounded, isize, u16);
4885     rev!(try_from_upper_bounded, isize, u32, u64, u128);
4886     rev!(try_from_unbounded, isize, i32);
4887     rev!(try_from_both_bounded, isize, i64, i128);
4888 }
4889
4890 #[cfg(target_pointer_width = "64")]
4891 mod ptr_try_from_impls {
4892     use super::TryFromIntError;
4893     use crate::convert::TryFrom;
4894
4895     try_from_upper_bounded!(usize, u8, u16, u32);
4896     try_from_unbounded!(usize, u64, u128);
4897     try_from_upper_bounded!(usize, i8, i16, i32, i64);
4898     try_from_unbounded!(usize, i128);
4899
4900     try_from_both_bounded!(isize, u8, u16, u32);
4901     try_from_lower_bounded!(isize, u64, u128);
4902     try_from_both_bounded!(isize, i8, i16, i32);
4903     try_from_unbounded!(isize, i64, i128);
4904
4905     rev!(try_from_unbounded, usize, u32, u64);
4906     rev!(try_from_upper_bounded, usize, u128);
4907     rev!(try_from_lower_bounded, usize, i8, i16, i32, i64);
4908     rev!(try_from_both_bounded, usize, i128);
4909
4910     rev!(try_from_unbounded, isize, u16, u32);
4911     rev!(try_from_upper_bounded, isize, u64, u128);
4912     rev!(try_from_unbounded, isize, i32, i64);
4913     rev!(try_from_both_bounded, isize, i128);
4914 }
4915
4916 #[doc(hidden)]
4917 trait FromStrRadixHelper: PartialOrd + Copy {
4918     fn min_value() -> Self;
4919     fn max_value() -> Self;
4920     fn from_u32(u: u32) -> Self;
4921     fn checked_mul(&self, other: u32) -> Option<Self>;
4922     fn checked_sub(&self, other: u32) -> Option<Self>;
4923     fn checked_add(&self, other: u32) -> Option<Self>;
4924 }
4925
4926 macro_rules! doit {
4927     ($($t:ty)*) => ($(impl FromStrRadixHelper for $t {
4928         #[inline]
4929         fn min_value() -> Self { Self::min_value() }
4930         #[inline]
4931         fn max_value() -> Self { Self::max_value() }
4932         #[inline]
4933         fn from_u32(u: u32) -> Self { u as Self }
4934         #[inline]
4935         fn checked_mul(&self, other: u32) -> Option<Self> {
4936             Self::checked_mul(*self, other as Self)
4937         }
4938         #[inline]
4939         fn checked_sub(&self, other: u32) -> Option<Self> {
4940             Self::checked_sub(*self, other as Self)
4941         }
4942         #[inline]
4943         fn checked_add(&self, other: u32) -> Option<Self> {
4944             Self::checked_add(*self, other as Self)
4945         }
4946     })*)
4947 }
4948 doit! { i8 i16 i32 i64 i128 isize u8 u16 u32 u64 u128 usize }
4949
4950 fn from_str_radix<T: FromStrRadixHelper>(src: &str, radix: u32) -> Result<T, ParseIntError> {
4951     use self::IntErrorKind::*;
4952     use self::ParseIntError as PIE;
4953
4954     assert!(radix >= 2 && radix <= 36,
4955            "from_str_radix_int: must lie in the range `[2, 36]` - found {}",
4956            radix);
4957
4958     if src.is_empty() {
4959         return Err(PIE { kind: Empty });
4960     }
4961
4962     let is_signed_ty = T::from_u32(0) > T::min_value();
4963
4964     // all valid digits are ascii, so we will just iterate over the utf8 bytes
4965     // and cast them to chars. .to_digit() will safely return None for anything
4966     // other than a valid ascii digit for the given radix, including the first-byte
4967     // of multi-byte sequences
4968     let src = src.as_bytes();
4969
4970     let (is_positive, digits) = match src[0] {
4971         b'+' => (true, &src[1..]),
4972         b'-' if is_signed_ty => (false, &src[1..]),
4973         _ => (true, src),
4974     };
4975
4976     if digits.is_empty() {
4977         return Err(PIE { kind: Empty });
4978     }
4979
4980     let mut result = T::from_u32(0);
4981     if is_positive {
4982         // The number is positive
4983         for &c in digits {
4984             let x = match (c as char).to_digit(radix) {
4985                 Some(x) => x,
4986                 None => return Err(PIE { kind: InvalidDigit }),
4987             };
4988             result = match result.checked_mul(radix) {
4989                 Some(result) => result,
4990                 None => return Err(PIE { kind: Overflow }),
4991             };
4992             result = match result.checked_add(x) {
4993                 Some(result) => result,
4994                 None => return Err(PIE { kind: Overflow }),
4995             };
4996         }
4997     } else {
4998         // The number is negative
4999         for &c in digits {
5000             let x = match (c as char).to_digit(radix) {
5001                 Some(x) => x,
5002                 None => return Err(PIE { kind: InvalidDigit }),
5003             };
5004             result = match result.checked_mul(radix) {
5005                 Some(result) => result,
5006                 None => return Err(PIE { kind: Underflow }),
5007             };
5008             result = match result.checked_sub(x) {
5009                 Some(result) => result,
5010                 None => return Err(PIE { kind: Underflow }),
5011             };
5012         }
5013     }
5014     Ok(result)
5015 }
5016
5017 /// An error which can be returned when parsing an integer.
5018 ///
5019 /// This error is used as the error type for the `from_str_radix()` functions
5020 /// on the primitive integer types, such as [`i8::from_str_radix`].
5021 ///
5022 /// # Potential causes
5023 ///
5024 /// Among other causes, `ParseIntError` can be thrown because of leading or trailing whitespace
5025 /// in the string e.g., when it is obtained from the standard input.
5026 /// Using the [`str.trim()`] method ensures that no whitespace remains before parsing.
5027 ///
5028 /// [`str.trim()`]: ../../std/primitive.str.html#method.trim
5029 /// [`i8::from_str_radix`]: ../../std/primitive.i8.html#method.from_str_radix
5030 #[derive(Debug, Clone, PartialEq, Eq)]
5031 #[stable(feature = "rust1", since = "1.0.0")]
5032 pub struct ParseIntError {
5033     kind: IntErrorKind,
5034 }
5035
5036 /// Enum to store the various types of errors that can cause parsing an integer to fail.
5037 #[unstable(feature = "int_error_matching",
5038            reason = "it can be useful to match errors when making error messages \
5039                      for integer parsing",
5040            issue = "22639")]
5041 #[derive(Debug, Clone, PartialEq, Eq)]
5042 #[non_exhaustive]
5043 pub enum IntErrorKind {
5044     /// Value being parsed is empty.
5045     ///
5046     /// Among other causes, this variant will be constructed when parsing an empty string.
5047     Empty,
5048     /// Contains an invalid digit.
5049     ///
5050     /// Among other causes, this variant will be constructed when parsing a string that
5051     /// contains a letter.
5052     InvalidDigit,
5053     /// Integer is too large to store in target integer type.
5054     Overflow,
5055     /// Integer is too small to store in target integer type.
5056     Underflow,
5057     /// Value was Zero
5058     ///
5059     /// This variant will be emitted when the parsing string has a value of zero, which
5060     /// would be illegal for non-zero types.
5061     Zero,
5062 }
5063
5064 impl ParseIntError {
5065     /// Outputs the detailed cause of parsing an integer failing.
5066     #[unstable(feature = "int_error_matching",
5067                reason = "it can be useful to match errors when making error messages \
5068                          for integer parsing",
5069                issue = "22639")]
5070     pub fn kind(&self) -> &IntErrorKind {
5071         &self.kind
5072     }
5073     #[unstable(feature = "int_error_internals",
5074                reason = "available through Error trait and this method should \
5075                          not be exposed publicly",
5076                issue = "0")]
5077     #[doc(hidden)]
5078     pub fn __description(&self) -> &str {
5079         match self.kind {
5080             IntErrorKind::Empty => "cannot parse integer from empty string",
5081             IntErrorKind::InvalidDigit => "invalid digit found in string",
5082             IntErrorKind::Overflow => "number too large to fit in target type",
5083             IntErrorKind::Underflow => "number too small to fit in target type",
5084             IntErrorKind::Zero => "number would be zero for non-zero type",
5085         }
5086     }
5087 }
5088
5089 #[stable(feature = "rust1", since = "1.0.0")]
5090 impl fmt::Display for ParseIntError {
5091     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
5092         self.__description().fmt(f)
5093     }
5094 }
5095
5096 #[stable(feature = "rust1", since = "1.0.0")]
5097 pub use crate::num::dec2flt::ParseFloatError;
5098
5099 // Conversion traits for primitive integer and float types
5100 // Conversions T -> T are covered by a blanket impl and therefore excluded
5101 // Some conversions from and to usize/isize are not implemented due to portability concerns
5102 macro_rules! impl_from {
5103     ($Small: ty, $Large: ty, #[$attr:meta], $doc: expr) => {
5104         #[$attr]
5105         #[doc = $doc]
5106         impl From<$Small> for $Large {
5107             #[inline]
5108             fn from(small: $Small) -> $Large {
5109                 small as $Large
5110             }
5111         }
5112     };
5113     ($Small: ty, $Large: ty, #[$attr:meta]) => {
5114         impl_from!($Small,
5115                    $Large,
5116                    #[$attr],
5117                    concat!("Converts `",
5118                            stringify!($Small),
5119                            "` to `",
5120                            stringify!($Large),
5121                            "` losslessly."));
5122     }
5123 }
5124
5125 macro_rules! impl_from_bool {
5126     ($target: ty, #[$attr:meta]) => {
5127         impl_from!(bool, $target, #[$attr], concat!("Converts a `bool` to a `",
5128             stringify!($target), "`. The resulting value is `0` for `false` and `1` for `true`
5129 values.
5130
5131 # Examples
5132
5133 ```
5134 assert_eq!(", stringify!($target), "::from(true), 1);
5135 assert_eq!(", stringify!($target), "::from(false), 0);
5136 ```"));
5137     };
5138 }
5139
5140 // Bool -> Any
5141 impl_from_bool! { u8, #[stable(feature = "from_bool", since = "1.28.0")] }
5142 impl_from_bool! { u16, #[stable(feature = "from_bool", since = "1.28.0")] }
5143 impl_from_bool! { u32, #[stable(feature = "from_bool", since = "1.28.0")] }
5144 impl_from_bool! { u64, #[stable(feature = "from_bool", since = "1.28.0")] }
5145 impl_from_bool! { u128, #[stable(feature = "from_bool", since = "1.28.0")] }
5146 impl_from_bool! { usize, #[stable(feature = "from_bool", since = "1.28.0")] }
5147 impl_from_bool! { i8, #[stable(feature = "from_bool", since = "1.28.0")] }
5148 impl_from_bool! { i16, #[stable(feature = "from_bool", since = "1.28.0")] }
5149 impl_from_bool! { i32, #[stable(feature = "from_bool", since = "1.28.0")] }
5150 impl_from_bool! { i64, #[stable(feature = "from_bool", since = "1.28.0")] }
5151 impl_from_bool! { i128, #[stable(feature = "from_bool", since = "1.28.0")] }
5152 impl_from_bool! { isize, #[stable(feature = "from_bool", since = "1.28.0")] }
5153
5154 // Unsigned -> Unsigned
5155 impl_from! { u8, u16, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5156 impl_from! { u8, u32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5157 impl_from! { u8, u64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5158 impl_from! { u8, u128, #[stable(feature = "i128", since = "1.26.0")] }
5159 impl_from! { u8, usize, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5160 impl_from! { u16, u32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5161 impl_from! { u16, u64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5162 impl_from! { u16, u128, #[stable(feature = "i128", since = "1.26.0")] }
5163 impl_from! { u32, u64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5164 impl_from! { u32, u128, #[stable(feature = "i128", since = "1.26.0")] }
5165 impl_from! { u64, u128, #[stable(feature = "i128", since = "1.26.0")] }
5166
5167 // Signed -> Signed
5168 impl_from! { i8, i16, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5169 impl_from! { i8, i32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5170 impl_from! { i8, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5171 impl_from! { i8, i128, #[stable(feature = "i128", since = "1.26.0")] }
5172 impl_from! { i8, isize, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5173 impl_from! { i16, i32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5174 impl_from! { i16, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5175 impl_from! { i16, i128, #[stable(feature = "i128", since = "1.26.0")] }
5176 impl_from! { i32, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5177 impl_from! { i32, i128, #[stable(feature = "i128", since = "1.26.0")] }
5178 impl_from! { i64, i128, #[stable(feature = "i128", since = "1.26.0")] }
5179
5180 // Unsigned -> Signed
5181 impl_from! { u8, i16, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5182 impl_from! { u8, i32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5183 impl_from! { u8, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5184 impl_from! { u8, i128, #[stable(feature = "i128", since = "1.26.0")] }
5185 impl_from! { u16, i32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5186 impl_from! { u16, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5187 impl_from! { u16, i128, #[stable(feature = "i128", since = "1.26.0")] }
5188 impl_from! { u32, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5189 impl_from! { u32, i128, #[stable(feature = "i128", since = "1.26.0")] }
5190 impl_from! { u64, i128, #[stable(feature = "i128", since = "1.26.0")] }
5191
5192 // The C99 standard defines bounds on INTPTR_MIN, INTPTR_MAX, and UINTPTR_MAX
5193 // which imply that pointer-sized integers must be at least 16 bits:
5194 // https://port70.net/~nsz/c/c99/n1256.html#7.18.2.4
5195 impl_from! { u16, usize, #[stable(feature = "lossless_iusize_conv", since = "1.26.0")] }
5196 impl_from! { u8, isize, #[stable(feature = "lossless_iusize_conv", since = "1.26.0")] }
5197 impl_from! { i16, isize, #[stable(feature = "lossless_iusize_conv", since = "1.26.0")] }
5198
5199 // RISC-V defines the possibility of a 128-bit address space (RV128).
5200
5201 // CHERI proposes 256-bit “capabilities”. Unclear if this would be relevant to usize/isize.
5202 // https://www.cl.cam.ac.uk/research/security/ctsrd/pdfs/20171017a-cheri-poster.pdf
5203 // http://www.csl.sri.com/users/neumann/2012resolve-cheri.pdf
5204
5205
5206 // Note: integers can only be represented with full precision in a float if
5207 // they fit in the significand, which is 24 bits in f32 and 53 bits in f64.
5208 // Lossy float conversions are not implemented at this time.
5209
5210 // Signed -> Float
5211 impl_from! { i8, f32, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
5212 impl_from! { i8, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
5213 impl_from! { i16, f32, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
5214 impl_from! { i16, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
5215 impl_from! { i32, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
5216
5217 // Unsigned -> Float
5218 impl_from! { u8, f32, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
5219 impl_from! { u8, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
5220 impl_from! { u16, f32, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
5221 impl_from! { u16, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
5222 impl_from! { u32, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
5223
5224 // Float -> Float
5225 impl_from! { f32, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }