src/libcore/num/mod.rs

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