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 let bytes = ", $swap_op, stringify!($SelfT), ".to_be_bytes();
1925 assert_eq!(bytes, ", $be_bytes, ");
1926 ```"),
1927             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
1928             #[rustc_const_unstable(feature = "const_int_conversion")]
1929             #[inline]
1930             pub const fn to_be_bytes(self) -> [u8; mem::size_of::<Self>()] {
1931                 self.to_be().to_ne_bytes()
1932             }
1933         }
1934
1935 doc_comment! {
1936             concat!("Return the memory representation of this integer as a byte array in
1937 little-endian byte order.
1938
1939 # Examples
1940
1941 ```
1942 let bytes = ", $swap_op, stringify!($SelfT), ".to_le_bytes();
1943 assert_eq!(bytes, ", $le_bytes, ");
1944 ```"),
1945             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
1946             #[rustc_const_unstable(feature = "const_int_conversion")]
1947             #[inline]
1948             pub const fn to_le_bytes(self) -> [u8; mem::size_of::<Self>()] {
1949                 self.to_le().to_ne_bytes()
1950             }
1951         }
1952
1953         doc_comment! {
1954             concat!("
1955 Return the memory representation of this integer as a byte array in
1956 native byte order.
1957
1958 As the target platform's native endianness is used, portable code
1959 should use [`to_be_bytes`] or [`to_le_bytes`], as appropriate,
1960 instead.
1961
1962 [`to_be_bytes`]: #method.to_be_bytes
1963 [`to_le_bytes`]: #method.to_le_bytes
1964
1965 # Examples
1966
1967 ```
1968 let bytes = ", $swap_op, stringify!($SelfT), ".to_ne_bytes();
1969 assert_eq!(bytes, if cfg!(target_endian = \"big\") {
1970         ", $be_bytes, "
1971     } else {
1972         ", $le_bytes, "
1973     });
1974 ```"),
1975             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
1976             #[rustc_const_unstable(feature = "const_int_conversion")]
1977             #[inline]
1978             pub const fn to_ne_bytes(self) -> [u8; mem::size_of::<Self>()] {
1979                 unsafe { mem::transmute(self) }
1980             }
1981         }
1982
1983 doc_comment! {
1984             concat!("Create an integer value from its representation as a byte array in
1985 big endian.
1986
1987 # Examples
1988
1989 ```
1990 let value = ", stringify!($SelfT), "::from_be_bytes(", $be_bytes, ");
1991 assert_eq!(value, ", $swap_op, ");
1992 ```"),
1993             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
1994             #[rustc_const_unstable(feature = "const_int_conversion")]
1995             #[inline]
1996             pub const fn from_be_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
1997                 Self::from_be(Self::from_ne_bytes(bytes))
1998             }
1999         }
2000
2001 doc_comment! {
2002             concat!("
2003 Create an integer value from its representation as a byte array in
2004 little endian.
2005
2006 # Examples
2007
2008 ```
2009 let value = ", stringify!($SelfT), "::from_le_bytes(", $le_bytes, ");
2010 assert_eq!(value, ", $swap_op, ");
2011 ```"),
2012             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2013             #[rustc_const_unstable(feature = "const_int_conversion")]
2014             #[inline]
2015             pub const fn from_le_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
2016                 Self::from_le(Self::from_ne_bytes(bytes))
2017             }
2018         }
2019
2020         doc_comment! {
2021             concat!("Create an integer value from its memory representation as a byte
2022 array in native endianness.
2023
2024 As the target platform's native endianness is used, portable code
2025 likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as
2026 appropriate instead.
2027
2028 [`from_be_bytes`]: #method.from_be_bytes
2029 [`from_le_bytes`]: #method.from_le_bytes
2030
2031 # Examples
2032
2033 ```
2034 let value = ", stringify!($SelfT), "::from_ne_bytes(if cfg!(target_endian = \"big\") {
2035         ", $be_bytes, "
2036     } else {
2037         ", $le_bytes, "
2038     });
2039 assert_eq!(value, ", $swap_op, ");
2040 ```"),
2041             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2042             #[rustc_const_unstable(feature = "const_int_conversion")]
2043             #[inline]
2044             pub const fn from_ne_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
2045                 unsafe { mem::transmute(bytes) }
2046             }
2047         }
2048     }
2049 }
2050
2051 #[lang = "i8"]
2052 impl i8 {
2053     int_impl! { i8, i8, u8, 8, -128, 127, "", "", 2, "-0x7e", "0xa", "0x12", "0x12", "0x48",
2054         "[0x12]", "[0x12]" }
2055 }
2056
2057 #[lang = "i16"]
2058 impl i16 {
2059     int_impl! { i16, i16, u16, 16, -32768, 32767, "", "", 4, "-0x5ffd", "0x3a", "0x1234", "0x3412",
2060         "0x2c48", "[0x34, 0x12]", "[0x12, 0x34]" }
2061 }
2062
2063 #[lang = "i32"]
2064 impl i32 {
2065     int_impl! { i32, i32, u32, 32, -2147483648, 2147483647, "", "", 8, "0x10000b3", "0xb301",
2066         "0x12345678", "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]",
2067         "[0x12, 0x34, 0x56, 0x78]" }
2068 }
2069
2070 #[lang = "i64"]
2071 impl i64 {
2072     int_impl! { i64, i64, u64, 64, -9223372036854775808, 9223372036854775807, "", "", 12,
2073          "0xaa00000000006e1", "0x6e10aa", "0x1234567890123456", "0x5634129078563412",
2074          "0x6a2c48091e6a2c48", "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
2075          "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]" }
2076 }
2077
2078 #[lang = "i128"]
2079 impl i128 {
2080     int_impl! { i128, i128, u128, 128, -170141183460469231731687303715884105728,
2081         170141183460469231731687303715884105727, "", "", 16,
2082         "0x13f40000000000000000000000004f76", "0x4f7613f4", "0x12345678901234567890123456789012",
2083         "0x12907856341290785634129078563412", "0x48091e6a2c48091e6a2c48091e6a2c48",
2084         "[0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, \
2085           0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
2086         "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56, \
2087           0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12]" }
2088 }
2089
2090 #[cfg(target_pointer_width = "16")]
2091 #[lang = "isize"]
2092 impl isize {
2093     int_impl! { isize, i16, u16, 16, -32768, 32767, "", "", 4, "-0x5ffd", "0x3a", "0x1234",
2094         "0x3412", "0x2c48", "[0x34, 0x12]", "[0x12, 0x34]" }
2095 }
2096
2097 #[cfg(target_pointer_width = "32")]
2098 #[lang = "isize"]
2099 impl isize {
2100     int_impl! { isize, i32, u32, 32, -2147483648, 2147483647, "", "", 8, "0x10000b3", "0xb301",
2101         "0x12345678", "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]",
2102         "[0x12, 0x34, 0x56, 0x78]" }
2103 }
2104
2105 #[cfg(target_pointer_width = "64")]
2106 #[lang = "isize"]
2107 impl isize {
2108     int_impl! { isize, i64, u64, 64, -9223372036854775808, 9223372036854775807, "", "",
2109         12, "0xaa00000000006e1", "0x6e10aa",  "0x1234567890123456", "0x5634129078563412",
2110          "0x6a2c48091e6a2c48", "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
2111          "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]" }
2112 }
2113
2114 // Emits the correct `cttz` call, depending on the size of the type.
2115 macro_rules! uint_cttz_call {
2116     // As of LLVM 3.6 the codegen for the zero-safe cttz8 intrinsic
2117     // emits two conditional moves on x86_64. By promoting the value to
2118     // u16 and setting bit 8, we get better code without any conditional
2119     // operations.
2120     // FIXME: There's a LLVM patch (http://reviews.llvm.org/D9284)
2121     // pending, remove this workaround once LLVM generates better code
2122     // for cttz8.
2123     ($value:expr, 8) => { intrinsics::cttz($value as u16 | 0x100) };
2124     ($value:expr, $_BITS:expr) => { intrinsics::cttz($value) }
2125 }
2126
2127 // `Int` + `UnsignedInt` implemented for unsigned integers
2128 macro_rules! uint_impl {
2129     ($SelfT:ty, $ActualT:ty, $BITS:expr, $MaxV:expr, $Feature:expr, $EndFeature:expr,
2130         $rot:expr, $rot_op:expr, $rot_result:expr, $swap_op:expr, $swapped:expr,
2131         $reversed:expr, $le_bytes:expr, $be_bytes:expr) => {
2132         doc_comment! {
2133             concat!("Returns the smallest value that can be represented by this integer type.
2134
2135 # Examples
2136
2137 Basic usage:
2138
2139 ```
2140 ", $Feature, "assert_eq!(", stringify!($SelfT), "::min_value(), 0);", $EndFeature, "
2141 ```"),
2142             #[stable(feature = "rust1", since = "1.0.0")]
2143             #[rustc_promotable]
2144             #[inline]
2145             pub const fn min_value() -> Self { 0 }
2146         }
2147
2148         doc_comment! {
2149             concat!("Returns the largest value that can be represented by this integer type.
2150
2151 # Examples
2152
2153 Basic usage:
2154
2155 ```
2156 ", $Feature, "assert_eq!(", stringify!($SelfT), "::max_value(), ",
2157 stringify!($MaxV), ");", $EndFeature, "
2158 ```"),
2159             #[stable(feature = "rust1", since = "1.0.0")]
2160             #[rustc_promotable]
2161             #[inline]
2162             pub const fn max_value() -> Self { !0 }
2163         }
2164
2165         doc_comment! {
2166             concat!("Converts a string slice in a given base to an integer.
2167
2168 The string is expected to be an optional `+` sign
2169 followed by digits.
2170 Leading and trailing whitespace represent an error.
2171 Digits are a subset of these characters, depending on `radix`:
2172
2173 * `0-9`
2174 * `a-z`
2175 * `A-Z`
2176
2177 # Panics
2178
2179 This function panics if `radix` is not in the range from 2 to 36.
2180
2181 # Examples
2182
2183 Basic usage:
2184
2185 ```
2186 ", $Feature, "assert_eq!(", stringify!($SelfT), "::from_str_radix(\"A\", 16), Ok(10));",
2187 $EndFeature, "
2188 ```"),
2189             #[stable(feature = "rust1", since = "1.0.0")]
2190             pub fn from_str_radix(src: &str, radix: u32) -> Result<Self, ParseIntError> {
2191                 from_str_radix(src, radix)
2192             }
2193         }
2194
2195         doc_comment! {
2196             concat!("Returns the number of ones in the binary representation of `self`.
2197
2198 # Examples
2199
2200 Basic usage:
2201
2202 ```
2203 ", $Feature, "let n = 0b01001100", stringify!($SelfT), ";
2204
2205 assert_eq!(n.count_ones(), 3);", $EndFeature, "
2206 ```"),
2207             #[stable(feature = "rust1", since = "1.0.0")]
2208             #[rustc_const_unstable(feature = "const_int_ops")]
2209             #[inline]
2210             pub const fn count_ones(self) -> u32 {
2211                 unsafe { intrinsics::ctpop(self as $ActualT) as u32 }
2212             }
2213         }
2214
2215         doc_comment! {
2216             concat!("Returns the number of zeros in the binary representation of `self`.
2217
2218 # Examples
2219
2220 Basic usage:
2221
2222 ```
2223 ", $Feature, "assert_eq!(", stringify!($SelfT), "::max_value().count_zeros(), 0);", $EndFeature, "
2224 ```"),
2225             #[stable(feature = "rust1", since = "1.0.0")]
2226             #[rustc_const_unstable(feature = "const_int_ops")]
2227             #[inline]
2228             pub const fn count_zeros(self) -> u32 {
2229                 (!self).count_ones()
2230             }
2231         }
2232
2233         doc_comment! {
2234             concat!("Returns the number of leading zeros in the binary representation of `self`.
2235
2236 # Examples
2237
2238 Basic usage:
2239
2240 ```
2241 ", $Feature, "let n = ", stringify!($SelfT), "::max_value() >> 2;
2242
2243 assert_eq!(n.leading_zeros(), 2);", $EndFeature, "
2244 ```"),
2245             #[stable(feature = "rust1", since = "1.0.0")]
2246             #[rustc_const_unstable(feature = "const_int_ops")]
2247             #[inline]
2248             pub const fn leading_zeros(self) -> u32 {
2249                 unsafe { intrinsics::ctlz(self as $ActualT) as u32 }
2250             }
2251         }
2252
2253         doc_comment! {
2254             concat!("Returns the number of trailing zeros in the binary representation
2255 of `self`.
2256
2257 # Examples
2258
2259 Basic usage:
2260
2261 ```
2262 ", $Feature, "let n = 0b0101000", stringify!($SelfT), ";
2263
2264 assert_eq!(n.trailing_zeros(), 3);", $EndFeature, "
2265 ```"),
2266             #[stable(feature = "rust1", since = "1.0.0")]
2267             #[rustc_const_unstable(feature = "const_int_ops")]
2268             #[inline]
2269             pub const fn trailing_zeros(self) -> u32 {
2270                 unsafe { uint_cttz_call!(self, $BITS) as u32 }
2271             }
2272         }
2273
2274         doc_comment! {
2275             concat!("Shifts the bits to the left by a specified amount, `n`,
2276 wrapping the truncated bits to the end of the resulting integer.
2277
2278 Please note this isn't the same operation as `<<`!
2279
2280 # Examples
2281
2282 Basic usage:
2283
2284 ```
2285 let n = ", $rot_op, stringify!($SelfT), ";
2286 let m = ", $rot_result, ";
2287
2288 assert_eq!(n.rotate_left(", $rot, "), m);
2289 ```"),
2290             #[stable(feature = "rust1", since = "1.0.0")]
2291             #[rustc_const_unstable(feature = "const_int_rotate")]
2292             #[inline]
2293             pub const fn rotate_left(self, n: u32) -> Self {
2294                 #[cfg(not(stage0))] {
2295                     unsafe { intrinsics::rotate_left(self, n as $SelfT) }
2296                 }
2297                 #[cfg(stage0)] {
2298                     (self << (n % $BITS)) | (self >> (($BITS - (n % $BITS)) % $BITS))
2299                 }
2300             }
2301         }
2302
2303         doc_comment! {
2304             concat!("Shifts the bits to the right by a specified amount, `n`,
2305 wrapping the truncated bits to the beginning of the resulting
2306 integer.
2307
2308 Please note this isn't the same operation as `>>`!
2309
2310 # Examples
2311
2312 Basic usage:
2313
2314 ```
2315 let n = ", $rot_result, stringify!($SelfT), ";
2316 let m = ", $rot_op, ";
2317
2318 assert_eq!(n.rotate_right(", $rot, "), m);
2319 ```"),
2320             #[stable(feature = "rust1", since = "1.0.0")]
2321             #[rustc_const_unstable(feature = "const_int_rotate")]
2322             #[inline]
2323             pub const fn rotate_right(self, n: u32) -> Self {
2324                 #[cfg(not(stage0))] {
2325                     unsafe { intrinsics::rotate_right(self, n as $SelfT) }
2326                 }
2327                 #[cfg(stage0)] {
2328                     (self >> (n % $BITS)) | (self << (($BITS - (n % $BITS)) % $BITS))
2329                 }
2330             }
2331         }
2332
2333         doc_comment! {
2334             concat!("
2335 Reverses the byte order of the integer.
2336
2337 # Examples
2338
2339 Basic usage:
2340
2341 ```
2342 let n = ", $swap_op, stringify!($SelfT), ";
2343 let m = n.swap_bytes();
2344
2345 assert_eq!(m, ", $swapped, ");
2346 ```"),
2347             #[stable(feature = "rust1", since = "1.0.0")]
2348             #[rustc_const_unstable(feature = "const_int_ops")]
2349             #[inline]
2350             pub const fn swap_bytes(self) -> Self {
2351                 unsafe { intrinsics::bswap(self as $ActualT) as Self }
2352             }
2353         }
2354
2355         doc_comment! {
2356             concat!("Reverses the bit pattern of the integer.
2357
2358 # Examples
2359
2360 Basic usage:
2361
2362 ```
2363 #![feature(reverse_bits)]
2364
2365 let n = ", $swap_op, stringify!($SelfT), ";
2366 let m = n.reverse_bits();
2367
2368 assert_eq!(m, ", $reversed, ");
2369 ```"),
2370             #[unstable(feature = "reverse_bits", issue = "48763")]
2371             #[rustc_const_unstable(feature = "const_int_conversion")]
2372             #[inline]
2373             pub const fn reverse_bits(self) -> Self {
2374                 unsafe { intrinsics::bitreverse(self as $ActualT) as Self }
2375             }
2376         }
2377
2378         doc_comment! {
2379             concat!("Converts an integer from big endian to the target's endianness.
2380
2381 On big endian this is a no-op. On little endian the bytes are
2382 swapped.
2383
2384 # Examples
2385
2386 Basic usage:
2387
2388 ```
2389 ", $Feature, "let n = 0x1A", stringify!($SelfT), ";
2390
2391 if cfg!(target_endian = \"big\") {
2392     assert_eq!(", stringify!($SelfT), "::from_be(n), n)
2393 } else {
2394     assert_eq!(", stringify!($SelfT), "::from_be(n), n.swap_bytes())
2395 }", $EndFeature, "
2396 ```"),
2397             #[stable(feature = "rust1", since = "1.0.0")]
2398             #[rustc_const_unstable(feature = "const_int_ops")]
2399             #[inline]
2400             pub const fn from_be(x: Self) -> Self {
2401                 #[cfg(target_endian = "big")]
2402                 {
2403                     x
2404                 }
2405                 #[cfg(not(target_endian = "big"))]
2406                 {
2407                     x.swap_bytes()
2408                 }
2409             }
2410         }
2411
2412         doc_comment! {
2413             concat!("Converts an integer from little endian to the target's endianness.
2414
2415 On little endian this is a no-op. On big endian the bytes are
2416 swapped.
2417
2418 # Examples
2419
2420 Basic usage:
2421
2422 ```
2423 ", $Feature, "let n = 0x1A", stringify!($SelfT), ";
2424
2425 if cfg!(target_endian = \"little\") {
2426     assert_eq!(", stringify!($SelfT), "::from_le(n), n)
2427 } else {
2428     assert_eq!(", stringify!($SelfT), "::from_le(n), n.swap_bytes())
2429 }", $EndFeature, "
2430 ```"),
2431             #[stable(feature = "rust1", since = "1.0.0")]
2432             #[rustc_const_unstable(feature = "const_int_ops")]
2433             #[inline]
2434             pub const fn from_le(x: Self) -> Self {
2435                 #[cfg(target_endian = "little")]
2436                 {
2437                     x
2438                 }
2439                 #[cfg(not(target_endian = "little"))]
2440                 {
2441                     x.swap_bytes()
2442                 }
2443             }
2444         }
2445
2446         doc_comment! {
2447             concat!("Converts `self` to big endian from the target's endianness.
2448
2449 On big endian this is a no-op. On little endian the bytes are
2450 swapped.
2451
2452 # Examples
2453
2454 Basic usage:
2455
2456 ```
2457 ", $Feature, "let n = 0x1A", stringify!($SelfT), ";
2458
2459 if cfg!(target_endian = \"big\") {
2460     assert_eq!(n.to_be(), n)
2461 } else {
2462     assert_eq!(n.to_be(), n.swap_bytes())
2463 }", $EndFeature, "
2464 ```"),
2465             #[stable(feature = "rust1", since = "1.0.0")]
2466             #[rustc_const_unstable(feature = "const_int_ops")]
2467             #[inline]
2468             pub const fn to_be(self) -> Self { // or not to be?
2469                 #[cfg(target_endian = "big")]
2470                 {
2471                     self
2472                 }
2473                 #[cfg(not(target_endian = "big"))]
2474                 {
2475                     self.swap_bytes()
2476                 }
2477             }
2478         }
2479
2480         doc_comment! {
2481             concat!("Converts `self` to little endian from the target's endianness.
2482
2483 On little endian this is a no-op. On big endian the bytes are
2484 swapped.
2485
2486 # Examples
2487
2488 Basic usage:
2489
2490 ```
2491 ", $Feature, "let n = 0x1A", stringify!($SelfT), ";
2492
2493 if cfg!(target_endian = \"little\") {
2494     assert_eq!(n.to_le(), n)
2495 } else {
2496     assert_eq!(n.to_le(), n.swap_bytes())
2497 }", $EndFeature, "
2498 ```"),
2499             #[stable(feature = "rust1", since = "1.0.0")]
2500             #[rustc_const_unstable(feature = "const_int_ops")]
2501             #[inline]
2502             pub const fn to_le(self) -> Self {
2503                 #[cfg(target_endian = "little")]
2504                 {
2505                     self
2506                 }
2507                 #[cfg(not(target_endian = "little"))]
2508                 {
2509                     self.swap_bytes()
2510                 }
2511             }
2512         }
2513
2514         doc_comment! {
2515             concat!("Checked integer addition. Computes `self + rhs`, returning `None`
2516 if overflow occurred.
2517
2518 # Examples
2519
2520 Basic usage:
2521
2522 ```
2523 ", $Feature, "assert_eq!((", stringify!($SelfT), "::max_value() - 2).checked_add(1), ",
2524 "Some(", stringify!($SelfT), "::max_value() - 1));
2525 assert_eq!((", stringify!($SelfT), "::max_value() - 2).checked_add(3), None);", $EndFeature, "
2526 ```"),
2527             #[stable(feature = "rust1", since = "1.0.0")]
2528             #[inline]
2529             pub fn checked_add(self, rhs: Self) -> Option<Self> {
2530                 let (a, b) = self.overflowing_add(rhs);
2531                 if b {None} else {Some(a)}
2532             }
2533         }
2534
2535         doc_comment! {
2536             concat!("Checked integer subtraction. Computes `self - rhs`, returning
2537 `None` if overflow occurred.
2538
2539 # Examples
2540
2541 Basic usage:
2542
2543 ```
2544 ", $Feature, "assert_eq!(1", stringify!($SelfT), ".checked_sub(1), Some(0));
2545 assert_eq!(0", stringify!($SelfT), ".checked_sub(1), None);", $EndFeature, "
2546 ```"),
2547             #[stable(feature = "rust1", since = "1.0.0")]
2548             #[inline]
2549             pub fn checked_sub(self, rhs: Self) -> Option<Self> {
2550                 let (a, b) = self.overflowing_sub(rhs);
2551                 if b {None} else {Some(a)}
2552             }
2553         }
2554
2555         doc_comment! {
2556             concat!("Checked integer multiplication. Computes `self * rhs`, returning
2557 `None` if overflow occurred.
2558
2559 # Examples
2560
2561 Basic usage:
2562
2563 ```
2564 ", $Feature, "assert_eq!(5", stringify!($SelfT), ".checked_mul(1), Some(5));
2565 assert_eq!(", stringify!($SelfT), "::max_value().checked_mul(2), None);", $EndFeature, "
2566 ```"),
2567             #[stable(feature = "rust1", since = "1.0.0")]
2568             #[inline]
2569             pub fn checked_mul(self, rhs: Self) -> Option<Self> {
2570                 let (a, b) = self.overflowing_mul(rhs);
2571                 if b {None} else {Some(a)}
2572             }
2573         }
2574
2575         doc_comment! {
2576             concat!("Checked integer division. Computes `self / rhs`, returning `None`
2577 if `rhs == 0`.
2578
2579 # Examples
2580
2581 Basic usage:
2582
2583 ```
2584 ", $Feature, "assert_eq!(128", stringify!($SelfT), ".checked_div(2), Some(64));
2585 assert_eq!(1", stringify!($SelfT), ".checked_div(0), None);", $EndFeature, "
2586 ```"),
2587             #[stable(feature = "rust1", since = "1.0.0")]
2588             #[inline]
2589             pub fn checked_div(self, rhs: Self) -> Option<Self> {
2590                 match rhs {
2591                     0 => None,
2592                     rhs => Some(unsafe { intrinsics::unchecked_div(self, rhs) }),
2593                 }
2594             }
2595         }
2596
2597         doc_comment! {
2598             concat!("Checked Euclidean division. Computes `self.div_euc(rhs)`, returning `None`
2599 if `rhs == 0`.
2600
2601 # Examples
2602
2603 Basic usage:
2604
2605 ```
2606 #![feature(euclidean_division)]
2607 assert_eq!(128", stringify!($SelfT), ".checked_div(2), Some(64));
2608 assert_eq!(1", stringify!($SelfT), ".checked_div_euc(0), None);
2609 ```"),
2610             #[unstable(feature = "euclidean_division", issue = "49048")]
2611             #[inline]
2612             pub fn checked_div_euc(self, rhs: Self) -> Option<Self> {
2613                 if rhs == 0 {
2614                     None
2615                 } else {
2616                     Some(self.div_euc(rhs))
2617                 }
2618             }
2619         }
2620
2621
2622         doc_comment! {
2623             concat!("Checked integer remainder. Computes `self % rhs`, returning `None`
2624 if `rhs == 0`.
2625
2626 # Examples
2627
2628 Basic usage:
2629
2630 ```
2631 ", $Feature, "assert_eq!(5", stringify!($SelfT), ".checked_rem(2), Some(1));
2632 assert_eq!(5", stringify!($SelfT), ".checked_rem(0), None);", $EndFeature, "
2633 ```"),
2634             #[stable(feature = "wrapping", since = "1.7.0")]
2635             #[inline]
2636             pub fn checked_rem(self, rhs: Self) -> Option<Self> {
2637                 if rhs == 0 {
2638                     None
2639                 } else {
2640                     Some(unsafe { intrinsics::unchecked_rem(self, rhs) })
2641                 }
2642             }
2643         }
2644
2645         doc_comment! {
2646             concat!("Checked Euclidean modulo. Computes `self.mod_euc(rhs)`, returning `None`
2647 if `rhs == 0`.
2648
2649 # Examples
2650
2651 Basic usage:
2652
2653 ```
2654 #![feature(euclidean_division)]
2655 assert_eq!(5", stringify!($SelfT), ".checked_mod_euc(2), Some(1));
2656 assert_eq!(5", stringify!($SelfT), ".checked_mod_euc(0), None);
2657 ```"),
2658             #[unstable(feature = "euclidean_division", issue = "49048")]
2659             #[inline]
2660             pub fn checked_mod_euc(self, rhs: Self) -> Option<Self> {
2661                 if rhs == 0 {
2662                     None
2663                 } else {
2664                     Some(self.mod_euc(rhs))
2665                 }
2666             }
2667         }
2668
2669         doc_comment! {
2670             concat!("Checked negation. Computes `-self`, returning `None` unless `self ==
2671 0`.
2672
2673 Note that negating any positive integer will overflow.
2674
2675 # Examples
2676
2677 Basic usage:
2678
2679 ```
2680 ", $Feature, "assert_eq!(0", stringify!($SelfT), ".checked_neg(), Some(0));
2681 assert_eq!(1", stringify!($SelfT), ".checked_neg(), None);", $EndFeature, "
2682 ```"),
2683             #[stable(feature = "wrapping", since = "1.7.0")]
2684             #[inline]
2685             pub fn checked_neg(self) -> Option<Self> {
2686                 let (a, b) = self.overflowing_neg();
2687                 if b {None} else {Some(a)}
2688             }
2689         }
2690
2691         doc_comment! {
2692             concat!("Checked shift left. Computes `self << rhs`, returning `None`
2693 if `rhs` is larger than or equal to the number of bits in `self`.
2694
2695 # Examples
2696
2697 Basic usage:
2698
2699 ```
2700 ", $Feature, "assert_eq!(0x1", stringify!($SelfT), ".checked_shl(4), Some(0x10));
2701 assert_eq!(0x10", stringify!($SelfT), ".checked_shl(129), None);", $EndFeature, "
2702 ```"),
2703             #[stable(feature = "wrapping", since = "1.7.0")]
2704             #[inline]
2705             pub fn checked_shl(self, rhs: u32) -> Option<Self> {
2706                 let (a, b) = self.overflowing_shl(rhs);
2707                 if b {None} else {Some(a)}
2708             }
2709         }
2710
2711         doc_comment! {
2712             concat!("Checked shift right. Computes `self >> rhs`, returning `None`
2713 if `rhs` is larger than or equal to the number of bits in `self`.
2714
2715 # Examples
2716
2717 Basic usage:
2718
2719 ```
2720 ", $Feature, "assert_eq!(0x10", stringify!($SelfT), ".checked_shr(4), Some(0x1));
2721 assert_eq!(0x10", stringify!($SelfT), ".checked_shr(129), None);", $EndFeature, "
2722 ```"),
2723             #[stable(feature = "wrapping", since = "1.7.0")]
2724             #[inline]
2725             pub fn checked_shr(self, rhs: u32) -> Option<Self> {
2726                 let (a, b) = self.overflowing_shr(rhs);
2727                 if b {None} else {Some(a)}
2728             }
2729         }
2730
2731         doc_comment! {
2732             concat!("Checked exponentiation. Computes `self.pow(exp)`, returning `None` if
2733 overflow occurred.
2734
2735 # Examples
2736
2737 Basic usage:
2738
2739 ```
2740 #![feature(no_panic_pow)]
2741 ", $Feature, "assert_eq!(2", stringify!($SelfT), ".checked_pow(5), Some(32));
2742 assert_eq!(", stringify!($SelfT), "::max_value().checked_pow(2), None);", $EndFeature, "
2743 ```"),
2744             #[unstable(feature = "no_panic_pow", issue = "48320")]
2745             #[inline]
2746             pub fn checked_pow(self, mut exp: u32) -> Option<Self> {
2747                 let mut base = self;
2748                 let mut acc: Self = 1;
2749
2750                 while exp > 1 {
2751                     if (exp & 1) == 1 {
2752                         acc = acc.checked_mul(base)?;
2753                     }
2754                     exp /= 2;
2755                     base = base.checked_mul(base)?;
2756                 }
2757
2758                 // Deal with the final bit of the exponent separately, since
2759                 // squaring the base afterwards is not necessary and may cause a
2760                 // needless overflow.
2761                 if exp == 1 {
2762                     acc = acc.checked_mul(base)?;
2763                 }
2764
2765                 Some(acc)
2766             }
2767         }
2768
2769         doc_comment! {
2770             concat!("Saturating integer addition. Computes `self + rhs`, saturating at
2771 the numeric bounds instead of overflowing.
2772
2773 # Examples
2774
2775 Basic usage:
2776
2777 ```
2778 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".saturating_add(1), 101);
2779 assert_eq!(200u8.saturating_add(127), 255);", $EndFeature, "
2780 ```"),
2781             #[stable(feature = "rust1", since = "1.0.0")]
2782             #[inline]
2783             pub fn saturating_add(self, rhs: Self) -> Self {
2784                 match self.checked_add(rhs) {
2785                     Some(x) => x,
2786                     None => Self::max_value(),
2787                 }
2788             }
2789         }
2790
2791         doc_comment! {
2792             concat!("Saturating integer subtraction. Computes `self - rhs`, saturating
2793 at the numeric bounds instead of overflowing.
2794
2795 # Examples
2796
2797 Basic usage:
2798
2799 ```
2800 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".saturating_sub(27), 73);
2801 assert_eq!(13", stringify!($SelfT), ".saturating_sub(127), 0);", $EndFeature, "
2802 ```"),
2803             #[stable(feature = "rust1", since = "1.0.0")]
2804             #[inline]
2805             pub fn saturating_sub(self, rhs: Self) -> Self {
2806                 match self.checked_sub(rhs) {
2807                     Some(x) => x,
2808                     None => Self::min_value(),
2809                 }
2810             }
2811         }
2812
2813         doc_comment! {
2814             concat!("Saturating integer multiplication. Computes `self * rhs`,
2815 saturating at the numeric bounds instead of overflowing.
2816
2817 # Examples
2818
2819 Basic usage:
2820
2821 ```
2822 ", $Feature, "use std::", stringify!($SelfT), ";
2823
2824 assert_eq!(2", stringify!($SelfT), ".saturating_mul(10), 20);
2825 assert_eq!((", stringify!($SelfT), "::MAX).saturating_mul(10), ", stringify!($SelfT),
2826 "::MAX);", $EndFeature, "
2827 ```"),
2828             #[stable(feature = "wrapping", since = "1.7.0")]
2829             #[inline]
2830             pub fn saturating_mul(self, rhs: Self) -> Self {
2831                 self.checked_mul(rhs).unwrap_or(Self::max_value())
2832             }
2833         }
2834
2835         doc_comment! {
2836             concat!("Saturating integer exponentiation. Computes `self.pow(exp)`,
2837 saturating at the numeric bounds instead of overflowing.
2838
2839 # Examples
2840
2841 Basic usage:
2842
2843 ```
2844 #![feature(no_panic_pow)]
2845 ", $Feature, "use std::", stringify!($SelfT), ";
2846
2847 assert_eq!(4", stringify!($SelfT), ".saturating_pow(3), 64);
2848 assert_eq!(", stringify!($SelfT), "::MAX.saturating_pow(2), ", stringify!($SelfT), "::MAX);",
2849 $EndFeature, "
2850 ```"),
2851             #[unstable(feature = "no_panic_pow", issue = "48320")]
2852             #[inline]
2853             pub fn saturating_pow(self, exp: u32) -> Self {
2854                 match self.checked_pow(exp) {
2855                     Some(x) => x,
2856                     None => Self::max_value(),
2857                 }
2858             }
2859         }
2860
2861         doc_comment! {
2862             concat!("Wrapping (modular) addition. Computes `self + rhs`,
2863 wrapping around at the boundary of the type.
2864
2865 # Examples
2866
2867 Basic usage:
2868
2869 ```
2870 ", $Feature, "assert_eq!(200", stringify!($SelfT), ".wrapping_add(55), 255);
2871 assert_eq!(200", stringify!($SelfT), ".wrapping_add(", stringify!($SelfT), "::max_value()), 199);",
2872 $EndFeature, "
2873 ```"),
2874             #[stable(feature = "rust1", since = "1.0.0")]
2875             #[rustc_const_unstable(feature = "const_int_wrapping")]
2876             #[inline]
2877             pub const fn wrapping_add(self, rhs: Self) -> Self {
2878                 unsafe {
2879                     intrinsics::overflowing_add(self, rhs)
2880                 }
2881             }
2882         }
2883
2884         doc_comment! {
2885             concat!("Wrapping (modular) subtraction. Computes `self - rhs`,
2886 wrapping around at the boundary of the type.
2887
2888 # Examples
2889
2890 Basic usage:
2891
2892 ```
2893 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".wrapping_sub(100), 0);
2894 assert_eq!(100", stringify!($SelfT), ".wrapping_sub(", stringify!($SelfT), "::max_value()), 101);",
2895 $EndFeature, "
2896 ```"),
2897             #[stable(feature = "rust1", since = "1.0.0")]
2898             #[rustc_const_unstable(feature = "const_int_wrapping")]
2899             #[inline]
2900             pub const fn wrapping_sub(self, rhs: Self) -> Self {
2901                 unsafe {
2902                     intrinsics::overflowing_sub(self, rhs)
2903                 }
2904             }
2905         }
2906
2907         /// Wrapping (modular) multiplication. Computes `self *
2908         /// rhs`, wrapping around at the boundary of the type.
2909         ///
2910         /// # Examples
2911         ///
2912         /// Basic usage:
2913         ///
2914         /// Please note that this example is shared between integer types.
2915         /// Which explains why `u8` is used here.
2916         ///
2917         /// ```
2918         /// assert_eq!(10u8.wrapping_mul(12), 120);
2919         /// assert_eq!(25u8.wrapping_mul(12), 44);
2920         /// ```
2921         #[stable(feature = "rust1", since = "1.0.0")]
2922         #[rustc_const_unstable(feature = "const_int_wrapping")]
2923         #[inline]
2924         pub const fn wrapping_mul(self, rhs: Self) -> Self {
2925             unsafe {
2926                 intrinsics::overflowing_mul(self, rhs)
2927             }
2928         }
2929
2930         doc_comment! {
2931             concat!("Wrapping (modular) division. Computes `self / rhs`.
2932 Wrapped division on unsigned types is just normal division.
2933 There's no way wrapping could ever happen.
2934 This function exists, so that all operations
2935 are accounted for in the wrapping operations.
2936
2937 # Examples
2938
2939 Basic usage:
2940
2941 ```
2942 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".wrapping_div(10), 10);", $EndFeature, "
2943 ```"),
2944             #[stable(feature = "num_wrapping", since = "1.2.0")]
2945             #[inline]
2946             pub fn wrapping_div(self, rhs: Self) -> Self {
2947                 self / rhs
2948             }
2949         }
2950
2951         doc_comment! {
2952             concat!("Wrapping Euclidean division. Computes `self.div_euc(rhs)`.
2953 Wrapped division on unsigned types is just normal division.
2954 There's no way wrapping could ever happen.
2955 This function exists, so that all operations
2956 are accounted for in the wrapping operations.
2957
2958 # Examples
2959
2960 Basic usage:
2961
2962 ```
2963 #![feature(euclidean_division)]
2964 assert_eq!(100", stringify!($SelfT), ".wrapping_div_euc(10), 10);
2965 ```"),
2966             #[unstable(feature = "euclidean_division", issue = "49048")]
2967             #[inline]
2968             pub fn wrapping_div_euc(self, rhs: Self) -> Self {
2969                 self / rhs
2970             }
2971         }
2972
2973         doc_comment! {
2974             concat!("Wrapping (modular) remainder. Computes `self % rhs`.
2975 Wrapped remainder calculation on unsigned types is
2976 just the regular remainder calculation.
2977 There's no way wrapping could ever happen.
2978 This function exists, so that all operations
2979 are accounted for in the wrapping operations.
2980
2981 # Examples
2982
2983 Basic usage:
2984
2985 ```
2986 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".wrapping_rem(10), 0);", $EndFeature, "
2987 ```"),
2988             #[stable(feature = "num_wrapping", since = "1.2.0")]
2989             #[inline]
2990             pub fn wrapping_rem(self, rhs: Self) -> Self {
2991                 self % rhs
2992             }
2993         }
2994
2995         doc_comment! {
2996             concat!("Wrapping Euclidean modulo. Computes `self.mod_euc(rhs)`.
2997 Wrapped modulo calculation on unsigned types is
2998 just the regular remainder calculation.
2999 There's no way wrapping could ever happen.
3000 This function exists, so that all operations
3001 are accounted for in the wrapping operations.
3002
3003 # Examples
3004
3005 Basic usage:
3006
3007 ```
3008 #![feature(euclidean_division)]
3009 assert_eq!(100", stringify!($SelfT), ".wrapping_mod_euc(10), 0);
3010 ```"),
3011             #[unstable(feature = "euclidean_division", issue = "49048")]
3012             #[inline]
3013             pub fn wrapping_mod_euc(self, rhs: Self) -> Self {
3014                 self % rhs
3015             }
3016         }
3017
3018         /// Wrapping (modular) negation. Computes `-self`,
3019         /// wrapping around at the boundary of the type.
3020         ///
3021         /// Since unsigned types do not have negative equivalents
3022         /// all applications of this function will wrap (except for `-0`).
3023         /// For values smaller than the corresponding signed type's maximum
3024         /// the result is the same as casting the corresponding signed value.
3025         /// Any larger values are equivalent to `MAX + 1 - (val - MAX - 1)` where
3026         /// `MAX` is the corresponding signed type's maximum.
3027         ///
3028         /// # Examples
3029         ///
3030         /// Basic usage:
3031         ///
3032         /// Please note that this example is shared between integer types.
3033         /// Which explains why `i8` is used here.
3034         ///
3035         /// ```
3036         /// assert_eq!(100i8.wrapping_neg(), -100);
3037         /// assert_eq!((-128i8).wrapping_neg(), -128);
3038         /// ```
3039         #[stable(feature = "num_wrapping", since = "1.2.0")]
3040         #[inline]
3041         pub fn wrapping_neg(self) -> Self {
3042             self.overflowing_neg().0
3043         }
3044
3045         doc_comment! {
3046             concat!("Panic-free bitwise shift-left; yields `self << mask(rhs)`,
3047 where `mask` removes any high-order bits of `rhs` that
3048 would cause the shift to exceed the bitwidth of the type.
3049
3050 Note that this is *not* the same as a rotate-left; the
3051 RHS of a wrapping shift-left is restricted to the range
3052 of the type, rather than the bits shifted out of the LHS
3053 being returned to the other end. The primitive integer
3054 types all implement a `rotate_left` function, which may
3055 be what you want instead.
3056
3057 # Examples
3058
3059 Basic usage:
3060
3061 ```
3062 ", $Feature, "assert_eq!(1", stringify!($SelfT), ".wrapping_shl(7), 128);
3063 assert_eq!(1", stringify!($SelfT), ".wrapping_shl(128), 1);", $EndFeature, "
3064 ```"),
3065             #[stable(feature = "num_wrapping", since = "1.2.0")]
3066             #[rustc_const_unstable(feature = "const_int_wrapping")]
3067             #[inline]
3068             pub const fn wrapping_shl(self, rhs: u32) -> Self {
3069                 unsafe {
3070                     intrinsics::unchecked_shl(self, (rhs & ($BITS - 1)) as $SelfT)
3071                 }
3072             }
3073         }
3074
3075         doc_comment! {
3076             concat!("Panic-free bitwise shift-right; yields `self >> mask(rhs)`,
3077 where `mask` removes any high-order bits of `rhs` that
3078 would cause the shift to exceed the bitwidth of the type.
3079
3080 Note that this is *not* the same as a rotate-right; the
3081 RHS of a wrapping shift-right is restricted to the range
3082 of the type, rather than the bits shifted out of the LHS
3083 being returned to the other end. The primitive integer
3084 types all implement a `rotate_right` function, which may
3085 be what you want instead.
3086
3087 # Examples
3088
3089 Basic usage:
3090
3091 ```
3092 ", $Feature, "assert_eq!(128", stringify!($SelfT), ".wrapping_shr(7), 1);
3093 assert_eq!(128", stringify!($SelfT), ".wrapping_shr(128), 128);", $EndFeature, "
3094 ```"),
3095             #[stable(feature = "num_wrapping", since = "1.2.0")]
3096             #[rustc_const_unstable(feature = "const_int_wrapping")]
3097             #[inline]
3098             pub const fn wrapping_shr(self, rhs: u32) -> Self {
3099                 unsafe {
3100                     intrinsics::unchecked_shr(self, (rhs & ($BITS - 1)) as $SelfT)
3101                 }
3102             }
3103         }
3104
3105         doc_comment! {
3106             concat!("Wrapping (modular) exponentiation. Computes `self.pow(exp)`,
3107 wrapping around at the boundary of the type.
3108
3109 # Examples
3110
3111 Basic usage:
3112
3113 ```
3114 #![feature(no_panic_pow)]
3115 ", $Feature, "assert_eq!(3", stringify!($SelfT), ".wrapping_pow(5), 243);
3116 assert_eq!(3u8.wrapping_pow(6), 217);", $EndFeature, "
3117 ```"),
3118             #[unstable(feature = "no_panic_pow", issue = "48320")]
3119             #[inline]
3120             pub fn wrapping_pow(self, mut exp: u32) -> Self {
3121                 let mut base = self;
3122                 let mut acc: Self = 1;
3123
3124                 while exp > 1 {
3125                     if (exp & 1) == 1 {
3126                         acc = acc.wrapping_mul(base);
3127                     }
3128                     exp /= 2;
3129                     base = base.wrapping_mul(base);
3130                 }
3131
3132                 // Deal with the final bit of the exponent separately, since
3133                 // squaring the base afterwards is not necessary and may cause a
3134                 // needless overflow.
3135                 if exp == 1 {
3136                     acc = acc.wrapping_mul(base);
3137                 }
3138
3139                 acc
3140             }
3141         }
3142
3143         doc_comment! {
3144             concat!("Calculates `self` + `rhs`
3145
3146 Returns a tuple of the addition along with a boolean indicating
3147 whether an arithmetic overflow would occur. If an overflow would
3148 have occurred then the wrapped value is returned.
3149
3150 # Examples
3151
3152 Basic usage
3153
3154 ```
3155 ", $Feature, "use std::", stringify!($SelfT), ";
3156
3157 assert_eq!(5", stringify!($SelfT), ".overflowing_add(2), (7, false));
3158 assert_eq!(", stringify!($SelfT), "::MAX.overflowing_add(1), (0, true));", $EndFeature, "
3159 ```"),
3160             #[stable(feature = "wrapping", since = "1.7.0")]
3161             #[rustc_const_unstable(feature = "const_int_overflowing")]
3162             #[inline]
3163             pub const fn overflowing_add(self, rhs: Self) -> (Self, bool) {
3164                 let (a, b) = unsafe {
3165                     intrinsics::add_with_overflow(self as $ActualT,
3166                                                   rhs as $ActualT)
3167                 };
3168                 (a as Self, b)
3169             }
3170         }
3171
3172         doc_comment! {
3173             concat!("Calculates `self` - `rhs`
3174
3175 Returns a tuple of the subtraction along with a boolean indicating
3176 whether an arithmetic overflow would occur. If an overflow would
3177 have occurred then the wrapped value is returned.
3178
3179 # Examples
3180
3181 Basic usage
3182
3183 ```
3184 ", $Feature, "use std::", stringify!($SelfT), ";
3185
3186 assert_eq!(5", stringify!($SelfT), ".overflowing_sub(2), (3, false));
3187 assert_eq!(0", stringify!($SelfT), ".overflowing_sub(1), (", stringify!($SelfT), "::MAX, true));",
3188 $EndFeature, "
3189 ```"),
3190             #[stable(feature = "wrapping", since = "1.7.0")]
3191             #[rustc_const_unstable(feature = "const_int_overflowing")]
3192             #[inline]
3193             pub const fn overflowing_sub(self, rhs: Self) -> (Self, bool) {
3194                 let (a, b) = unsafe {
3195                     intrinsics::sub_with_overflow(self as $ActualT,
3196                                                   rhs as $ActualT)
3197                 };
3198                 (a as Self, b)
3199             }
3200         }
3201
3202         /// Calculates the multiplication of `self` and `rhs`.
3203         ///
3204         /// Returns a tuple of the multiplication along with a boolean
3205         /// indicating whether an arithmetic overflow would occur. If an
3206         /// overflow would have occurred then the wrapped value is returned.
3207         ///
3208         /// # Examples
3209         ///
3210         /// Basic usage:
3211         ///
3212         /// Please note that this example is shared between integer types.
3213         /// Which explains why `u32` is used here.
3214         ///
3215         /// ```
3216         /// assert_eq!(5u32.overflowing_mul(2), (10, false));
3217         /// assert_eq!(1_000_000_000u32.overflowing_mul(10), (1410065408, true));
3218         /// ```
3219         #[stable(feature = "wrapping", since = "1.7.0")]
3220         #[rustc_const_unstable(feature = "const_int_overflowing")]
3221         #[inline]
3222         pub const fn overflowing_mul(self, rhs: Self) -> (Self, bool) {
3223             let (a, b) = unsafe {
3224                 intrinsics::mul_with_overflow(self as $ActualT,
3225                                               rhs as $ActualT)
3226             };
3227             (a as Self, b)
3228         }
3229
3230         doc_comment! {
3231             concat!("Calculates the divisor when `self` is divided by `rhs`.
3232
3233 Returns a tuple of the divisor along with a boolean indicating
3234 whether an arithmetic overflow would occur. Note that for unsigned
3235 integers overflow never occurs, so the second value is always
3236 `false`.
3237
3238 # Panics
3239
3240 This function will panic if `rhs` is 0.
3241
3242 # Examples
3243
3244 Basic usage
3245
3246 ```
3247 ", $Feature, "assert_eq!(5", stringify!($SelfT), ".overflowing_div(2), (2, false));", $EndFeature, "
3248 ```"),
3249             #[inline]
3250             #[stable(feature = "wrapping", since = "1.7.0")]
3251             pub fn overflowing_div(self, rhs: Self) -> (Self, bool) {
3252                 (self / rhs, false)
3253             }
3254         }
3255
3256         doc_comment! {
3257             concat!("Calculates the quotient of Euclidean division `self.div_euc(rhs)`.
3258
3259 Returns a tuple of the divisor along with a boolean indicating
3260 whether an arithmetic overflow would occur. Note that for unsigned
3261 integers overflow never occurs, so the second value is always
3262 `false`.
3263
3264 # Panics
3265
3266 This function will panic if `rhs` is 0.
3267
3268 # Examples
3269
3270 Basic usage
3271
3272 ```
3273 #![feature(euclidean_division)]
3274 assert_eq!(5", stringify!($SelfT), ".overflowing_div_euc(2), (2, false));
3275 ```"),
3276             #[inline]
3277             #[unstable(feature = "euclidean_division", issue = "49048")]
3278             pub fn overflowing_div_euc(self, rhs: Self) -> (Self, bool) {
3279                 (self / rhs, false)
3280             }
3281         }
3282
3283         doc_comment! {
3284             concat!("Calculates the remainder when `self` is divided by `rhs`.
3285
3286 Returns a tuple of the remainder after dividing along with a boolean
3287 indicating whether an arithmetic overflow would occur. Note that for
3288 unsigned integers overflow never occurs, so the second value is
3289 always `false`.
3290
3291 # Panics
3292
3293 This function will panic if `rhs` is 0.
3294
3295 # Examples
3296
3297 Basic usage
3298
3299 ```
3300 ", $Feature, "assert_eq!(5", stringify!($SelfT), ".overflowing_rem(2), (1, false));", $EndFeature, "
3301 ```"),
3302             #[inline]
3303             #[stable(feature = "wrapping", since = "1.7.0")]
3304             pub fn overflowing_rem(self, rhs: Self) -> (Self, bool) {
3305                 (self % rhs, false)
3306             }
3307         }
3308
3309         doc_comment! {
3310             concat!("Calculates the remainder `self.mod_euc(rhs)` by Euclidean division.
3311
3312 Returns a tuple of the modulo after dividing along with a boolean
3313 indicating whether an arithmetic overflow would occur. Note that for
3314 unsigned integers overflow never occurs, so the second value is
3315 always `false`.
3316
3317 # Panics
3318
3319 This function will panic if `rhs` is 0.
3320
3321 # Examples
3322
3323 Basic usage
3324
3325 ```
3326 #![feature(euclidean_division)]
3327 assert_eq!(5", stringify!($SelfT), ".overflowing_mod_euc(2), (1, false));
3328 ```"),
3329             #[inline]
3330             #[unstable(feature = "euclidean_division", issue = "49048")]
3331             pub fn overflowing_mod_euc(self, rhs: Self) -> (Self, bool) {
3332                 (self % rhs, false)
3333             }
3334         }
3335
3336         doc_comment! {
3337             concat!("Negates self in an overflowing fashion.
3338
3339 Returns `!self + 1` using wrapping operations to return the value
3340 that represents the negation of this unsigned value. Note that for
3341 positive unsigned values overflow always occurs, but negating 0 does
3342 not overflow.
3343
3344 # Examples
3345
3346 Basic usage
3347
3348 ```
3349 ", $Feature, "assert_eq!(0", stringify!($SelfT), ".overflowing_neg(), (0, false));
3350 assert_eq!(2", stringify!($SelfT), ".overflowing_neg(), (-2i32 as ", stringify!($SelfT),
3351 ", true));", $EndFeature, "
3352 ```"),
3353             #[inline]
3354             #[stable(feature = "wrapping", since = "1.7.0")]
3355             pub fn overflowing_neg(self) -> (Self, bool) {
3356                 ((!self).wrapping_add(1), self != 0)
3357             }
3358         }
3359
3360         doc_comment! {
3361             concat!("Shifts self left by `rhs` bits.
3362
3363 Returns a tuple of the shifted version of self along with a boolean
3364 indicating whether the shift value was larger than or equal to the
3365 number of bits. If the shift value is too large, then value is
3366 masked (N-1) where N is the number of bits, and this value is then
3367 used to perform the shift.
3368
3369 # Examples
3370
3371 Basic usage
3372
3373 ```
3374 ", $Feature, "assert_eq!(0x1", stringify!($SelfT), ".overflowing_shl(4), (0x10, false));
3375 assert_eq!(0x1", stringify!($SelfT), ".overflowing_shl(132), (0x10, true));", $EndFeature, "
3376 ```"),
3377             #[stable(feature = "wrapping", since = "1.7.0")]
3378             #[rustc_const_unstable(feature = "const_int_overflowing")]
3379             #[inline]
3380             pub const fn overflowing_shl(self, rhs: u32) -> (Self, bool) {
3381                 (self.wrapping_shl(rhs), (rhs > ($BITS - 1)))
3382             }
3383         }
3384
3385         doc_comment! {
3386             concat!("Shifts self right by `rhs` bits.
3387
3388 Returns a tuple of the shifted version of self along with a boolean
3389 indicating whether the shift value was larger than or equal to the
3390 number of bits. If the shift value is too large, then value is
3391 masked (N-1) where N is the number of bits, and this value is then
3392 used to perform the shift.
3393
3394 # Examples
3395
3396 Basic usage
3397
3398 ```
3399 ", $Feature, "assert_eq!(0x10", stringify!($SelfT), ".overflowing_shr(4), (0x1, false));
3400 assert_eq!(0x10", stringify!($SelfT), ".overflowing_shr(132), (0x1, true));", $EndFeature, "
3401 ```"),
3402             #[stable(feature = "wrapping", since = "1.7.0")]
3403             #[rustc_const_unstable(feature = "const_int_overflowing")]
3404             #[inline]
3405             pub const fn overflowing_shr(self, rhs: u32) -> (Self, bool) {
3406                 (self.wrapping_shr(rhs), (rhs > ($BITS - 1)))
3407             }
3408         }
3409
3410         doc_comment! {
3411             concat!("Raises self to the power of `exp`, using exponentiation by squaring.
3412
3413 Returns a tuple of the exponentiation along with a bool indicating
3414 whether an overflow happened.
3415
3416 # Examples
3417
3418 Basic usage:
3419
3420 ```
3421 #![feature(no_panic_pow)]
3422 ", $Feature, "assert_eq!(3", stringify!($SelfT), ".overflowing_pow(5), (243, false));
3423 assert_eq!(3u8.overflowing_pow(6), (217, true));", $EndFeature, "
3424 ```"),
3425             #[unstable(feature = "no_panic_pow", issue = "48320")]
3426             #[inline]
3427             pub fn overflowing_pow(self, mut exp: u32) -> (Self, bool) {
3428                 let mut base = self;
3429                 let mut acc: Self = 1;
3430                 let mut overflown = false;
3431                 // Scratch space for storing results of overflowing_mul.
3432                 let mut r;
3433
3434                 while exp > 1 {
3435                     if (exp & 1) == 1 {
3436                         r = acc.overflowing_mul(base);
3437                         acc = r.0;
3438                         overflown |= r.1;
3439                     }
3440                     exp /= 2;
3441                     r = base.overflowing_mul(base);
3442                     base = r.0;
3443                     overflown |= r.1;
3444                 }
3445
3446                 // Deal with the final bit of the exponent separately, since
3447                 // squaring the base afterwards is not necessary and may cause a
3448                 // needless overflow.
3449                 if exp == 1 {
3450                     r = acc.overflowing_mul(base);
3451                     acc = r.0;
3452                     overflown |= r.1;
3453                 }
3454
3455                 (acc, overflown)
3456             }
3457         }
3458
3459         doc_comment! {
3460             concat!("Raises self to the power of `exp`, using exponentiation by squaring.
3461
3462 # Examples
3463
3464 Basic usage:
3465
3466 ```
3467 ", $Feature, "assert_eq!(2", stringify!($SelfT), ".pow(5), 32);", $EndFeature, "
3468 ```"),
3469         #[stable(feature = "rust1", since = "1.0.0")]
3470         #[inline]
3471         #[rustc_inherit_overflow_checks]
3472         pub fn pow(self, mut exp: u32) -> Self {
3473             let mut base = self;
3474             let mut acc = 1;
3475
3476             while exp > 1 {
3477                 if (exp & 1) == 1 {
3478                     acc = acc * base;
3479                 }
3480                 exp /= 2;
3481                 base = base * base;
3482             }
3483
3484             // Deal with the final bit of the exponent separately, since
3485             // squaring the base afterwards is not necessary and may cause a
3486             // needless overflow.
3487             if exp == 1 {
3488                 acc = acc * base;
3489             }
3490
3491             acc
3492         }
3493     }
3494
3495             doc_comment! {
3496             concat!("Performs Euclidean division.
3497
3498 For unsigned types, this is just the same as `self / rhs`.
3499
3500 # Examples
3501
3502 Basic usage:
3503
3504 ```
3505 #![feature(euclidean_division)]
3506 assert_eq!(7", stringify!($SelfT), ".div_euc(4), 1); // or any other integer type
3507 ```"),
3508             #[unstable(feature = "euclidean_division", issue = "49048")]
3509             #[inline]
3510             #[rustc_inherit_overflow_checks]
3511             pub fn div_euc(self, rhs: Self) -> Self {
3512                 self / rhs
3513             }
3514         }
3515
3516
3517         doc_comment! {
3518             concat!("Calculates the remainder `self mod rhs` by Euclidean division.
3519
3520 For unsigned types, this is just the same as `self % rhs`.
3521
3522 # Examples
3523
3524 Basic usage:
3525
3526 ```
3527 #![feature(euclidean_division)]
3528 assert_eq!(7", stringify!($SelfT), ".mod_euc(4), 3); // or any other integer type
3529 ```"),
3530             #[unstable(feature = "euclidean_division", issue = "49048")]
3531             #[inline]
3532             #[rustc_inherit_overflow_checks]
3533             pub fn mod_euc(self, rhs: Self) -> Self {
3534                 self % rhs
3535             }
3536         }
3537
3538         doc_comment! {
3539             concat!("Returns `true` if and only if `self == 2^k` for some `k`.
3540
3541 # Examples
3542
3543 Basic usage:
3544
3545 ```
3546 ", $Feature, "assert!(16", stringify!($SelfT), ".is_power_of_two());
3547 assert!(!10", stringify!($SelfT), ".is_power_of_two());", $EndFeature, "
3548 ```"),
3549             #[stable(feature = "rust1", since = "1.0.0")]
3550             #[inline]
3551             pub fn is_power_of_two(self) -> bool {
3552                 (self.wrapping_sub(1)) & self == 0 && !(self == 0)
3553             }
3554         }
3555
3556         // Returns one less than next power of two.
3557         // (For 8u8 next power of two is 8u8 and for 6u8 it is 8u8)
3558         //
3559         // 8u8.one_less_than_next_power_of_two() == 7
3560         // 6u8.one_less_than_next_power_of_two() == 7
3561         //
3562         // This method cannot overflow, as in the `next_power_of_two`
3563         // overflow cases it instead ends up returning the maximum value
3564         // of the type, and can return 0 for 0.
3565         #[inline]
3566         fn one_less_than_next_power_of_two(self) -> Self {
3567             if self <= 1 { return 0; }
3568
3569             // Because `p > 0`, it cannot consist entirely of leading zeros.
3570             // That means the shift is always in-bounds, and some processors
3571             // (such as intel pre-haswell) have more efficient ctlz
3572             // intrinsics when the argument is non-zero.
3573             let p = self - 1;
3574             let z = unsafe { intrinsics::ctlz_nonzero(p) };
3575             <$SelfT>::max_value() >> z
3576         }
3577
3578         doc_comment! {
3579             concat!("Returns the smallest power of two greater than or equal to `self`.
3580
3581 When return value overflows (i.e. `self > (1 << (N-1))` for type
3582 `uN`), it panics in debug mode and return value is wrapped to 0 in
3583 release mode (the only situation in which method can return 0).
3584
3585 # Examples
3586
3587 Basic usage:
3588
3589 ```
3590 ", $Feature, "assert_eq!(2", stringify!($SelfT), ".next_power_of_two(), 2);
3591 assert_eq!(3", stringify!($SelfT), ".next_power_of_two(), 4);", $EndFeature, "
3592 ```"),
3593             #[stable(feature = "rust1", since = "1.0.0")]
3594             #[inline]
3595             pub fn next_power_of_two(self) -> Self {
3596                 // Call the trait to get overflow checks
3597                 ops::Add::add(self.one_less_than_next_power_of_two(), 1)
3598             }
3599         }
3600
3601         doc_comment! {
3602             concat!("Returns the smallest power of two greater than or equal to `n`. If
3603 the next power of two is greater than the type's maximum value,
3604 `None` is returned, otherwise the power of two is wrapped in `Some`.
3605
3606 # Examples
3607
3608 Basic usage:
3609
3610 ```
3611 ", $Feature, "assert_eq!(2", stringify!($SelfT),
3612 ".checked_next_power_of_two(), Some(2));
3613 assert_eq!(3", stringify!($SelfT), ".checked_next_power_of_two(), Some(4));
3614 assert_eq!(", stringify!($SelfT), "::max_value().checked_next_power_of_two(), None);",
3615 $EndFeature, "
3616 ```"),
3617             #[stable(feature = "rust1", since = "1.0.0")]
3618             pub fn checked_next_power_of_two(self) -> Option<Self> {
3619                 self.one_less_than_next_power_of_two().checked_add(1)
3620             }
3621         }
3622
3623         doc_comment! {
3624             concat!("Returns the smallest power of two greater than or equal to `n`. If
3625 the next power of two is greater than the type's maximum value,
3626 the return value is wrapped to `0`.
3627
3628 # Examples
3629
3630 Basic usage:
3631
3632 ```
3633 #![feature(wrapping_next_power_of_two)]
3634 ", $Feature, "
3635 assert_eq!(2", stringify!($SelfT), ".wrapping_next_power_of_two(), 2);
3636 assert_eq!(3", stringify!($SelfT), ".wrapping_next_power_of_two(), 4);
3637 assert_eq!(", stringify!($SelfT), "::max_value().wrapping_next_power_of_two(), 0);",
3638 $EndFeature, "
3639 ```"),
3640             #[unstable(feature = "wrapping_next_power_of_two", issue = "32463",
3641                        reason = "needs decision on wrapping behaviour")]
3642             pub fn wrapping_next_power_of_two(self) -> Self {
3643                 self.one_less_than_next_power_of_two().wrapping_add(1)
3644             }
3645         }
3646
3647         doc_comment! {
3648             concat!("Return the memory representation of this integer as a byte array in
3649 big-endian (network) byte order.
3650
3651 # Examples
3652
3653 ```
3654 let bytes = ", $swap_op, stringify!($SelfT), ".to_be_bytes();
3655 assert_eq!(bytes, ", $be_bytes, ");
3656 ```"),
3657             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
3658             #[rustc_const_unstable(feature = "const_int_conversion")]
3659             #[inline]
3660             pub const fn to_be_bytes(self) -> [u8; mem::size_of::<Self>()] {
3661                 self.to_be().to_ne_bytes()
3662             }
3663         }
3664
3665         doc_comment! {
3666             concat!("Return the memory representation of this integer as a byte array in
3667 little-endian byte order.
3668
3669 # Examples
3670
3671 ```
3672 let bytes = ", $swap_op, stringify!($SelfT), ".to_le_bytes();
3673 assert_eq!(bytes, ", $le_bytes, ");
3674 ```"),
3675             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
3676             #[rustc_const_unstable(feature = "const_int_conversion")]
3677             #[inline]
3678             pub const fn to_le_bytes(self) -> [u8; mem::size_of::<Self>()] {
3679                 self.to_le().to_ne_bytes()
3680             }
3681         }
3682
3683         doc_comment! {
3684             concat!("
3685 Return the memory representation of this integer as a byte array in
3686 native byte order.
3687
3688 As the target platform's native endianness is used, portable code
3689 should use [`to_be_bytes`] or [`to_le_bytes`], as appropriate,
3690 instead.
3691
3692 [`to_be_bytes`]: #method.to_be_bytes
3693 [`to_le_bytes`]: #method.to_le_bytes
3694
3695 # Examples
3696
3697 ```
3698 let bytes = ", $swap_op, stringify!($SelfT), ".to_ne_bytes();
3699 assert_eq!(bytes, if cfg!(target_endian = \"big\") {
3700         ", $be_bytes, "
3701     } else {
3702         ", $le_bytes, "
3703     });
3704 ```"),
3705             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
3706             #[rustc_const_unstable(feature = "const_int_conversion")]
3707             #[inline]
3708             pub const fn to_ne_bytes(self) -> [u8; mem::size_of::<Self>()] {
3709                 unsafe { mem::transmute(self) }
3710             }
3711         }
3712
3713         doc_comment! {
3714             concat!("Create an integer value from its representation as a byte array in
3715 big endian.
3716
3717 # Examples
3718
3719 ```
3720 let value = ", stringify!($SelfT), "::from_be_bytes(", $be_bytes, ");
3721 assert_eq!(value, ", $swap_op, ");
3722 ```"),
3723             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
3724             #[rustc_const_unstable(feature = "const_int_conversion")]
3725             #[inline]
3726             pub const fn from_be_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
3727                 Self::from_be(Self::from_ne_bytes(bytes))
3728             }
3729         }
3730
3731         doc_comment! {
3732             concat!("
3733 Create an integer value from its representation as a byte array in
3734 little endian.
3735
3736 # Examples
3737
3738 ```
3739 let value = ", stringify!($SelfT), "::from_le_bytes(", $le_bytes, ");
3740 assert_eq!(value, ", $swap_op, ");
3741 ```"),
3742             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
3743             #[rustc_const_unstable(feature = "const_int_conversion")]
3744             #[inline]
3745             pub const fn from_le_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
3746                 Self::from_le(Self::from_ne_bytes(bytes))
3747             }
3748         }
3749
3750         doc_comment! {
3751             concat!("Create an integer value from its memory representation as a byte
3752 array in native endianness.
3753
3754 As the target platform's native endianness is used, portable code
3755 likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as
3756 appropriate instead.
3757
3758 [`from_be_bytes`]: #method.from_be_bytes
3759 [`from_le_bytes`]: #method.from_le_bytes
3760
3761 # Examples
3762
3763 ```
3764 let value = ", stringify!($SelfT), "::from_ne_bytes(if cfg!(target_endian = \"big\") {
3765         ", $be_bytes, "
3766     } else {
3767         ", $le_bytes, "
3768     });
3769 assert_eq!(value, ", $swap_op, ");
3770 ```"),
3771             #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
3772             #[rustc_const_unstable(feature = "const_int_conversion")]
3773             #[inline]
3774             pub const fn from_ne_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
3775                 unsafe { mem::transmute(bytes) }
3776             }
3777         }
3778     }
3779 }
3780
3781 #[lang = "u8"]
3782 impl u8 {
3783     uint_impl! { u8, u8, 8, 255, "", "", 2, "0x82", "0xa", "0x12", "0x12", "0x48", "[0x12]",
3784         "[0x12]" }
3785
3786
3787     /// Checks if the value is within the ASCII range.
3788     ///
3789     /// # Examples
3790     ///
3791     /// ```
3792     /// let ascii = 97u8;
3793     /// let non_ascii = 150u8;
3794     ///
3795     /// assert!(ascii.is_ascii());
3796     /// assert!(!non_ascii.is_ascii());
3797     /// ```
3798     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
3799     #[inline]
3800     pub fn is_ascii(&self) -> bool {
3801         *self & 128 == 0
3802     }
3803
3804     /// Makes a copy of the value in its ASCII upper case equivalent.
3805     ///
3806     /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
3807     /// but non-ASCII letters are unchanged.
3808     ///
3809     /// To uppercase the value in-place, use [`make_ascii_uppercase`].
3810     ///
3811     /// # Examples
3812     ///
3813     /// ```
3814     /// let lowercase_a = 97u8;
3815     ///
3816     /// assert_eq!(65, lowercase_a.to_ascii_uppercase());
3817     /// ```
3818     ///
3819     /// [`make_ascii_uppercase`]: #method.make_ascii_uppercase
3820     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
3821     #[inline]
3822     pub fn to_ascii_uppercase(&self) -> u8 {
3823         ASCII_UPPERCASE_MAP[*self as usize]
3824     }
3825
3826     /// Makes a copy of the value in its ASCII lower case equivalent.
3827     ///
3828     /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
3829     /// but non-ASCII letters are unchanged.
3830     ///
3831     /// To lowercase the value in-place, use [`make_ascii_lowercase`].
3832     ///
3833     /// # Examples
3834     ///
3835     /// ```
3836     /// let uppercase_a = 65u8;
3837     ///
3838     /// assert_eq!(97, uppercase_a.to_ascii_lowercase());
3839     /// ```
3840     ///
3841     /// [`make_ascii_lowercase`]: #method.make_ascii_lowercase
3842     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
3843     #[inline]
3844     pub fn to_ascii_lowercase(&self) -> u8 {
3845         ASCII_LOWERCASE_MAP[*self as usize]
3846     }
3847
3848     /// Checks that two values are an ASCII case-insensitive match.
3849     ///
3850     /// This is equivalent to `to_ascii_lowercase(a) == to_ascii_lowercase(b)`.
3851     ///
3852     /// # Examples
3853     ///
3854     /// ```
3855     /// let lowercase_a = 97u8;
3856     /// let uppercase_a = 65u8;
3857     ///
3858     /// assert!(lowercase_a.eq_ignore_ascii_case(&uppercase_a));
3859     /// ```
3860     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
3861     #[inline]
3862     pub fn eq_ignore_ascii_case(&self, other: &u8) -> bool {
3863         self.to_ascii_lowercase() == other.to_ascii_lowercase()
3864     }
3865
3866     /// Converts this value to its ASCII upper case equivalent in-place.
3867     ///
3868     /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
3869     /// but non-ASCII letters are unchanged.
3870     ///
3871     /// To return a new uppercased value without modifying the existing one, use
3872     /// [`to_ascii_uppercase`].
3873     ///
3874     /// # Examples
3875     ///
3876     /// ```
3877     /// let mut byte = b'a';
3878     ///
3879     /// byte.make_ascii_uppercase();
3880     ///
3881     /// assert_eq!(b'A', byte);
3882     /// ```
3883     ///
3884     /// [`to_ascii_uppercase`]: #method.to_ascii_uppercase
3885     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
3886     #[inline]
3887     pub fn make_ascii_uppercase(&mut self) {
3888         *self = self.to_ascii_uppercase();
3889     }
3890
3891     /// Converts this value to its ASCII lower case equivalent in-place.
3892     ///
3893     /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
3894     /// but non-ASCII letters are unchanged.
3895     ///
3896     /// To return a new lowercased value without modifying the existing one, use
3897     /// [`to_ascii_lowercase`].
3898     ///
3899     /// # Examples
3900     ///
3901     /// ```
3902     /// let mut byte = b'A';
3903     ///
3904     /// byte.make_ascii_lowercase();
3905     ///
3906     /// assert_eq!(b'a', byte);
3907     /// ```
3908     ///
3909     /// [`to_ascii_lowercase`]: #method.to_ascii_lowercase
3910     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
3911     #[inline]
3912     pub fn make_ascii_lowercase(&mut self) {
3913         *self = self.to_ascii_lowercase();
3914     }
3915
3916     /// Checks if the value is an ASCII alphabetic character:
3917     ///
3918     /// - U+0041 'A' ... U+005A 'Z', or
3919     /// - U+0061 'a' ... U+007A 'z'.
3920     ///
3921     /// # Examples
3922     ///
3923     /// ```
3924     /// let uppercase_a = b'A';
3925     /// let uppercase_g = b'G';
3926     /// let a = b'a';
3927     /// let g = b'g';
3928     /// let zero = b'0';
3929     /// let percent = b'%';
3930     /// let space = b' ';
3931     /// let lf = b'\n';
3932     /// let esc = 0x1b_u8;
3933     ///
3934     /// assert!(uppercase_a.is_ascii_alphabetic());
3935     /// assert!(uppercase_g.is_ascii_alphabetic());
3936     /// assert!(a.is_ascii_alphabetic());
3937     /// assert!(g.is_ascii_alphabetic());
3938     /// assert!(!zero.is_ascii_alphabetic());
3939     /// assert!(!percent.is_ascii_alphabetic());
3940     /// assert!(!space.is_ascii_alphabetic());
3941     /// assert!(!lf.is_ascii_alphabetic());
3942     /// assert!(!esc.is_ascii_alphabetic());
3943     /// ```
3944     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
3945     #[inline]
3946     pub fn is_ascii_alphabetic(&self) -> bool {
3947         if *self >= 0x80 { return false; }
3948         match ASCII_CHARACTER_CLASS[*self as usize] {
3949             L | Lx | U | Ux => true,
3950             _ => false
3951         }
3952     }
3953
3954     /// Checks if the value is an ASCII uppercase character:
3955     /// U+0041 'A' ... U+005A 'Z'.
3956     ///
3957     /// # Examples
3958     ///
3959     /// ```
3960     /// let uppercase_a = b'A';
3961     /// let uppercase_g = b'G';
3962     /// let a = b'a';
3963     /// let g = b'g';
3964     /// let zero = b'0';
3965     /// let percent = b'%';
3966     /// let space = b' ';
3967     /// let lf = b'\n';
3968     /// let esc = 0x1b_u8;
3969     ///
3970     /// assert!(uppercase_a.is_ascii_uppercase());
3971     /// assert!(uppercase_g.is_ascii_uppercase());
3972     /// assert!(!a.is_ascii_uppercase());
3973     /// assert!(!g.is_ascii_uppercase());
3974     /// assert!(!zero.is_ascii_uppercase());
3975     /// assert!(!percent.is_ascii_uppercase());
3976     /// assert!(!space.is_ascii_uppercase());
3977     /// assert!(!lf.is_ascii_uppercase());
3978     /// assert!(!esc.is_ascii_uppercase());
3979     /// ```
3980     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
3981     #[inline]
3982     pub fn is_ascii_uppercase(&self) -> bool {
3983         if *self >= 0x80 { return false }
3984         match ASCII_CHARACTER_CLASS[*self as usize] {
3985             U | Ux => true,
3986             _ => false
3987         }
3988     }
3989
3990     /// Checks if the value is an ASCII lowercase character:
3991     /// U+0061 'a' ... U+007A 'z'.
3992     ///
3993     /// # Examples
3994     ///
3995     /// ```
3996     /// let uppercase_a = b'A';
3997     /// let uppercase_g = b'G';
3998     /// let a = b'a';
3999     /// let g = b'g';
4000     /// let zero = b'0';
4001     /// let percent = b'%';
4002     /// let space = b' ';
4003     /// let lf = b'\n';
4004     /// let esc = 0x1b_u8;
4005     ///
4006     /// assert!(!uppercase_a.is_ascii_lowercase());
4007     /// assert!(!uppercase_g.is_ascii_lowercase());
4008     /// assert!(a.is_ascii_lowercase());
4009     /// assert!(g.is_ascii_lowercase());
4010     /// assert!(!zero.is_ascii_lowercase());
4011     /// assert!(!percent.is_ascii_lowercase());
4012     /// assert!(!space.is_ascii_lowercase());
4013     /// assert!(!lf.is_ascii_lowercase());
4014     /// assert!(!esc.is_ascii_lowercase());
4015     /// ```
4016     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4017     #[inline]
4018     pub fn is_ascii_lowercase(&self) -> bool {
4019         if *self >= 0x80 { return false }
4020         match ASCII_CHARACTER_CLASS[*self as usize] {
4021             L | Lx => true,
4022             _ => false
4023         }
4024     }
4025
4026     /// Checks if the value is an ASCII alphanumeric character:
4027     ///
4028     /// - U+0041 'A' ... U+005A 'Z', or
4029     /// - U+0061 'a' ... U+007A 'z', or
4030     /// - U+0030 '0' ... U+0039 '9'.
4031     ///
4032     /// # Examples
4033     ///
4034     /// ```
4035     /// let uppercase_a = b'A';
4036     /// let uppercase_g = b'G';
4037     /// let a = b'a';
4038     /// let g = b'g';
4039     /// let zero = b'0';
4040     /// let percent = b'%';
4041     /// let space = b' ';
4042     /// let lf = b'\n';
4043     /// let esc = 0x1b_u8;
4044     ///
4045     /// assert!(uppercase_a.is_ascii_alphanumeric());
4046     /// assert!(uppercase_g.is_ascii_alphanumeric());
4047     /// assert!(a.is_ascii_alphanumeric());
4048     /// assert!(g.is_ascii_alphanumeric());
4049     /// assert!(zero.is_ascii_alphanumeric());
4050     /// assert!(!percent.is_ascii_alphanumeric());
4051     /// assert!(!space.is_ascii_alphanumeric());
4052     /// assert!(!lf.is_ascii_alphanumeric());
4053     /// assert!(!esc.is_ascii_alphanumeric());
4054     /// ```
4055     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4056     #[inline]
4057     pub fn is_ascii_alphanumeric(&self) -> bool {
4058         if *self >= 0x80 { return false }
4059         match ASCII_CHARACTER_CLASS[*self as usize] {
4060             D | L | Lx | U | Ux => true,
4061             _ => false
4062         }
4063     }
4064
4065     /// Checks if the value is an ASCII decimal digit:
4066     /// U+0030 '0' ... U+0039 '9'.
4067     ///
4068     /// # Examples
4069     ///
4070     /// ```
4071     /// let uppercase_a = b'A';
4072     /// let uppercase_g = b'G';
4073     /// let a = b'a';
4074     /// let g = b'g';
4075     /// let zero = b'0';
4076     /// let percent = b'%';
4077     /// let space = b' ';
4078     /// let lf = b'\n';
4079     /// let esc = 0x1b_u8;
4080     ///
4081     /// assert!(!uppercase_a.is_ascii_digit());
4082     /// assert!(!uppercase_g.is_ascii_digit());
4083     /// assert!(!a.is_ascii_digit());
4084     /// assert!(!g.is_ascii_digit());
4085     /// assert!(zero.is_ascii_digit());
4086     /// assert!(!percent.is_ascii_digit());
4087     /// assert!(!space.is_ascii_digit());
4088     /// assert!(!lf.is_ascii_digit());
4089     /// assert!(!esc.is_ascii_digit());
4090     /// ```
4091     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4092     #[inline]
4093     pub fn is_ascii_digit(&self) -> bool {
4094         if *self >= 0x80 { return false }
4095         match ASCII_CHARACTER_CLASS[*self as usize] {
4096             D => true,
4097             _ => false
4098         }
4099     }
4100
4101     /// Checks if the value is an ASCII hexadecimal digit:
4102     ///
4103     /// - U+0030 '0' ... U+0039 '9', or
4104     /// - U+0041 'A' ... U+0046 'F', or
4105     /// - U+0061 'a' ... U+0066 'f'.
4106     ///
4107     /// # Examples
4108     ///
4109     /// ```
4110     /// let uppercase_a = b'A';
4111     /// let uppercase_g = b'G';
4112     /// let a = b'a';
4113     /// let g = b'g';
4114     /// let zero = b'0';
4115     /// let percent = b'%';
4116     /// let space = b' ';
4117     /// let lf = b'\n';
4118     /// let esc = 0x1b_u8;
4119     ///
4120     /// assert!(uppercase_a.is_ascii_hexdigit());
4121     /// assert!(!uppercase_g.is_ascii_hexdigit());
4122     /// assert!(a.is_ascii_hexdigit());
4123     /// assert!(!g.is_ascii_hexdigit());
4124     /// assert!(zero.is_ascii_hexdigit());
4125     /// assert!(!percent.is_ascii_hexdigit());
4126     /// assert!(!space.is_ascii_hexdigit());
4127     /// assert!(!lf.is_ascii_hexdigit());
4128     /// assert!(!esc.is_ascii_hexdigit());
4129     /// ```
4130     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4131     #[inline]
4132     pub fn is_ascii_hexdigit(&self) -> bool {
4133         if *self >= 0x80 { return false }
4134         match ASCII_CHARACTER_CLASS[*self as usize] {
4135             D | Lx | Ux => true,
4136             _ => false
4137         }
4138     }
4139
4140     /// Checks if the value is an ASCII punctuation character:
4141     ///
4142     /// - U+0021 ... U+002F `! " # $ % & ' ( ) * + , - . /`, or
4143     /// - U+003A ... U+0040 `: ; < = > ? @`, or
4144     /// - U+005B ... U+0060 ``[ \ ] ^ _ ` ``, or
4145     /// - U+007B ... U+007E `{ | } ~`
4146     ///
4147     /// # Examples
4148     ///
4149     /// ```
4150     /// let uppercase_a = b'A';
4151     /// let uppercase_g = b'G';
4152     /// let a = b'a';
4153     /// let g = b'g';
4154     /// let zero = b'0';
4155     /// let percent = b'%';
4156     /// let space = b' ';
4157     /// let lf = b'\n';
4158     /// let esc = 0x1b_u8;
4159     ///
4160     /// assert!(!uppercase_a.is_ascii_punctuation());
4161     /// assert!(!uppercase_g.is_ascii_punctuation());
4162     /// assert!(!a.is_ascii_punctuation());
4163     /// assert!(!g.is_ascii_punctuation());
4164     /// assert!(!zero.is_ascii_punctuation());
4165     /// assert!(percent.is_ascii_punctuation());
4166     /// assert!(!space.is_ascii_punctuation());
4167     /// assert!(!lf.is_ascii_punctuation());
4168     /// assert!(!esc.is_ascii_punctuation());
4169     /// ```
4170     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4171     #[inline]
4172     pub fn is_ascii_punctuation(&self) -> bool {
4173         if *self >= 0x80 { return false }
4174         match ASCII_CHARACTER_CLASS[*self as usize] {
4175             P => true,
4176             _ => false
4177         }
4178     }
4179
4180     /// Checks if the value is an ASCII graphic character:
4181     /// U+0021 '!' ... U+007E '~'.
4182     ///
4183     /// # Examples
4184     ///
4185     /// ```
4186     /// let uppercase_a = b'A';
4187     /// let uppercase_g = b'G';
4188     /// let a = b'a';
4189     /// let g = b'g';
4190     /// let zero = b'0';
4191     /// let percent = b'%';
4192     /// let space = b' ';
4193     /// let lf = b'\n';
4194     /// let esc = 0x1b_u8;
4195     ///
4196     /// assert!(uppercase_a.is_ascii_graphic());
4197     /// assert!(uppercase_g.is_ascii_graphic());
4198     /// assert!(a.is_ascii_graphic());
4199     /// assert!(g.is_ascii_graphic());
4200     /// assert!(zero.is_ascii_graphic());
4201     /// assert!(percent.is_ascii_graphic());
4202     /// assert!(!space.is_ascii_graphic());
4203     /// assert!(!lf.is_ascii_graphic());
4204     /// assert!(!esc.is_ascii_graphic());
4205     /// ```
4206     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4207     #[inline]
4208     pub fn is_ascii_graphic(&self) -> bool {
4209         if *self >= 0x80 { return false; }
4210         match ASCII_CHARACTER_CLASS[*self as usize] {
4211             Ux | U | Lx | L | D | P => true,
4212             _ => false
4213         }
4214     }
4215
4216     /// Checks if the value is an ASCII whitespace character:
4217     /// U+0020 SPACE, U+0009 HORIZONTAL TAB, U+000A LINE FEED,
4218     /// U+000C FORM FEED, or U+000D CARRIAGE RETURN.
4219     ///
4220     /// Rust uses the WhatWG Infra Standard's [definition of ASCII
4221     /// whitespace][infra-aw]. There are several other definitions in
4222     /// wide use. For instance, [the POSIX locale][pct] includes
4223     /// U+000B VERTICAL TAB as well as all the above characters,
4224     /// but—from the very same specification—[the default rule for
4225     /// "field splitting" in the Bourne shell][bfs] considers *only*
4226     /// SPACE, HORIZONTAL TAB, and LINE FEED as whitespace.
4227     ///
4228     /// If you are writing a program that will process an existing
4229     /// file format, check what that format's definition of whitespace is
4230     /// before using this function.
4231     ///
4232     /// [infra-aw]: https://infra.spec.whatwg.org/#ascii-whitespace
4233     /// [pct]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html#tag_07_03_01
4234     /// [bfs]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_05
4235     ///
4236     /// # Examples
4237     ///
4238     /// ```
4239     /// let uppercase_a = b'A';
4240     /// let uppercase_g = b'G';
4241     /// let a = b'a';
4242     /// let g = b'g';
4243     /// let zero = b'0';
4244     /// let percent = b'%';
4245     /// let space = b' ';
4246     /// let lf = b'\n';
4247     /// let esc = 0x1b_u8;
4248     ///
4249     /// assert!(!uppercase_a.is_ascii_whitespace());
4250     /// assert!(!uppercase_g.is_ascii_whitespace());
4251     /// assert!(!a.is_ascii_whitespace());
4252     /// assert!(!g.is_ascii_whitespace());
4253     /// assert!(!zero.is_ascii_whitespace());
4254     /// assert!(!percent.is_ascii_whitespace());
4255     /// assert!(space.is_ascii_whitespace());
4256     /// assert!(lf.is_ascii_whitespace());
4257     /// assert!(!esc.is_ascii_whitespace());
4258     /// ```
4259     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4260     #[inline]
4261     pub fn is_ascii_whitespace(&self) -> bool {
4262         if *self >= 0x80 { return false; }
4263         match ASCII_CHARACTER_CLASS[*self as usize] {
4264             Cw | W => true,
4265             _ => false
4266         }
4267     }
4268
4269     /// Checks if the value is an ASCII control character:
4270     /// U+0000 NUL ... U+001F UNIT SEPARATOR, or U+007F DELETE.
4271     /// Note that most ASCII whitespace characters are control
4272     /// characters, but SPACE is not.
4273     ///
4274     /// # Examples
4275     ///
4276     /// ```
4277     /// let uppercase_a = b'A';
4278     /// let uppercase_g = b'G';
4279     /// let a = b'a';
4280     /// let g = b'g';
4281     /// let zero = b'0';
4282     /// let percent = b'%';
4283     /// let space = b' ';
4284     /// let lf = b'\n';
4285     /// let esc = 0x1b_u8;
4286     ///
4287     /// assert!(!uppercase_a.is_ascii_control());
4288     /// assert!(!uppercase_g.is_ascii_control());
4289     /// assert!(!a.is_ascii_control());
4290     /// assert!(!g.is_ascii_control());
4291     /// assert!(!zero.is_ascii_control());
4292     /// assert!(!percent.is_ascii_control());
4293     /// assert!(!space.is_ascii_control());
4294     /// assert!(lf.is_ascii_control());
4295     /// assert!(esc.is_ascii_control());
4296     /// ```
4297     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4298     #[inline]
4299     pub fn is_ascii_control(&self) -> bool {
4300         if *self >= 0x80 { return false; }
4301         match ASCII_CHARACTER_CLASS[*self as usize] {
4302             C | Cw => true,
4303             _ => false
4304         }
4305     }
4306 }
4307
4308 #[lang = "u16"]
4309 impl u16 {
4310     uint_impl! { u16, u16, 16, 65535, "", "", 4, "0xa003", "0x3a", "0x1234", "0x3412", "0x2c48",
4311         "[0x34, 0x12]", "[0x12, 0x34]" }
4312 }
4313
4314 #[lang = "u32"]
4315 impl u32 {
4316     uint_impl! { u32, u32, 32, 4294967295, "", "", 8, "0x10000b3", "0xb301", "0x12345678",
4317         "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]", "[0x12, 0x34, 0x56, 0x78]" }
4318 }
4319
4320 #[lang = "u64"]
4321 impl u64 {
4322     uint_impl! { u64, u64, 64, 18446744073709551615, "", "", 12, "0xaa00000000006e1", "0x6e10aa",
4323         "0x1234567890123456", "0x5634129078563412", "0x6a2c48091e6a2c48",
4324         "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
4325         "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]" }
4326 }
4327
4328 #[lang = "u128"]
4329 impl u128 {
4330     uint_impl! { u128, u128, 128, 340282366920938463463374607431768211455, "", "", 16,
4331         "0x13f40000000000000000000000004f76", "0x4f7613f4", "0x12345678901234567890123456789012",
4332         "0x12907856341290785634129078563412", "0x48091e6a2c48091e6a2c48091e6a2c48",
4333         "[0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, \
4334           0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
4335         "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56, \
4336           0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12]" }
4337 }
4338
4339 #[cfg(target_pointer_width = "16")]
4340 #[lang = "usize"]
4341 impl usize {
4342     uint_impl! { usize, u16, 16, 65536, "", "", 4, "0xa003", "0x3a", "0x1234", "0x3412", "0x2c48",
4343         "[0x34, 0x12]", "[0x12, 0x34]" }
4344 }
4345 #[cfg(target_pointer_width = "32")]
4346 #[lang = "usize"]
4347 impl usize {
4348     uint_impl! { usize, u32, 32, 4294967295, "", "", 8, "0x10000b3", "0xb301", "0x12345678",
4349         "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]", "[0x12, 0x34, 0x56, 0x78]" }
4350 }
4351
4352 #[cfg(target_pointer_width = "64")]
4353 #[lang = "usize"]
4354 impl usize {
4355     uint_impl! { usize, u64, 64, 18446744073709551615, "", "", 12, "0xaa00000000006e1", "0x6e10aa",
4356         "0x1234567890123456", "0x5634129078563412", "0x6a2c48091e6a2c48",
4357         "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
4358          "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]" }
4359 }
4360
4361 /// A classification of floating point numbers.
4362 ///
4363 /// This `enum` is used as the return type for [`f32::classify`] and [`f64::classify`]. See
4364 /// their documentation for more.
4365 ///
4366 /// [`f32::classify`]: ../../std/primitive.f32.html#method.classify
4367 /// [`f64::classify`]: ../../std/primitive.f64.html#method.classify
4368 ///
4369 /// # Examples
4370 ///
4371 /// ```
4372 /// use std::num::FpCategory;
4373 /// use std::f32;
4374 ///
4375 /// let num = 12.4_f32;
4376 /// let inf = f32::INFINITY;
4377 /// let zero = 0f32;
4378 /// let sub: f32 = 1.1754942e-38;
4379 /// let nan = f32::NAN;
4380 ///
4381 /// assert_eq!(num.classify(), FpCategory::Normal);
4382 /// assert_eq!(inf.classify(), FpCategory::Infinite);
4383 /// assert_eq!(zero.classify(), FpCategory::Zero);
4384 /// assert_eq!(nan.classify(), FpCategory::Nan);
4385 /// assert_eq!(sub.classify(), FpCategory::Subnormal);
4386 /// ```
4387 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
4388 #[stable(feature = "rust1", since = "1.0.0")]
4389 pub enum FpCategory {
4390     /// "Not a Number", often obtained by dividing by zero.
4391     #[stable(feature = "rust1", since = "1.0.0")]
4392     Nan,
4393
4394     /// Positive or negative infinity.
4395     #[stable(feature = "rust1", since = "1.0.0")]
4396     Infinite,
4397
4398     /// Positive or negative zero.
4399     #[stable(feature = "rust1", since = "1.0.0")]
4400     Zero,
4401
4402     /// De-normalized floating point representation (less precise than `Normal`).
4403     #[stable(feature = "rust1", since = "1.0.0")]
4404     Subnormal,
4405
4406     /// A regular floating point number.
4407     #[stable(feature = "rust1", since = "1.0.0")]
4408     Normal,
4409 }
4410
4411 macro_rules! from_str_radix_int_impl {
4412     ($($t:ty)*) => {$(
4413         #[stable(feature = "rust1", since = "1.0.0")]
4414         impl FromStr for $t {
4415             type Err = ParseIntError;
4416             fn from_str(src: &str) -> Result<Self, ParseIntError> {
4417                 from_str_radix(src, 10)
4418             }
4419         }
4420     )*}
4421 }
4422 from_str_radix_int_impl! { isize i8 i16 i32 i64 i128 usize u8 u16 u32 u64 u128 }
4423
4424 /// The error type returned when a checked integral type conversion fails.
4425 #[unstable(feature = "try_from", issue = "33417")]
4426 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
4427 pub struct TryFromIntError(());
4428
4429 impl TryFromIntError {
4430     #[unstable(feature = "int_error_internals",
4431                reason = "available through Error trait and this method should \
4432                          not be exposed publicly",
4433                issue = "0")]
4434     #[doc(hidden)]
4435     pub fn __description(&self) -> &str {
4436         "out of range integral type conversion attempted"
4437     }
4438 }
4439
4440 #[unstable(feature = "try_from", issue = "33417")]
4441 impl fmt::Display for TryFromIntError {
4442     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
4443         self.__description().fmt(fmt)
4444     }
4445 }
4446
4447 #[unstable(feature = "try_from", issue = "33417")]
4448 impl From<!> for TryFromIntError {
4449     fn from(never: !) -> TryFromIntError {
4450         never
4451     }
4452 }
4453
4454 // no possible bounds violation
4455 macro_rules! try_from_unbounded {
4456     ($source:ty, $($target:ty),*) => {$(
4457         #[unstable(feature = "try_from", issue = "33417")]
4458         impl TryFrom<$source> for $target {
4459             type Error = TryFromIntError;
4460
4461             #[inline]
4462             fn try_from(value: $source) -> Result<Self, Self::Error> {
4463                 Ok(value as $target)
4464             }
4465         }
4466     )*}
4467 }
4468
4469 // only negative bounds
4470 macro_rules! try_from_lower_bounded {
4471     ($source:ty, $($target:ty),*) => {$(
4472         #[unstable(feature = "try_from", issue = "33417")]
4473         impl TryFrom<$source> for $target {
4474             type Error = TryFromIntError;
4475
4476             #[inline]
4477             fn try_from(u: $source) -> Result<$target, TryFromIntError> {
4478                 if u >= 0 {
4479                     Ok(u as $target)
4480                 } else {
4481                     Err(TryFromIntError(()))
4482                 }
4483             }
4484         }
4485     )*}
4486 }
4487
4488 // unsigned to signed (only positive bound)
4489 macro_rules! try_from_upper_bounded {
4490     ($source:ty, $($target:ty),*) => {$(
4491         #[unstable(feature = "try_from", issue = "33417")]
4492         impl TryFrom<$source> for $target {
4493             type Error = TryFromIntError;
4494
4495             #[inline]
4496             fn try_from(u: $source) -> Result<$target, TryFromIntError> {
4497                 if u > (<$target>::max_value() as $source) {
4498                     Err(TryFromIntError(()))
4499                 } else {
4500                     Ok(u as $target)
4501                 }
4502             }
4503         }
4504     )*}
4505 }
4506
4507 // all other cases
4508 macro_rules! try_from_both_bounded {
4509     ($source:ty, $($target:ty),*) => {$(
4510         #[unstable(feature = "try_from", issue = "33417")]
4511         impl TryFrom<$source> for $target {
4512             type Error = TryFromIntError;
4513
4514             #[inline]
4515             fn try_from(u: $source) -> Result<$target, TryFromIntError> {
4516                 let min = <$target>::min_value() as $source;
4517                 let max = <$target>::max_value() as $source;
4518                 if u < min || u > max {
4519                     Err(TryFromIntError(()))
4520                 } else {
4521                     Ok(u as $target)
4522                 }
4523             }
4524         }
4525     )*}
4526 }
4527
4528 macro_rules! rev {
4529     ($mac:ident, $source:ty, $($target:ty),*) => {$(
4530         $mac!($target, $source);
4531     )*}
4532 }
4533
4534 /// intra-sign conversions
4535 try_from_upper_bounded!(u16, u8);
4536 try_from_upper_bounded!(u32, u16, u8);
4537 try_from_upper_bounded!(u64, u32, u16, u8);
4538 try_from_upper_bounded!(u128, u64, u32, u16, u8);
4539
4540 try_from_both_bounded!(i16, i8);
4541 try_from_both_bounded!(i32, i16, i8);
4542 try_from_both_bounded!(i64, i32, i16, i8);
4543 try_from_both_bounded!(i128, i64, i32, i16, i8);
4544
4545 // unsigned-to-signed
4546 try_from_upper_bounded!(u8, i8);
4547 try_from_upper_bounded!(u16, i8, i16);
4548 try_from_upper_bounded!(u32, i8, i16, i32);
4549 try_from_upper_bounded!(u64, i8, i16, i32, i64);
4550 try_from_upper_bounded!(u128, i8, i16, i32, i64, i128);
4551
4552 // signed-to-unsigned
4553 try_from_lower_bounded!(i8, u8, u16, u32, u64, u128);
4554 try_from_lower_bounded!(i16, u16, u32, u64, u128);
4555 try_from_lower_bounded!(i32, u32, u64, u128);
4556 try_from_lower_bounded!(i64, u64, u128);
4557 try_from_lower_bounded!(i128, u128);
4558 try_from_both_bounded!(i16, u8);
4559 try_from_both_bounded!(i32, u16, u8);
4560 try_from_both_bounded!(i64, u32, u16, u8);
4561 try_from_both_bounded!(i128, u64, u32, u16, u8);
4562
4563 // usize/isize
4564 try_from_upper_bounded!(usize, isize);
4565 try_from_lower_bounded!(isize, usize);
4566
4567 #[cfg(target_pointer_width = "16")]
4568 mod ptr_try_from_impls {
4569     use super::TryFromIntError;
4570     use convert::TryFrom;
4571
4572     try_from_upper_bounded!(usize, u8);
4573     try_from_unbounded!(usize, u16, u32, u64, u128);
4574     try_from_upper_bounded!(usize, i8, i16);
4575     try_from_unbounded!(usize, i32, i64, i128);
4576
4577     try_from_both_bounded!(isize, u8);
4578     try_from_lower_bounded!(isize, u16, u32, u64, u128);
4579     try_from_both_bounded!(isize, i8);
4580     try_from_unbounded!(isize, i16, i32, i64, i128);
4581
4582     rev!(try_from_upper_bounded, usize, u32, u64, u128);
4583     rev!(try_from_lower_bounded, usize, i8, i16);
4584     rev!(try_from_both_bounded, usize, i32, i64, i128);
4585
4586     rev!(try_from_upper_bounded, isize, u16, u32, u64, u128);
4587     rev!(try_from_both_bounded, isize, i32, i64, i128);
4588 }
4589
4590 #[cfg(target_pointer_width = "32")]
4591 mod ptr_try_from_impls {
4592     use super::TryFromIntError;
4593     use convert::TryFrom;
4594
4595     try_from_upper_bounded!(usize, u8, u16);
4596     try_from_unbounded!(usize, u32, u64, u128);
4597     try_from_upper_bounded!(usize, i8, i16, i32);
4598     try_from_unbounded!(usize, i64, i128);
4599
4600     try_from_both_bounded!(isize, u8, u16);
4601     try_from_lower_bounded!(isize, u32, u64, u128);
4602     try_from_both_bounded!(isize, i8, i16);
4603     try_from_unbounded!(isize, i32, i64, i128);
4604
4605     rev!(try_from_unbounded, usize, u32);
4606     rev!(try_from_upper_bounded, usize, u64, u128);
4607     rev!(try_from_lower_bounded, usize, i8, i16, i32);
4608     rev!(try_from_both_bounded, usize, i64, i128);
4609
4610     rev!(try_from_unbounded, isize, u16);
4611     rev!(try_from_upper_bounded, isize, u32, u64, u128);
4612     rev!(try_from_unbounded, isize, i32);
4613     rev!(try_from_both_bounded, isize, i64, i128);
4614 }
4615
4616 #[cfg(target_pointer_width = "64")]
4617 mod ptr_try_from_impls {
4618     use super::TryFromIntError;
4619     use convert::TryFrom;
4620
4621     try_from_upper_bounded!(usize, u8, u16, u32);
4622     try_from_unbounded!(usize, u64, u128);
4623     try_from_upper_bounded!(usize, i8, i16, i32, i64);
4624     try_from_unbounded!(usize, i128);
4625
4626     try_from_both_bounded!(isize, u8, u16, u32);
4627     try_from_lower_bounded!(isize, u64, u128);
4628     try_from_both_bounded!(isize, i8, i16, i32);
4629     try_from_unbounded!(isize, i64, i128);
4630
4631     rev!(try_from_unbounded, usize, u32, u64);
4632     rev!(try_from_upper_bounded, usize, u128);
4633     rev!(try_from_lower_bounded, usize, i8, i16, i32, i64);
4634     rev!(try_from_both_bounded, usize, i128);
4635
4636     rev!(try_from_unbounded, isize, u16, u32);
4637     rev!(try_from_upper_bounded, isize, u64, u128);
4638     rev!(try_from_unbounded, isize, i32, i64);
4639     rev!(try_from_both_bounded, isize, i128);
4640 }
4641
4642 #[doc(hidden)]
4643 trait FromStrRadixHelper: PartialOrd + Copy {
4644     fn min_value() -> Self;
4645     fn max_value() -> Self;
4646     fn from_u32(u: u32) -> Self;
4647     fn checked_mul(&self, other: u32) -> Option<Self>;
4648     fn checked_sub(&self, other: u32) -> Option<Self>;
4649     fn checked_add(&self, other: u32) -> Option<Self>;
4650 }
4651
4652 macro_rules! doit {
4653     ($($t:ty)*) => ($(impl FromStrRadixHelper for $t {
4654         #[inline]
4655         fn min_value() -> Self { Self::min_value() }
4656         #[inline]
4657         fn max_value() -> Self { Self::max_value() }
4658         #[inline]
4659         fn from_u32(u: u32) -> Self { u as Self }
4660         #[inline]
4661         fn checked_mul(&self, other: u32) -> Option<Self> {
4662             Self::checked_mul(*self, other as Self)
4663         }
4664         #[inline]
4665         fn checked_sub(&self, other: u32) -> Option<Self> {
4666             Self::checked_sub(*self, other as Self)
4667         }
4668         #[inline]
4669         fn checked_add(&self, other: u32) -> Option<Self> {
4670             Self::checked_add(*self, other as Self)
4671         }
4672     })*)
4673 }
4674 doit! { i8 i16 i32 i64 i128 isize u8 u16 u32 u64 u128 usize }
4675
4676 fn from_str_radix<T: FromStrRadixHelper>(src: &str, radix: u32) -> Result<T, ParseIntError> {
4677     use self::IntErrorKind::*;
4678     use self::ParseIntError as PIE;
4679
4680     assert!(radix >= 2 && radix <= 36,
4681            "from_str_radix_int: must lie in the range `[2, 36]` - found {}",
4682            radix);
4683
4684     if src.is_empty() {
4685         return Err(PIE { kind: Empty });
4686     }
4687
4688     let is_signed_ty = T::from_u32(0) > T::min_value();
4689
4690     // all valid digits are ascii, so we will just iterate over the utf8 bytes
4691     // and cast them to chars. .to_digit() will safely return None for anything
4692     // other than a valid ascii digit for the given radix, including the first-byte
4693     // of multi-byte sequences
4694     let src = src.as_bytes();
4695
4696     let (is_positive, digits) = match src[0] {
4697         b'+' => (true, &src[1..]),
4698         b'-' if is_signed_ty => (false, &src[1..]),
4699         _ => (true, src),
4700     };
4701
4702     if digits.is_empty() {
4703         return Err(PIE { kind: Empty });
4704     }
4705
4706     let mut result = T::from_u32(0);
4707     if is_positive {
4708         // The number is positive
4709         for &c in digits {
4710             let x = match (c as char).to_digit(radix) {
4711                 Some(x) => x,
4712                 None => return Err(PIE { kind: InvalidDigit }),
4713             };
4714             result = match result.checked_mul(radix) {
4715                 Some(result) => result,
4716                 None => return Err(PIE { kind: Overflow }),
4717             };
4718             result = match result.checked_add(x) {
4719                 Some(result) => result,
4720                 None => return Err(PIE { kind: Overflow }),
4721             };
4722         }
4723     } else {
4724         // The number is negative
4725         for &c in digits {
4726             let x = match (c as char).to_digit(radix) {
4727                 Some(x) => x,
4728                 None => return Err(PIE { kind: InvalidDigit }),
4729             };
4730             result = match result.checked_mul(radix) {
4731                 Some(result) => result,
4732                 None => return Err(PIE { kind: Underflow }),
4733             };
4734             result = match result.checked_sub(x) {
4735                 Some(result) => result,
4736                 None => return Err(PIE { kind: Underflow }),
4737             };
4738         }
4739     }
4740     Ok(result)
4741 }
4742
4743 /// An error which can be returned when parsing an integer.
4744 ///
4745 /// This error is used as the error type for the `from_str_radix()` functions
4746 /// on the primitive integer types, such as [`i8::from_str_radix`].
4747 ///
4748 /// # Potential causes
4749 ///
4750 /// Among other causes, `ParseIntError` can be thrown because of leading or trailing whitespace
4751 /// in the string e.g. when it is obtained from the standard input.
4752 /// Using the [`str.trim()`] method ensures that no whitespace remains before parsing.
4753 ///
4754 /// [`str.trim()`]: ../../std/primitive.str.html#method.trim
4755 /// [`i8::from_str_radix`]: ../../std/primitive.i8.html#method.from_str_radix
4756 #[derive(Debug, Clone, PartialEq, Eq)]
4757 #[stable(feature = "rust1", since = "1.0.0")]
4758 pub struct ParseIntError {
4759     kind: IntErrorKind,
4760 }
4761
4762 /// Enum to store the various types of errors that can cause parsing an integer to fail.
4763 #[unstable(feature = "int_error_matching",
4764            reason = "it can be useful to match errors when making error messages \
4765                      for integer parsing",
4766            issue = "22639")]
4767 #[derive(Debug, Clone, PartialEq, Eq)]
4768 #[non_exhaustive]
4769 pub enum IntErrorKind {
4770     /// Value being parsed is empty.
4771     ///
4772     /// Among other causes, this variant will be constructed when parsing an empty string.
4773     Empty,
4774     /// Contains an invalid digit.
4775     ///
4776     /// Among other causes, this variant will be constructed when parsing a string that
4777     /// contains a letter.
4778     InvalidDigit,
4779     /// Integer is too large to store in target integer type.
4780     Overflow,
4781     /// Integer is too small to store in target integer type.
4782     Underflow,
4783 }
4784
4785 impl ParseIntError {
4786     /// Outputs the detailed cause of parsing an integer failing.
4787     #[unstable(feature = "int_error_matching",
4788                reason = "it can be useful to match errors when making error messages \
4789                          for integer parsing",
4790                issue = "22639")]
4791     pub fn kind(&self) -> &IntErrorKind {
4792         &self.kind
4793     }
4794     #[unstable(feature = "int_error_internals",
4795                reason = "available through Error trait and this method should \
4796                          not be exposed publicly",
4797                issue = "0")]
4798     #[doc(hidden)]
4799     pub fn __description(&self) -> &str {
4800         match self.kind {
4801             IntErrorKind::Empty => "cannot parse integer from empty string",
4802             IntErrorKind::InvalidDigit => "invalid digit found in string",
4803             IntErrorKind::Overflow => "number too large to fit in target type",
4804             IntErrorKind::Underflow => "number too small to fit in target type",
4805         }
4806     }
4807 }
4808
4809 #[stable(feature = "rust1", since = "1.0.0")]
4810 impl fmt::Display for ParseIntError {
4811     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
4812         self.__description().fmt(f)
4813     }
4814 }
4815
4816 #[stable(feature = "rust1", since = "1.0.0")]
4817 pub use num::dec2flt::ParseFloatError;
4818
4819 // Conversion traits for primitive integer and float types
4820 // Conversions T -> T are covered by a blanket impl and therefore excluded
4821 // Some conversions from and to usize/isize are not implemented due to portability concerns
4822 macro_rules! impl_from {
4823     ($Small: ty, $Large: ty, #[$attr:meta], $doc: expr) => {
4824         #[$attr]
4825         #[doc = $doc]
4826         impl From<$Small> for $Large {
4827             #[inline]
4828             fn from(small: $Small) -> $Large {
4829                 small as $Large
4830             }
4831         }
4832     };
4833     ($Small: ty, $Large: ty, #[$attr:meta]) => {
4834         impl_from!($Small,
4835                    $Large,
4836                    #[$attr],
4837                    concat!("Converts `",
4838                            stringify!($Small),
4839                            "` to `",
4840                            stringify!($Large),
4841                            "` losslessly."));
4842     }
4843 }
4844
4845 macro_rules! impl_from_bool {
4846     ($target: ty, #[$attr:meta]) => {
4847         impl_from!(bool, $target, #[$attr], concat!("Converts a `bool` to a `",
4848             stringify!($target), "`. The resulting value is `0` for `false` and `1` for `true`
4849 values.
4850
4851 # Examples
4852
4853 ```
4854 assert_eq!(", stringify!($target), "::from(true), 1);
4855 assert_eq!(", stringify!($target), "::from(false), 0);
4856 ```"));
4857     };
4858 }
4859
4860 // Bool -> Any
4861 impl_from_bool! { u8, #[stable(feature = "from_bool", since = "1.28.0")] }
4862 impl_from_bool! { u16, #[stable(feature = "from_bool", since = "1.28.0")] }
4863 impl_from_bool! { u32, #[stable(feature = "from_bool", since = "1.28.0")] }
4864 impl_from_bool! { u64, #[stable(feature = "from_bool", since = "1.28.0")] }
4865 impl_from_bool! { u128, #[stable(feature = "from_bool", since = "1.28.0")] }
4866 impl_from_bool! { usize, #[stable(feature = "from_bool", since = "1.28.0")] }
4867 impl_from_bool! { i8, #[stable(feature = "from_bool", since = "1.28.0")] }
4868 impl_from_bool! { i16, #[stable(feature = "from_bool", since = "1.28.0")] }
4869 impl_from_bool! { i32, #[stable(feature = "from_bool", since = "1.28.0")] }
4870 impl_from_bool! { i64, #[stable(feature = "from_bool", since = "1.28.0")] }
4871 impl_from_bool! { i128, #[stable(feature = "from_bool", since = "1.28.0")] }
4872 impl_from_bool! { isize, #[stable(feature = "from_bool", since = "1.28.0")] }
4873
4874 // Unsigned -> Unsigned
4875 impl_from! { u8, u16, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
4876 impl_from! { u8, u32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
4877 impl_from! { u8, u64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
4878 impl_from! { u8, u128, #[stable(feature = "i128", since = "1.26.0")] }
4879 impl_from! { u8, usize, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
4880 impl_from! { u16, u32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
4881 impl_from! { u16, u64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
4882 impl_from! { u16, u128, #[stable(feature = "i128", since = "1.26.0")] }
4883 impl_from! { u32, u64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
4884 impl_from! { u32, u128, #[stable(feature = "i128", since = "1.26.0")] }
4885 impl_from! { u64, u128, #[stable(feature = "i128", since = "1.26.0")] }
4886
4887 // Signed -> Signed
4888 impl_from! { i8, i16, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
4889 impl_from! { i8, i32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
4890 impl_from! { i8, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
4891 impl_from! { i8, i128, #[stable(feature = "i128", since = "1.26.0")] }
4892 impl_from! { i8, isize, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
4893 impl_from! { i16, i32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
4894 impl_from! { i16, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
4895 impl_from! { i16, i128, #[stable(feature = "i128", since = "1.26.0")] }
4896 impl_from! { i32, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
4897 impl_from! { i32, i128, #[stable(feature = "i128", since = "1.26.0")] }
4898 impl_from! { i64, i128, #[stable(feature = "i128", since = "1.26.0")] }
4899
4900 // Unsigned -> Signed
4901 impl_from! { u8, i16, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
4902 impl_from! { u8, i32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
4903 impl_from! { u8, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
4904 impl_from! { u8, i128, #[stable(feature = "i128", since = "1.26.0")] }
4905 impl_from! { u16, i32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
4906 impl_from! { u16, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
4907 impl_from! { u16, i128, #[stable(feature = "i128", since = "1.26.0")] }
4908 impl_from! { u32, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
4909 impl_from! { u32, i128, #[stable(feature = "i128", since = "1.26.0")] }
4910 impl_from! { u64, i128, #[stable(feature = "i128", since = "1.26.0")] }
4911
4912 // The C99 standard defines bounds on INTPTR_MIN, INTPTR_MAX, and UINTPTR_MAX
4913 // which imply that pointer-sized integers must be at least 16 bits:
4914 // https://port70.net/~nsz/c/c99/n1256.html#7.18.2.4
4915 impl_from! { u16, usize, #[stable(feature = "lossless_iusize_conv", since = "1.26.0")] }
4916 impl_from! { u8, isize, #[stable(feature = "lossless_iusize_conv", since = "1.26.0")] }
4917 impl_from! { i16, isize, #[stable(feature = "lossless_iusize_conv", since = "1.26.0")] }
4918
4919 // RISC-V defines the possibility of a 128-bit address space (RV128).
4920
4921 // CHERI proposes 256-bit “capabilities”. Unclear if this would be relevant to usize/isize.
4922 // https://www.cl.cam.ac.uk/research/security/ctsrd/pdfs/20171017a-cheri-poster.pdf
4923 // http://www.csl.sri.com/users/neumann/2012resolve-cheri.pdf
4924
4925
4926 // Note: integers can only be represented with full precision in a float if
4927 // they fit in the significand, which is 24 bits in f32 and 53 bits in f64.
4928 // Lossy float conversions are not implemented at this time.
4929
4930 // Signed -> Float
4931 impl_from! { i8, f32, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
4932 impl_from! { i8, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
4933 impl_from! { i16, f32, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
4934 impl_from! { i16, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
4935 impl_from! { i32, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
4936
4937 // Unsigned -> Float
4938 impl_from! { u8, f32, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
4939 impl_from! { u8, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
4940 impl_from! { u16, f32, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
4941 impl_from! { u16, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
4942 impl_from! { u32, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
4943
4944 // Float -> Float
4945 impl_from! { f32, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
4946
4947 static ASCII_LOWERCASE_MAP: [u8; 256] = [
4948     0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
4949     0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
4950     0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
4951     0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
4952     b' ', b'!', b'"', b'#', b'$', b'%', b'&', b'\'',
4953     b'(', b')', b'*', b'+', b',', b'-', b'.', b'/',
4954     b'0', b'1', b'2', b'3', b'4', b'5', b'6', b'7',
4955     b'8', b'9', b':', b';', b'<', b'=', b'>', b'?',
4956     b'@',
4957
4958           b'a', b'b', b'c', b'd', b'e', b'f', b'g',
4959     b'h', b'i', b'j', b'k', b'l', b'm', b'n', b'o',
4960     b'p', b'q', b'r', b's', b't', b'u', b'v', b'w',
4961     b'x', b'y', b'z',
4962
4963                       b'[', b'\\', b']', b'^', b'_',
4964     b'`', b'a', b'b', b'c', b'd', b'e', b'f', b'g',
4965     b'h', b'i', b'j', b'k', b'l', b'm', b'n', b'o',
4966     b'p', b'q', b'r', b's', b't', b'u', b'v', b'w',
4967     b'x', b'y', b'z', b'{', b'|', b'}', b'~', 0x7f,
4968     0x80, 0x81, 0x82, 0x83, 0x84, 0x85, 0x86, 0x87,
4969     0x88, 0x89, 0x8a, 0x8b, 0x8c, 0x8d, 0x8e, 0x8f,
4970     0x90, 0x91, 0x92, 0x93, 0x94, 0x95, 0x96, 0x97,
4971     0x98, 0x99, 0x9a, 0x9b, 0x9c, 0x9d, 0x9e, 0x9f,
4972     0xa0, 0xa1, 0xa2, 0xa3, 0xa4, 0xa5, 0xa6, 0xa7,
4973     0xa8, 0xa9, 0xaa, 0xab, 0xac, 0xad, 0xae, 0xaf,
4974     0xb0, 0xb1, 0xb2, 0xb3, 0xb4, 0xb5, 0xb6, 0xb7,
4975     0xb8, 0xb9, 0xba, 0xbb, 0xbc, 0xbd, 0xbe, 0xbf,
4976     0xc0, 0xc1, 0xc2, 0xc3, 0xc4, 0xc5, 0xc6, 0xc7,
4977     0xc8, 0xc9, 0xca, 0xcb, 0xcc, 0xcd, 0xce, 0xcf,
4978     0xd0, 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7,
4979     0xd8, 0xd9, 0xda, 0xdb, 0xdc, 0xdd, 0xde, 0xdf,
4980     0xe0, 0xe1, 0xe2, 0xe3, 0xe4, 0xe5, 0xe6, 0xe7,
4981     0xe8, 0xe9, 0xea, 0xeb, 0xec, 0xed, 0xee, 0xef,
4982     0xf0, 0xf1, 0xf2, 0xf3, 0xf4, 0xf5, 0xf6, 0xf7,
4983     0xf8, 0xf9, 0xfa, 0xfb, 0xfc, 0xfd, 0xfe, 0xff,
4984 ];
4985
4986 static ASCII_UPPERCASE_MAP: [u8; 256] = [
4987     0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
4988     0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
4989     0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
4990     0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
4991     b' ', b'!', b'"', b'#', b'$', b'%', b'&', b'\'',
4992     b'(', b')', b'*', b'+', b',', b'-', b'.', b'/',
4993     b'0', b'1', b'2', b'3', b'4', b'5', b'6', b'7',
4994     b'8', b'9', b':', b';', b'<', b'=', b'>', b'?',
4995     b'@', b'A', b'B', b'C', b'D', b'E', b'F', b'G',
4996     b'H', b'I', b'J', b'K', b'L', b'M', b'N', b'O',
4997     b'P', b'Q', b'R', b'S', b'T', b'U', b'V', b'W',
4998     b'X', b'Y', b'Z', b'[', b'\\', b']', b'^', b'_',
4999     b'`',
5000
5001           b'A', b'B', b'C', b'D', b'E', b'F', b'G',
5002     b'H', b'I', b'J', b'K', b'L', b'M', b'N', b'O',
5003     b'P', b'Q', b'R', b'S', b'T', b'U', b'V', b'W',
5004     b'X', b'Y', b'Z',
5005
5006                       b'{', b'|', b'}', b'~', 0x7f,
5007     0x80, 0x81, 0x82, 0x83, 0x84, 0x85, 0x86, 0x87,
5008     0x88, 0x89, 0x8a, 0x8b, 0x8c, 0x8d, 0x8e, 0x8f,
5009     0x90, 0x91, 0x92, 0x93, 0x94, 0x95, 0x96, 0x97,
5010     0x98, 0x99, 0x9a, 0x9b, 0x9c, 0x9d, 0x9e, 0x9f,
5011     0xa0, 0xa1, 0xa2, 0xa3, 0xa4, 0xa5, 0xa6, 0xa7,
5012     0xa8, 0xa9, 0xaa, 0xab, 0xac, 0xad, 0xae, 0xaf,
5013     0xb0, 0xb1, 0xb2, 0xb3, 0xb4, 0xb5, 0xb6, 0xb7,
5014     0xb8, 0xb9, 0xba, 0xbb, 0xbc, 0xbd, 0xbe, 0xbf,
5015     0xc0, 0xc1, 0xc2, 0xc3, 0xc4, 0xc5, 0xc6, 0xc7,
5016     0xc8, 0xc9, 0xca, 0xcb, 0xcc, 0xcd, 0xce, 0xcf,
5017     0xd0, 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7,
5018     0xd8, 0xd9, 0xda, 0xdb, 0xdc, 0xdd, 0xde, 0xdf,
5019     0xe0, 0xe1, 0xe2, 0xe3, 0xe4, 0xe5, 0xe6, 0xe7,
5020     0xe8, 0xe9, 0xea, 0xeb, 0xec, 0xed, 0xee, 0xef,
5021     0xf0, 0xf1, 0xf2, 0xf3, 0xf4, 0xf5, 0xf6, 0xf7,
5022     0xf8, 0xf9, 0xfa, 0xfb, 0xfc, 0xfd, 0xfe, 0xff,
5023 ];
5024
5025 enum AsciiCharacterClass {
5026     C,  // control
5027     Cw, // control whitespace
5028     W,  // whitespace
5029     D,  // digit
5030     L,  // lowercase
5031     Lx, // lowercase hex digit
5032     U,  // uppercase
5033     Ux, // uppercase hex digit
5034     P,  // punctuation
5035 }
5036 use self::AsciiCharacterClass::*;
5037
5038 static ASCII_CHARACTER_CLASS: [AsciiCharacterClass; 128] = [
5039 //  _0 _1 _2 _3 _4 _5 _6 _7 _8 _9 _a _b _c _d _e _f
5040     C, C, C, C, C, C, C, C, C, Cw,Cw,C, Cw,Cw,C, C, // 0_
5041     C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, // 1_
5042     W, P, P, P, P, P, P, P, P, P, P, P, P, P, P, P, // 2_
5043     D, D, D, D, D, D, D, D, D, D, P, P, P, P, P, P, // 3_
5044     P, Ux,Ux,Ux,Ux,Ux,Ux,U, U, U, U, U, U, U, U, U, // 4_
5045     U, U, U, U, U, U, U, U, U, U, U, P, P, P, P, P, // 5_
5046     P, Lx,Lx,Lx,Lx,Lx,Lx,L, L, L, L, L, L, L, L, L, // 6_
5047     L, L, L, L, L, L, L, L, L, L, L, P, P, P, P, C, // 7_
5048 ];