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 str::FromStr;
  19
  20 /// Provides intentionally-wrapped arithmetic on `T`.
  21 ///
  22 /// Operations like `+` on `u32` values is intended to never overflow,
  23 /// and in some debug configurations overflow is detected and results
  24 /// in a panic. While most arithmetic falls into this category, some
  25 /// code explicitly expects and relies upon modular arithmetic (e.g.,
  26 /// hashing).
  27 ///
  28 /// Wrapping arithmetic can be achieved either through methods like
  29 /// `wrapping_add`, or through the `Wrapping<T>` type, which says that
  30 /// all standard arithmetic operations on the underlying value are
  31 /// intended to have wrapping semantics.
  32 ///
  33 /// # Examples
  34 ///
  35 /// ```
  36 /// use std::num::Wrapping;
  37 ///
  38 /// let zero = Wrapping(0u32);
  39 /// let one = Wrapping(1u32);
  40 ///
  41 /// assert_eq!(std::u32::MAX, (zero - one).0);
  42 /// ```
  43 #[stable(feature = "rust1", since = "1.0.0")]
  44 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Copy, Default, Hash)]
  45 pub struct Wrapping<T>(#[stable(feature = "rust1", since = "1.0.0")]
  46                        pub T);
  47
  48 #[stable(feature = "rust1", since = "1.0.0")]
  49 impl<T: fmt::Debug> fmt::Debug for Wrapping<T> {
  50     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
  51         self.0.fmt(f)
  52     }
  53 }
  54
  55 #[stable(feature = "wrapping_display", since = "1.10.0")]
  56 impl<T: fmt::Display> fmt::Display for Wrapping<T> {
  57     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
  58         self.0.fmt(f)
  59     }
  60 }
  61
  62 #[stable(feature = "wrapping_fmt", since = "1.11.0")]
  63 impl<T: fmt::Binary> fmt::Binary for Wrapping<T> {
  64     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
  65         self.0.fmt(f)
  66     }
  67 }
  68
  69 #[stable(feature = "wrapping_fmt", since = "1.11.0")]
  70 impl<T: fmt::Octal> fmt::Octal for Wrapping<T> {
  71     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
  72         self.0.fmt(f)
  73     }
  74 }
  75
  76 #[stable(feature = "wrapping_fmt", since = "1.11.0")]
  77 impl<T: fmt::LowerHex> fmt::LowerHex for Wrapping<T> {
  78     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
  79         self.0.fmt(f)
  80     }
  81 }
  82
  83 #[stable(feature = "wrapping_fmt", since = "1.11.0")]
  84 impl<T: fmt::UpperHex> fmt::UpperHex for Wrapping<T> {
  85     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
  86         self.0.fmt(f)
  87     }
  88 }
  89
  90 mod wrapping;
  91
  92 // All these modules are technically private and only exposed for coretests:
  93 pub mod flt2dec;
  94 pub mod dec2flt;
  95 pub mod bignum;
  96 pub mod diy_float;
  97
  98 // `Int` + `SignedInt` implemented for signed integers
  99 macro_rules! int_impl {
 100     ($SelfT:ty, $ActualT:ident, $UnsignedT:ty, $BITS:expr,
 101      $add_with_overflow:path,
 102      $sub_with_overflow:path,
 103      $mul_with_overflow:path) => {
 104         /// Returns the smallest value that can be represented by this integer type.
 105         ///
 106         /// # Examples
 107         ///
 108         /// ```
 109         /// assert_eq!(i8::min_value(), -128);
 110         /// ```
 111         #[stable(feature = "rust1", since = "1.0.0")]
 112         #[inline]
 113         pub const fn min_value() -> Self {
 114             !0 ^ ((!0 as $UnsignedT) >> 1) as Self
 115         }
 116
 117         /// Returns the largest value that can be represented by this integer type.
 118         ///
 119         /// # Examples
 120         ///
 121         /// ```
 122         /// assert_eq!(i8::max_value(), 127);
 123         /// ```
 124         #[stable(feature = "rust1", since = "1.0.0")]
 125         #[inline]
 126         pub const fn max_value() -> Self {
 127             !Self::min_value()
 128         }
 129
 130         /// Converts a string slice in a given base to an integer.
 131         ///
 132         /// Leading and trailing whitespace represent an error.
 133         ///
 134         /// # Examples
 135         ///
 136         /// Basic usage:
 137         ///
 138         /// ```
 139         /// assert_eq!(i32::from_str_radix("A", 16), Ok(10));
 140         /// ```
 141         #[stable(feature = "rust1", since = "1.0.0")]
 142         pub fn from_str_radix(src: &str, radix: u32) -> Result<Self, ParseIntError> {
 143             from_str_radix(src, radix)
 144         }
 145
 146         /// Returns the number of ones in the binary representation of `self`.
 147         ///
 148         /// # Examples
 149         ///
 150         /// Basic usage:
 151         ///
 152         /// ```
 153         /// let n = -0b1000_0000i8;
 154         ///
 155         /// assert_eq!(n.count_ones(), 1);
 156         /// ```
 157         #[stable(feature = "rust1", since = "1.0.0")]
 158         #[inline]
 159         pub fn count_ones(self) -> u32 { (self as $UnsignedT).count_ones() }
 160
 161         /// Returns the number of zeros in the binary representation of `self`.
 162         ///
 163         /// # Examples
 164         ///
 165         /// Basic usage:
 166         ///
 167         /// ```
 168         /// let n = -0b1000_0000i8;
 169         ///
 170         /// assert_eq!(n.count_zeros(), 7);
 171         /// ```
 172         #[stable(feature = "rust1", since = "1.0.0")]
 173         #[inline]
 174         pub fn count_zeros(self) -> u32 {
 175             (!self).count_ones()
 176         }
 177
 178         /// Returns the number of leading zeros in the binary representation
 179         /// of `self`.
 180         ///
 181         /// # Examples
 182         ///
 183         /// Basic usage:
 184         ///
 185         /// ```
 186         /// let n = -1i16;
 187         ///
 188         /// assert_eq!(n.leading_zeros(), 0);
 189         /// ```
 190         #[stable(feature = "rust1", since = "1.0.0")]
 191         #[inline]
 192         pub fn leading_zeros(self) -> u32 {
 193             (self as $UnsignedT).leading_zeros()
 194         }
 195
 196         /// Returns the number of trailing zeros in the binary representation
 197         /// of `self`.
 198         ///
 199         /// # Examples
 200         ///
 201         /// Basic usage:
 202         ///
 203         /// ```
 204         /// let n = -4i8;
 205         ///
 206         /// assert_eq!(n.trailing_zeros(), 2);
 207         /// ```
 208         #[stable(feature = "rust1", since = "1.0.0")]
 209         #[inline]
 210         pub fn trailing_zeros(self) -> u32 {
 211             (self as $UnsignedT).trailing_zeros()
 212         }
 213
 214         /// Shifts the bits to the left by a specified amount, `n`,
 215         /// wrapping the truncated bits to the end of the resulting integer.
 216         ///
 217         /// Please note this isn't the same operation as `<<`!
 218         ///
 219         /// # Examples
 220         ///
 221         /// Basic usage:
 222         ///
 223         /// ```
 224         /// let n = 0x0123456789ABCDEFi64;
 225         /// let m = -0x76543210FEDCBA99i64;
 226         ///
 227         /// assert_eq!(n.rotate_left(32), m);
 228         /// ```
 229         #[stable(feature = "rust1", since = "1.0.0")]
 230         #[inline]
 231         pub fn rotate_left(self, n: u32) -> Self {
 232             (self as $UnsignedT).rotate_left(n) as Self
 233         }
 234
 235         /// Shifts the bits to the right by a specified amount, `n`,
 236         /// wrapping the truncated bits to the beginning of the resulting
 237         /// integer.
 238         ///
 239         /// Please note this isn't the same operation as `>>`!
 240         ///
 241         /// # Examples
 242         ///
 243         /// Basic usage:
 244         ///
 245         /// ```
 246         /// let n = 0x0123456789ABCDEFi64;
 247         /// let m = -0xFEDCBA987654322i64;
 248         ///
 249         /// assert_eq!(n.rotate_right(4), m);
 250         /// ```
 251         #[stable(feature = "rust1", since = "1.0.0")]
 252         #[inline]
 253         pub fn rotate_right(self, n: u32) -> Self {
 254             (self as $UnsignedT).rotate_right(n) as Self
 255         }
 256
 257         /// Reverses the byte order of the integer.
 258         ///
 259         /// # Examples
 260         ///
 261         /// Basic usage:
 262         ///
 263         /// ```
 264         /// let n =  0x0123456789ABCDEFi64;
 265         /// let m = -0x1032547698BADCFFi64;
 266         ///
 267         /// assert_eq!(n.swap_bytes(), m);
 268         /// ```
 269         #[stable(feature = "rust1", since = "1.0.0")]
 270         #[inline]
 271         pub fn swap_bytes(self) -> Self {
 272             (self as $UnsignedT).swap_bytes() as Self
 273         }
 274
 275         /// Converts an integer from big endian to the target's endianness.
 276         ///
 277         /// On big endian this is a no-op. On little endian the bytes are
 278         /// swapped.
 279         ///
 280         /// # Examples
 281         ///
 282         /// Basic usage:
 283         ///
 284         /// ```
 285         /// let n = 0x0123456789ABCDEFi64;
 286         ///
 287         /// if cfg!(target_endian = "big") {
 288         ///     assert_eq!(i64::from_be(n), n)
 289         /// } else {
 290         ///     assert_eq!(i64::from_be(n), n.swap_bytes())
 291         /// }
 292         /// ```
 293         #[stable(feature = "rust1", since = "1.0.0")]
 294         #[inline]
 295         pub fn from_be(x: Self) -> Self {
 296             if cfg!(target_endian = "big") { x } else { x.swap_bytes() }
 297         }
 298
 299         /// Converts an integer from little endian to the target's endianness.
 300         ///
 301         /// On little endian this is a no-op. On big endian the bytes are
 302         /// swapped.
 303         ///
 304         /// # Examples
 305         ///
 306         /// Basic usage:
 307         ///
 308         /// ```
 309         /// let n = 0x0123456789ABCDEFi64;
 310         ///
 311         /// if cfg!(target_endian = "little") {
 312         ///     assert_eq!(i64::from_le(n), n)
 313         /// } else {
 314         ///     assert_eq!(i64::from_le(n), n.swap_bytes())
 315         /// }
 316         /// ```
 317         #[stable(feature = "rust1", since = "1.0.0")]
 318         #[inline]
 319         pub fn from_le(x: Self) -> Self {
 320             if cfg!(target_endian = "little") { x } else { x.swap_bytes() }
 321         }
 322
 323         /// Converts `self` to big endian from the target's endianness.
 324         ///
 325         /// On big endian this is a no-op. On little endian the bytes are
 326         /// swapped.
 327         ///
 328         /// # Examples
 329         ///
 330         /// Basic usage:
 331         ///
 332         /// ```
 333         /// let n = 0x0123456789ABCDEFi64;
 334         ///
 335         /// if cfg!(target_endian = "big") {
 336         ///     assert_eq!(n.to_be(), n)
 337         /// } else {
 338         ///     assert_eq!(n.to_be(), n.swap_bytes())
 339         /// }
 340         /// ```
 341         #[stable(feature = "rust1", since = "1.0.0")]
 342         #[inline]
 343         pub fn to_be(self) -> Self { // or not to be?
 344             if cfg!(target_endian = "big") { self } else { self.swap_bytes() }
 345         }
 346
 347         /// Converts `self` to little endian from the target's endianness.
 348         ///
 349         /// On little endian this is a no-op. On big endian the bytes are
 350         /// swapped.
 351         ///
 352         /// # Examples
 353         ///
 354         /// Basic usage:
 355         ///
 356         /// ```
 357         /// let n = 0x0123456789ABCDEFi64;
 358         ///
 359         /// if cfg!(target_endian = "little") {
 360         ///     assert_eq!(n.to_le(), n)
 361         /// } else {
 362         ///     assert_eq!(n.to_le(), n.swap_bytes())
 363         /// }
 364         /// ```
 365         #[stable(feature = "rust1", since = "1.0.0")]
 366         #[inline]
 367         pub fn to_le(self) -> Self {
 368             if cfg!(target_endian = "little") { self } else { self.swap_bytes() }
 369         }
 370
 371         /// Checked integer addition. Computes `self + other`, returning `None`
 372         /// if overflow occurred.
 373         ///
 374         /// # Examples
 375         ///
 376         /// Basic usage:
 377         ///
 378         /// ```
 379         /// assert_eq!(7i16.checked_add(32760), Some(32767));
 380         /// assert_eq!(8i16.checked_add(32760), None);
 381         /// ```
 382         #[stable(feature = "rust1", since = "1.0.0")]
 383         #[inline]
 384         pub fn checked_add(self, other: Self) -> Option<Self> {
 385             let (a, b) = self.overflowing_add(other);
 386             if b {None} else {Some(a)}
 387         }
 388
 389         /// Checked integer subtraction. Computes `self - other`, returning
 390         /// `None` if underflow occurred.
 391         ///
 392         /// # Examples
 393         ///
 394         /// Basic usage:
 395         ///
 396         /// ```
 397         /// assert_eq!((-127i8).checked_sub(1), Some(-128));
 398         /// assert_eq!((-128i8).checked_sub(1), None);
 399         /// ```
 400         #[stable(feature = "rust1", since = "1.0.0")]
 401         #[inline]
 402         pub fn checked_sub(self, other: Self) -> Option<Self> {
 403             let (a, b) = self.overflowing_sub(other);
 404             if b {None} else {Some(a)}
 405         }
 406
 407         /// Checked integer multiplication. Computes `self * other`, returning
 408         /// `None` if underflow or overflow occurred.
 409         ///
 410         /// # Examples
 411         ///
 412         /// Basic usage:
 413         ///
 414         /// ```
 415         /// assert_eq!(6i8.checked_mul(21), Some(126));
 416         /// assert_eq!(6i8.checked_mul(22), None);
 417         /// ```
 418         #[stable(feature = "rust1", since = "1.0.0")]
 419         #[inline]
 420         pub fn checked_mul(self, other: Self) -> Option<Self> {
 421             let (a, b) = self.overflowing_mul(other);
 422             if b {None} else {Some(a)}
 423         }
 424
 425         /// Checked integer division. Computes `self / other`, returning `None`
 426         /// if `other == 0` or the operation results in underflow or overflow.
 427         ///
 428         /// # Examples
 429         ///
 430         /// Basic usage:
 431         ///
 432         /// ```
 433         /// assert_eq!((-127i8).checked_div(-1), Some(127));
 434         /// assert_eq!((-128i8).checked_div(-1), None);
 435         /// assert_eq!((1i8).checked_div(0), None);
 436         /// ```
 437         #[stable(feature = "rust1", since = "1.0.0")]
 438         #[inline]
 439         pub fn checked_div(self, other: Self) -> Option<Self> {
 440             if other == 0 || (self == Self::min_value() && other == -1) {
 441                 None
 442             } else {
 443                 Some(unsafe { intrinsics::unchecked_div(self, other) })
 444             }
 445         }
 446
 447         /// Checked integer remainder. Computes `self % other`, returning `None`
 448         /// if `other == 0` or the operation results in underflow or overflow.
 449         ///
 450         /// # Examples
 451         ///
 452         /// Basic usage:
 453         ///
 454         /// ```
 455         /// use std::i32;
 456         ///
 457         /// assert_eq!(5i32.checked_rem(2), Some(1));
 458         /// assert_eq!(5i32.checked_rem(0), None);
 459         /// assert_eq!(i32::MIN.checked_rem(-1), None);
 460         /// ```
 461         #[stable(feature = "wrapping", since = "1.7.0")]
 462         #[inline]
 463         pub fn checked_rem(self, other: Self) -> Option<Self> {
 464             if other == 0 || (self == Self::min_value() && other == -1) {
 465                 None
 466             } else {
 467                 Some(unsafe { intrinsics::unchecked_rem(self, other) })
 468             }
 469         }
 470
 471         /// Checked negation. Computes `-self`, returning `None` if `self ==
 472         /// MIN`.
 473         ///
 474         /// # Examples
 475         ///
 476         /// Basic usage:
 477         ///
 478         /// ```
 479         /// use std::i32;
 480         ///
 481         /// assert_eq!(5i32.checked_neg(), Some(-5));
 482         /// assert_eq!(i32::MIN.checked_neg(), None);
 483         /// ```
 484         #[stable(feature = "wrapping", since = "1.7.0")]
 485         #[inline]
 486         pub fn checked_neg(self) -> Option<Self> {
 487             let (a, b) = self.overflowing_neg();
 488             if b {None} else {Some(a)}
 489         }
 490
 491         /// Checked shift left. Computes `self << rhs`, returning `None`
 492         /// if `rhs` is larger than or equal to the number of bits in `self`.
 493         ///
 494         /// # Examples
 495         ///
 496         /// Basic usage:
 497         ///
 498         /// ```
 499         /// assert_eq!(0x10i32.checked_shl(4), Some(0x100));
 500         /// assert_eq!(0x10i32.checked_shl(33), None);
 501         /// ```
 502         #[stable(feature = "wrapping", since = "1.7.0")]
 503         #[inline]
 504         pub fn checked_shl(self, rhs: u32) -> Option<Self> {
 505             let (a, b) = self.overflowing_shl(rhs);
 506             if b {None} else {Some(a)}
 507         }
 508
 509         /// Checked shift right. Computes `self >> rhs`, returning `None`
 510         /// if `rhs` is larger than or equal to the number of bits in `self`.
 511         ///
 512         /// # Examples
 513         ///
 514         /// Basic usage:
 515         ///
 516         /// ```
 517         /// assert_eq!(0x10i32.checked_shr(4), Some(0x1));
 518         /// assert_eq!(0x10i32.checked_shr(33), None);
 519         /// ```
 520         #[stable(feature = "wrapping", since = "1.7.0")]
 521         #[inline]
 522         pub fn checked_shr(self, rhs: u32) -> Option<Self> {
 523             let (a, b) = self.overflowing_shr(rhs);
 524             if b {None} else {Some(a)}
 525         }
 526
 527         /// Checked absolute value. Computes `self.abs()`, returning `None` if
 528         /// `self == MIN`.
 529         ///
 530         /// # Examples
 531         ///
 532         /// Basic usage:
 533         ///
 534         /// ```
 535         /// use std::i32;
 536         ///
 537         /// assert_eq!((-5i32).checked_abs(), Some(5));
 538         /// assert_eq!(i32::MIN.checked_abs(), None);
 539         /// ```
 540         #[stable(feature = "no_panic_abs", since = "1.13.0")]
 541         #[inline]
 542         pub fn checked_abs(self) -> Option<Self> {
 543             if self.is_negative() {
 544                 self.checked_neg()
 545             } else {
 546                 Some(self)
 547             }
 548         }
 549
 550         /// Saturating integer addition. Computes `self + other`, saturating at
 551         /// the numeric bounds instead of overflowing.
 552         ///
 553         /// # Examples
 554         ///
 555         /// Basic usage:
 556         ///
 557         /// ```
 558         /// assert_eq!(100i8.saturating_add(1), 101);
 559         /// assert_eq!(100i8.saturating_add(127), 127);
 560         /// ```
 561         #[stable(feature = "rust1", since = "1.0.0")]
 562         #[inline]
 563         pub fn saturating_add(self, other: Self) -> Self {
 564             match self.checked_add(other) {
 565                 Some(x) => x,
 566                 None if other >= 0 => Self::max_value(),
 567                 None => Self::min_value(),
 568             }
 569         }
 570
 571         /// Saturating integer subtraction. Computes `self - other`, saturating
 572         /// at the numeric bounds instead of overflowing.
 573         ///
 574         /// # Examples
 575         ///
 576         /// Basic usage:
 577         ///
 578         /// ```
 579         /// assert_eq!(100i8.saturating_sub(127), -27);
 580         /// assert_eq!((-100i8).saturating_sub(127), -128);
 581         /// ```
 582         #[stable(feature = "rust1", since = "1.0.0")]
 583         #[inline]
 584         pub fn saturating_sub(self, other: Self) -> Self {
 585             match self.checked_sub(other) {
 586                 Some(x) => x,
 587                 None if other >= 0 => Self::min_value(),
 588                 None => Self::max_value(),
 589             }
 590         }
 591
 592         /// Saturating integer multiplication. Computes `self * other`,
 593         /// saturating at the numeric bounds instead of overflowing.
 594         ///
 595         /// # Examples
 596         ///
 597         /// Basic usage:
 598         ///
 599         /// ```
 600         /// use std::i32;
 601         ///
 602         /// assert_eq!(100i32.saturating_mul(127), 12700);
 603         /// assert_eq!((1i32 << 23).saturating_mul(1 << 23), i32::MAX);
 604         /// assert_eq!((-1i32 << 23).saturating_mul(1 << 23), i32::MIN);
 605         /// ```
 606         #[stable(feature = "wrapping", since = "1.7.0")]
 607         #[inline]
 608         pub fn saturating_mul(self, other: Self) -> Self {
 609             self.checked_mul(other).unwrap_or_else(|| {
 610                 if (self < 0 && other < 0) || (self > 0 && other > 0) {
 611                     Self::max_value()
 612                 } else {
 613                     Self::min_value()
 614                 }
 615             })
 616         }
 617
 618         /// Wrapping (modular) addition. Computes `self + other`,
 619         /// wrapping around at the boundary of the type.
 620         ///
 621         /// # Examples
 622         ///
 623         /// Basic usage:
 624         ///
 625         /// ```
 626         /// assert_eq!(100i8.wrapping_add(27), 127);
 627         /// assert_eq!(100i8.wrapping_add(127), -29);
 628         /// ```
 629         #[stable(feature = "rust1", since = "1.0.0")]
 630         #[inline]
 631         pub fn wrapping_add(self, rhs: Self) -> Self {
 632             unsafe {
 633                 intrinsics::overflowing_add(self, rhs)
 634             }
 635         }
 636
 637         /// Wrapping (modular) subtraction. Computes `self - other`,
 638         /// wrapping around at the boundary of the type.
 639         ///
 640         /// # Examples
 641         ///
 642         /// Basic usage:
 643         ///
 644         /// ```
 645         /// assert_eq!(0i8.wrapping_sub(127), -127);
 646         /// assert_eq!((-2i8).wrapping_sub(127), 127);
 647         /// ```
 648         #[stable(feature = "rust1", since = "1.0.0")]
 649         #[inline]
 650         pub fn wrapping_sub(self, rhs: Self) -> Self {
 651             unsafe {
 652                 intrinsics::overflowing_sub(self, rhs)
 653             }
 654         }
 655
 656         /// Wrapping (modular) multiplication. Computes `self *
 657         /// other`, wrapping around at the boundary of the type.
 658         ///
 659         /// # Examples
 660         ///
 661         /// Basic usage:
 662         ///
 663         /// ```
 664         /// assert_eq!(10i8.wrapping_mul(12), 120);
 665         /// assert_eq!(11i8.wrapping_mul(12), -124);
 666         /// ```
 667         #[stable(feature = "rust1", since = "1.0.0")]
 668         #[inline]
 669         pub fn wrapping_mul(self, rhs: Self) -> Self {
 670             unsafe {
 671                 intrinsics::overflowing_mul(self, rhs)
 672             }
 673         }
 674
 675         /// Wrapping (modular) division. Computes `self / other`,
 676         /// wrapping around at the boundary of the type.
 677         ///
 678         /// The only case where such wrapping can occur is when one
 679         /// divides `MIN / -1` on a signed type (where `MIN` is the
 680         /// negative minimal value for the type); this is equivalent
 681         /// to `-MIN`, a positive value that is too large to represent
 682         /// in the type. In such a case, this function returns `MIN`
 683         /// itself.
 684         ///
 685         /// # Panics
 686         ///
 687         /// This function will panic if `rhs` is 0.
 688         ///
 689         /// # Examples
 690         ///
 691         /// Basic usage:
 692         ///
 693         /// ```
 694         /// assert_eq!(100u8.wrapping_div(10), 10);
 695         /// assert_eq!((-128i8).wrapping_div(-1), -128);
 696         /// ```
 697         #[stable(feature = "num_wrapping", since = "1.2.0")]
 698         #[inline(always)]
 699         pub fn wrapping_div(self, rhs: Self) -> Self {
 700             self.overflowing_div(rhs).0
 701         }
 702
 703         /// Wrapping (modular) remainder. Computes `self % other`,
 704         /// wrapping around at the boundary of the type.
 705         ///
 706         /// Such wrap-around never actually occurs mathematically;
 707         /// implementation artifacts make `x % y` invalid for `MIN /
 708         /// -1` on a signed type (where `MIN` is the negative
 709         /// minimal value). In such a case, this function returns `0`.
 710         ///
 711         /// # Panics
 712         ///
 713         /// This function will panic if `rhs` is 0.
 714         ///
 715         /// # Examples
 716         ///
 717         /// Basic usage:
 718         ///
 719         /// ```
 720         /// assert_eq!(100i8.wrapping_rem(10), 0);
 721         /// assert_eq!((-128i8).wrapping_rem(-1), 0);
 722         /// ```
 723         #[stable(feature = "num_wrapping", since = "1.2.0")]
 724         #[inline(always)]
 725         pub fn wrapping_rem(self, rhs: Self) -> Self {
 726             self.overflowing_rem(rhs).0
 727         }
 728
 729         /// Wrapping (modular) negation. Computes `-self`,
 730         /// wrapping around at the boundary of the type.
 731         ///
 732         /// The only case where such wrapping can occur is when one
 733         /// negates `MIN` on a signed type (where `MIN` is the
 734         /// negative minimal value for the type); this is a positive
 735         /// value that is too large to represent in the type. In such
 736         /// a case, this function returns `MIN` itself.
 737         ///
 738         /// # Examples
 739         ///
 740         /// Basic usage:
 741         ///
 742         /// ```
 743         /// assert_eq!(100i8.wrapping_neg(), -100);
 744         /// assert_eq!((-128i8).wrapping_neg(), -128);
 745         /// ```
 746         #[stable(feature = "num_wrapping", since = "1.2.0")]
 747         #[inline(always)]
 748         pub fn wrapping_neg(self) -> Self {
 749             self.overflowing_neg().0
 750         }
 751
 752         /// Panic-free bitwise shift-left; yields `self << mask(rhs)`,
 753         /// where `mask` removes any high-order bits of `rhs` that
 754         /// would cause the shift to exceed the bitwidth of the type.
 755         ///
 756         /// Note that this is *not* the same as a rotate-left; the
 757         /// RHS of a wrapping shift-left is restricted to the range
 758         /// of the type, rather than the bits shifted out of the LHS
 759         /// being returned to the other end. The primitive integer
 760         /// types all implement a `rotate_left` function, which may
 761         /// be what you want instead.
 762         ///
 763         /// # Examples
 764         ///
 765         /// Basic usage:
 766         ///
 767         /// ```
 768         /// assert_eq!((-1i8).wrapping_shl(7), -128);
 769         /// assert_eq!((-1i8).wrapping_shl(8), -1);
 770         /// ```
 771         #[stable(feature = "num_wrapping", since = "1.2.0")]
 772         #[inline(always)]
 773         pub fn wrapping_shl(self, rhs: u32) -> Self {
 774             unsafe {
 775                 intrinsics::unchecked_shl(self, (rhs & ($BITS - 1)) as $SelfT)
 776             }
 777         }
 778
 779         /// Panic-free bitwise shift-right; yields `self >> mask(rhs)`,
 780         /// where `mask` removes any high-order bits of `rhs` that
 781         /// would cause the shift to exceed the bitwidth of the type.
 782         ///
 783         /// Note that this is *not* the same as a rotate-right; the
 784         /// RHS of a wrapping shift-right is restricted to the range
 785         /// of the type, rather than the bits shifted out of the LHS
 786         /// being returned to the other end. The primitive integer
 787         /// types all implement a `rotate_right` function, which may
 788         /// be what you want instead.
 789         ///
 790         /// # Examples
 791         ///
 792         /// Basic usage:
 793         ///
 794         /// ```
 795         /// assert_eq!((-128i8).wrapping_shr(7), -1);
 796         /// assert_eq!((-128i8).wrapping_shr(8), -128);
 797         /// ```
 798         #[stable(feature = "num_wrapping", since = "1.2.0")]
 799         #[inline(always)]
 800         pub fn wrapping_shr(self, rhs: u32) -> Self {
 801             unsafe {
 802                 intrinsics::unchecked_shr(self, (rhs & ($BITS - 1)) as $SelfT)
 803             }
 804         }
 805
 806         /// Wrapping (modular) absolute value. Computes `self.abs()`,
 807         /// wrapping around at the boundary of the type.
 808         ///
 809         /// The only case where such wrapping can occur is when one takes
 810         /// the absolute value of the negative minimal value for the type
 811         /// this is a positive value that is too large to represent in the
 812         /// type. In such a case, this function returns `MIN` itself.
 813         ///
 814         /// # Examples
 815         ///
 816         /// Basic usage:
 817         ///
 818         /// ```
 819         /// assert_eq!(100i8.wrapping_abs(), 100);
 820         /// assert_eq!((-100i8).wrapping_abs(), 100);
 821         /// assert_eq!((-128i8).wrapping_abs(), -128);
 822         /// assert_eq!((-128i8).wrapping_abs() as u8, 128);
 823         /// ```
 824         #[stable(feature = "no_panic_abs", since = "1.13.0")]
 825         #[inline(always)]
 826         pub fn wrapping_abs(self) -> Self {
 827             if self.is_negative() {
 828                 self.wrapping_neg()
 829             } else {
 830                 self
 831             }
 832         }
 833
 834         /// Calculates `self` + `rhs`
 835         ///
 836         /// Returns a tuple of the addition along with a boolean indicating
 837         /// whether an arithmetic overflow would occur. If an overflow would
 838         /// have occurred then the wrapped value is returned.
 839         ///
 840         /// # Examples
 841         ///
 842         /// Basic usage
 843         ///
 844         /// ```
 845         /// use std::i32;
 846         ///
 847         /// assert_eq!(5i32.overflowing_add(2), (7, false));
 848         /// assert_eq!(i32::MAX.overflowing_add(1), (i32::MIN, true));
 849         /// ```
 850         #[inline]
 851         #[stable(feature = "wrapping", since = "1.7.0")]
 852         pub fn overflowing_add(self, rhs: Self) -> (Self, bool) {
 853             unsafe {
 854                 let (a, b) = $add_with_overflow(self as $ActualT,
 855                                                 rhs as $ActualT);
 856                 (a as Self, b)
 857             }
 858         }
 859
 860         /// Calculates `self` - `rhs`
 861         ///
 862         /// Returns a tuple of the subtraction along with a boolean indicating
 863         /// whether an arithmetic overflow would occur. If an overflow would
 864         /// have occurred then the wrapped value is returned.
 865         ///
 866         /// # Examples
 867         ///
 868         /// Basic usage
 869         ///
 870         /// ```
 871         /// use std::i32;
 872         ///
 873         /// assert_eq!(5i32.overflowing_sub(2), (3, false));
 874         /// assert_eq!(i32::MIN.overflowing_sub(1), (i32::MAX, true));
 875         /// ```
 876         #[inline]
 877         #[stable(feature = "wrapping", since = "1.7.0")]
 878         pub fn overflowing_sub(self, rhs: Self) -> (Self, bool) {
 879             unsafe {
 880                 let (a, b) = $sub_with_overflow(self as $ActualT,
 881                                                 rhs as $ActualT);
 882                 (a as Self, b)
 883             }
 884         }
 885
 886         /// Calculates the multiplication of `self` and `rhs`.
 887         ///
 888         /// Returns a tuple of the multiplication along with a boolean
 889         /// indicating whether an arithmetic overflow would occur. If an
 890         /// overflow would have occurred then the wrapped value is returned.
 891         ///
 892         /// # Examples
 893         ///
 894         /// Basic usage
 895         ///
 896         /// ```
 897         /// assert_eq!(5i32.overflowing_mul(2), (10, false));
 898         /// assert_eq!(1_000_000_000i32.overflowing_mul(10), (1410065408, true));
 899         /// ```
 900         #[inline]
 901         #[stable(feature = "wrapping", since = "1.7.0")]
 902         pub fn overflowing_mul(self, rhs: Self) -> (Self, bool) {
 903             unsafe {
 904                 let (a, b) = $mul_with_overflow(self as $ActualT,
 905                                                 rhs as $ActualT);
 906                 (a as Self, b)
 907             }
 908         }
 909
 910         /// Calculates the divisor when `self` is divided by `rhs`.
 911         ///
 912         /// Returns a tuple of the divisor along with a boolean indicating
 913         /// whether an arithmetic overflow would occur. If an overflow would
 914         /// occur then self is returned.
 915         ///
 916         /// # Panics
 917         ///
 918         /// This function will panic if `rhs` is 0.
 919         ///
 920         /// # Examples
 921         ///
 922         /// Basic usage
 923         ///
 924         /// ```
 925         /// use std::i32;
 926         ///
 927         /// assert_eq!(5i32.overflowing_div(2), (2, false));
 928         /// assert_eq!(i32::MIN.overflowing_div(-1), (i32::MIN, true));
 929         /// ```
 930         #[inline]
 931         #[stable(feature = "wrapping", since = "1.7.0")]
 932         pub fn overflowing_div(self, rhs: Self) -> (Self, bool) {
 933             if self == Self::min_value() && rhs == -1 {
 934                 (self, true)
 935             } else {
 936                 (self / rhs, false)
 937             }
 938         }
 939
 940         /// Calculates the remainder when `self` is divided by `rhs`.
 941         ///
 942         /// Returns a tuple of the remainder after dividing along with a boolean
 943         /// indicating whether an arithmetic overflow would occur. If an
 944         /// overflow would occur then 0 is returned.
 945         ///
 946         /// # Panics
 947         ///
 948         /// This function will panic if `rhs` is 0.
 949         ///
 950         /// # Examples
 951         ///
 952         /// Basic usage
 953         ///
 954         /// ```
 955         /// use std::i32;
 956         ///
 957         /// assert_eq!(5i32.overflowing_rem(2), (1, false));
 958         /// assert_eq!(i32::MIN.overflowing_rem(-1), (0, true));
 959         /// ```
 960         #[inline]
 961         #[stable(feature = "wrapping", since = "1.7.0")]
 962         pub fn overflowing_rem(self, rhs: Self) -> (Self, bool) {
 963             if self == Self::min_value() && rhs == -1 {
 964                 (0, true)
 965             } else {
 966                 (self % rhs, false)
 967             }
 968         }
 969
 970         /// Negates self, overflowing if this is equal to the minimum value.
 971         ///
 972         /// Returns a tuple of the negated version of self along with a boolean
 973         /// indicating whether an overflow happened. If `self` is the minimum
 974         /// value (e.g. `i32::MIN` for values of type `i32`), then the minimum
 975         /// value will be returned again and `true` will be returned for an
 976         /// overflow happening.
 977         ///
 978         /// # Examples
 979         ///
 980         /// Basic usage
 981         ///
 982         /// ```
 983         /// use std::i32;
 984         ///
 985         /// assert_eq!(2i32.overflowing_neg(), (-2, false));
 986         /// assert_eq!(i32::MIN.overflowing_neg(), (i32::MIN, true));
 987         /// ```
 988         #[inline]
 989         #[stable(feature = "wrapping", since = "1.7.0")]
 990         pub fn overflowing_neg(self) -> (Self, bool) {
 991             if self == Self::min_value() {
 992                 (Self::min_value(), true)
 993             } else {
 994                 (-self, false)
 995             }
 996         }
 997
 998         /// Shifts self left by `rhs` bits.
 999         ///
1000         /// Returns a tuple of the shifted version of self along with a boolean
1001         /// indicating whether the shift value was larger than or equal to the
1002         /// number of bits. If the shift value is too large, then value is
1003         /// masked (N-1) where N is the number of bits, and this value is then
1004         /// used to perform the shift.
1005         ///
1006         /// # Examples
1007         ///
1008         /// Basic usage
1009         ///
1010         /// ```
1011         /// assert_eq!(0x10i32.overflowing_shl(4), (0x100, false));
1012         /// assert_eq!(0x10i32.overflowing_shl(36), (0x100, true));
1013         /// ```
1014         #[inline]
1015         #[stable(feature = "wrapping", since = "1.7.0")]
1016         pub fn overflowing_shl(self, rhs: u32) -> (Self, bool) {
1017             (self.wrapping_shl(rhs), (rhs > ($BITS - 1)))
1018         }
1019
1020         /// Shifts self right by `rhs` bits.
1021         ///
1022         /// Returns a tuple of the shifted version of self along with a boolean
1023         /// indicating whether the shift value was larger than or equal to the
1024         /// number of bits. If the shift value is too large, then value is
1025         /// masked (N-1) where N is the number of bits, and this value is then
1026         /// used to perform the shift.
1027         ///
1028         /// # Examples
1029         ///
1030         /// Basic usage
1031         ///
1032         /// ```
1033         /// assert_eq!(0x10i32.overflowing_shr(4), (0x1, false));
1034         /// assert_eq!(0x10i32.overflowing_shr(36), (0x1, true));
1035         /// ```
1036         #[inline]
1037         #[stable(feature = "wrapping", since = "1.7.0")]
1038         pub fn overflowing_shr(self, rhs: u32) -> (Self, bool) {
1039             (self.wrapping_shr(rhs), (rhs > ($BITS - 1)))
1040         }
1041
1042         /// Computes the absolute value of `self`.
1043         ///
1044         /// Returns a tuple of the absolute version of self along with a
1045         /// boolean indicating whether an overflow happened. If self is the
1046         /// minimum value (e.g. i32::MIN for values of type i32), then the
1047         /// minimum value will be returned again and true will be returned for
1048         /// an overflow happening.
1049         ///
1050         /// # Examples
1051         ///
1052         /// Basic usage:
1053         ///
1054         /// ```
1055         /// assert_eq!(10i8.overflowing_abs(), (10,false));
1056         /// assert_eq!((-10i8).overflowing_abs(), (10,false));
1057         /// assert_eq!((-128i8).overflowing_abs(), (-128,true));
1058         /// ```
1059         #[stable(feature = "no_panic_abs", since = "1.13.0")]
1060         #[inline]
1061         pub fn overflowing_abs(self) -> (Self, bool) {
1062             if self.is_negative() {
1063                 self.overflowing_neg()
1064             } else {
1065                 (self, false)
1066             }
1067         }
1068
1069         /// Raises self to the power of `exp`, using exponentiation by squaring.
1070         ///
1071         /// # Examples
1072         ///
1073         /// Basic usage:
1074         ///
1075         /// ```
1076         /// let x: i32 = 2; // or any other integer type
1077         ///
1078         /// assert_eq!(x.pow(4), 16);
1079         /// ```
1080         #[stable(feature = "rust1", since = "1.0.0")]
1081         #[inline]
1082         #[rustc_inherit_overflow_checks]
1083         pub fn pow(self, mut exp: u32) -> Self {
1084             let mut base = self;
1085             let mut acc = 1;
1086
1087             while exp > 1 {
1088                 if (exp & 1) == 1 {
1089                     acc = acc * base;
1090                 }
1091                 exp /= 2;
1092                 base = base * base;
1093             }
1094
1095             // Deal with the final bit of the exponent separately, since
1096             // squaring the base afterwards is not necessary and may cause a
1097             // needless overflow.
1098             if exp == 1 {
1099                 acc = acc * base;
1100             }
1101
1102             acc
1103         }
1104
1105         /// Computes the absolute value of `self`.
1106         ///
1107         /// # Overflow behavior
1108         ///
1109         /// The absolute value of `i32::min_value()` cannot be represented as an
1110         /// `i32`, and attempting to calculate it will cause an overflow. This
1111         /// means that code in debug mode will trigger a panic on this case and
1112         /// optimized code will return `i32::min_value()` without a panic.
1113         ///
1114         /// # Examples
1115         ///
1116         /// Basic usage:
1117         ///
1118         /// ```
1119         /// assert_eq!(10i8.abs(), 10);
1120         /// assert_eq!((-10i8).abs(), 10);
1121         /// ```
1122         #[stable(feature = "rust1", since = "1.0.0")]
1123         #[inline]
1124         #[rustc_inherit_overflow_checks]
1125         pub fn abs(self) -> Self {
1126             if self.is_negative() {
1127                 // Note that the #[inline] above means that the overflow
1128                 // semantics of this negation depend on the crate we're being
1129                 // inlined into.
1130                 -self
1131             } else {
1132                 self
1133             }
1134         }
1135
1136         /// Returns a number representing sign of `self`.
1137         ///
1138         /// - `0` if the number is zero
1139         /// - `1` if the number is positive
1140         /// - `-1` if the number is negative
1141         ///
1142         /// # Examples
1143         ///
1144         /// Basic usage:
1145         ///
1146         /// ```
1147         /// assert_eq!(10i8.signum(), 1);
1148         /// assert_eq!(0i8.signum(), 0);
1149         /// assert_eq!((-10i8).signum(), -1);
1150         /// ```
1151         #[stable(feature = "rust1", since = "1.0.0")]
1152         #[inline]
1153         pub fn signum(self) -> Self {
1154             match self {
1155                 n if n > 0 =>  1,
1156                 0          =>  0,
1157                 _          => -1,
1158             }
1159         }
1160
1161         /// Returns `true` if `self` is positive and `false` if the number
1162         /// is zero or negative.
1163         ///
1164         /// # Examples
1165         ///
1166         /// Basic usage:
1167         ///
1168         /// ```
1169         /// assert!(10i8.is_positive());
1170         /// assert!(!(-10i8).is_positive());
1171         /// ```
1172         #[stable(feature = "rust1", since = "1.0.0")]
1173         #[inline]
1174         pub fn is_positive(self) -> bool { self > 0 }
1175
1176         /// Returns `true` if `self` is negative and `false` if the number
1177         /// is zero or positive.
1178         ///
1179         /// # Examples
1180         ///
1181         /// Basic usage:
1182         ///
1183         /// ```
1184         /// assert!((-10i8).is_negative());
1185         /// assert!(!10i8.is_negative());
1186         /// ```
1187         #[stable(feature = "rust1", since = "1.0.0")]
1188         #[inline]
1189         pub fn is_negative(self) -> bool { self < 0 }
1190     }
1191 }
1192
1193 #[lang = "i8"]
1194 impl i8 {
1195     int_impl! { i8, i8, u8, 8,
1196         intrinsics::add_with_overflow,
1197         intrinsics::sub_with_overflow,
1198         intrinsics::mul_with_overflow }
1199 }
1200
1201 #[lang = "i16"]
1202 impl i16 {
1203     int_impl! { i16, i16, u16, 16,
1204         intrinsics::add_with_overflow,
1205         intrinsics::sub_with_overflow,
1206         intrinsics::mul_with_overflow }
1207 }
1208
1209 #[lang = "i32"]
1210 impl i32 {
1211     int_impl! { i32, i32, u32, 32,
1212         intrinsics::add_with_overflow,
1213         intrinsics::sub_with_overflow,
1214         intrinsics::mul_with_overflow }
1215 }
1216
1217 #[lang = "i64"]
1218 impl i64 {
1219     int_impl! { i64, i64, u64, 64,
1220         intrinsics::add_with_overflow,
1221         intrinsics::sub_with_overflow,
1222         intrinsics::mul_with_overflow }
1223 }
1224
1225 #[lang = "i128"]
1226 impl i128 {
1227     int_impl! { i128, i128, u128, 128,
1228         intrinsics::add_with_overflow,
1229         intrinsics::sub_with_overflow,
1230         intrinsics::mul_with_overflow }
1231 }
1232
1233 #[cfg(target_pointer_width = "16")]
1234 #[lang = "isize"]
1235 impl isize {
1236     int_impl! { isize, i16, u16, 16,
1237         intrinsics::add_with_overflow,
1238         intrinsics::sub_with_overflow,
1239         intrinsics::mul_with_overflow }
1240 }
1241
1242 #[cfg(target_pointer_width = "32")]
1243 #[lang = "isize"]
1244 impl isize {
1245     int_impl! { isize, i32, u32, 32,
1246         intrinsics::add_with_overflow,
1247         intrinsics::sub_with_overflow,
1248         intrinsics::mul_with_overflow }
1249 }
1250
1251 #[cfg(target_pointer_width = "64")]
1252 #[lang = "isize"]
1253 impl isize {
1254     int_impl! { isize, i64, u64, 64,
1255         intrinsics::add_with_overflow,
1256         intrinsics::sub_with_overflow,
1257         intrinsics::mul_with_overflow }
1258 }
1259
1260 // `Int` + `UnsignedInt` implemented for unsigned integers
1261 macro_rules! uint_impl {
1262     ($SelfT:ty, $ActualT:ty, $BITS:expr,
1263      $ctpop:path,
1264      $ctlz:path,
1265      $ctlz_nonzero:path,
1266      $cttz:path,
1267      $bswap:path,
1268      $add_with_overflow:path,
1269      $sub_with_overflow:path,
1270      $mul_with_overflow:path) => {
1271         /// Returns the smallest value that can be represented by this integer type.
1272         ///
1273         /// # Examples
1274         ///
1275         /// ```
1276         /// assert_eq!(u8::min_value(), 0);
1277         /// ```
1278         #[stable(feature = "rust1", since = "1.0.0")]
1279         #[inline]
1280         pub const fn min_value() -> Self { 0 }
1281
1282         /// Returns the largest value that can be represented by this integer type.
1283         ///
1284         /// # Examples
1285         ///
1286         /// ```
1287         /// assert_eq!(u8::max_value(), 255);
1288         /// ```
1289         #[stable(feature = "rust1", since = "1.0.0")]
1290         #[inline]
1291         pub const fn max_value() -> Self { !0 }
1292
1293         /// Converts a string slice in a given base to an integer.
1294         ///
1295         /// Leading and trailing whitespace represent an error.
1296         ///
1297         /// # Examples
1298         ///
1299         /// Basic usage:
1300         ///
1301         /// ```
1302         /// assert_eq!(u32::from_str_radix("A", 16), Ok(10));
1303         /// ```
1304         #[stable(feature = "rust1", since = "1.0.0")]
1305         pub fn from_str_radix(src: &str, radix: u32) -> Result<Self, ParseIntError> {
1306             from_str_radix(src, radix)
1307         }
1308
1309         /// Returns the number of ones in the binary representation of `self`.
1310         ///
1311         /// # Examples
1312         ///
1313         /// Basic usage:
1314         ///
1315         /// ```
1316         /// let n = 0b01001100u8;
1317         ///
1318         /// assert_eq!(n.count_ones(), 3);
1319         /// ```
1320         #[stable(feature = "rust1", since = "1.0.0")]
1321         #[inline]
1322         pub fn count_ones(self) -> u32 {
1323             unsafe { $ctpop(self as $ActualT) as u32 }
1324         }
1325
1326         /// Returns the number of zeros in the binary representation of `self`.
1327         ///
1328         /// # Examples
1329         ///
1330         /// Basic usage:
1331         ///
1332         /// ```
1333         /// let n = 0b01001100u8;
1334         ///
1335         /// assert_eq!(n.count_zeros(), 5);
1336         /// ```
1337         #[stable(feature = "rust1", since = "1.0.0")]
1338         #[inline]
1339         pub fn count_zeros(self) -> u32 {
1340             (!self).count_ones()
1341         }
1342
1343         /// Returns the number of leading zeros in the binary representation
1344         /// of `self`.
1345         ///
1346         /// # Examples
1347         ///
1348         /// Basic usage:
1349         ///
1350         /// ```
1351         /// let n = 0b0101000u16;
1352         ///
1353         /// assert_eq!(n.leading_zeros(), 10);
1354         /// ```
1355         #[stable(feature = "rust1", since = "1.0.0")]
1356         #[inline]
1357         pub fn leading_zeros(self) -> u32 {
1358             unsafe { $ctlz(self as $ActualT) as u32 }
1359         }
1360
1361         /// Returns the number of trailing zeros in the binary representation
1362         /// of `self`.
1363         ///
1364         /// # Examples
1365         ///
1366         /// Basic usage:
1367         ///
1368         /// ```
1369         /// let n = 0b0101000u16;
1370         ///
1371         /// assert_eq!(n.trailing_zeros(), 3);
1372         /// ```
1373         #[stable(feature = "rust1", since = "1.0.0")]
1374         #[inline]
1375         pub fn trailing_zeros(self) -> u32 {
1376             // As of LLVM 3.6 the codegen for the zero-safe cttz8 intrinsic
1377             // emits two conditional moves on x86_64. By promoting the value to
1378             // u16 and setting bit 8, we get better code without any conditional
1379             // operations.
1380             // FIXME: There's a LLVM patch (http://reviews.llvm.org/D9284)
1381             // pending, remove this workaround once LLVM generates better code
1382             // for cttz8.
1383             unsafe {
1384                 if $BITS == 8 {
1385                     intrinsics::cttz(self as u16 | 0x100) as u32
1386                 } else {
1387                     intrinsics::cttz(self) as u32
1388                 }
1389             }
1390         }
1391
1392         /// Shifts the bits to the left by a specified amount, `n`,
1393         /// wrapping the truncated bits to the end of the resulting integer.
1394         ///
1395         /// Please note this isn't the same operation as `<<`!
1396         ///
1397         /// # Examples
1398         ///
1399         /// Basic usage:
1400         ///
1401         /// ```
1402         /// let n = 0x0123456789ABCDEFu64;
1403         /// let m = 0x3456789ABCDEF012u64;
1404         ///
1405         /// assert_eq!(n.rotate_left(12), m);
1406         /// ```
1407         #[stable(feature = "rust1", since = "1.0.0")]
1408         #[inline]
1409         pub fn rotate_left(self, n: u32) -> Self {
1410             // Protect against undefined behaviour for over-long bit shifts
1411             let n = n % $BITS;
1412             (self << n) | (self >> (($BITS - n) % $BITS))
1413         }
1414
1415         /// Shifts the bits to the right by a specified amount, `n`,
1416         /// wrapping the truncated bits to the beginning of the resulting
1417         /// integer.
1418         ///
1419         /// Please note this isn't the same operation as `>>`!
1420         ///
1421         /// # Examples
1422         ///
1423         /// Basic usage:
1424         ///
1425         /// ```
1426         /// let n = 0x0123456789ABCDEFu64;
1427         /// let m = 0xDEF0123456789ABCu64;
1428         ///
1429         /// assert_eq!(n.rotate_right(12), m);
1430         /// ```
1431         #[stable(feature = "rust1", since = "1.0.0")]
1432         #[inline]
1433         pub fn rotate_right(self, n: u32) -> Self {
1434             // Protect against undefined behaviour for over-long bit shifts
1435             let n = n % $BITS;
1436             (self >> n) | (self << (($BITS - n) % $BITS))
1437         }
1438
1439         /// Reverses the byte order of the integer.
1440         ///
1441         /// # Examples
1442         ///
1443         /// Basic usage:
1444         ///
1445         /// ```
1446         /// let n = 0x0123456789ABCDEFu64;
1447         /// let m = 0xEFCDAB8967452301u64;
1448         ///
1449         /// assert_eq!(n.swap_bytes(), m);
1450         /// ```
1451         #[stable(feature = "rust1", since = "1.0.0")]
1452         #[inline]
1453         pub fn swap_bytes(self) -> Self {
1454             unsafe { $bswap(self as $ActualT) as Self }
1455         }
1456
1457         /// Converts an integer from big endian to the target's endianness.
1458         ///
1459         /// On big endian this is a no-op. On little endian the bytes are
1460         /// swapped.
1461         ///
1462         /// # Examples
1463         ///
1464         /// Basic usage:
1465         ///
1466         /// ```
1467         /// let n = 0x0123456789ABCDEFu64;
1468         ///
1469         /// if cfg!(target_endian = "big") {
1470         ///     assert_eq!(u64::from_be(n), n)
1471         /// } else {
1472         ///     assert_eq!(u64::from_be(n), n.swap_bytes())
1473         /// }
1474         /// ```
1475         #[stable(feature = "rust1", since = "1.0.0")]
1476         #[inline]
1477         pub fn from_be(x: Self) -> Self {
1478             if cfg!(target_endian = "big") { x } else { x.swap_bytes() }
1479         }
1480
1481         /// Converts an integer from little endian to the target's endianness.
1482         ///
1483         /// On little endian this is a no-op. On big endian the bytes are
1484         /// swapped.
1485         ///
1486         /// # Examples
1487         ///
1488         /// Basic usage:
1489         ///
1490         /// ```
1491         /// let n = 0x0123456789ABCDEFu64;
1492         ///
1493         /// if cfg!(target_endian = "little") {
1494         ///     assert_eq!(u64::from_le(n), n)
1495         /// } else {
1496         ///     assert_eq!(u64::from_le(n), n.swap_bytes())
1497         /// }
1498         /// ```
1499         #[stable(feature = "rust1", since = "1.0.0")]
1500         #[inline]
1501         pub fn from_le(x: Self) -> Self {
1502             if cfg!(target_endian = "little") { x } else { x.swap_bytes() }
1503         }
1504
1505         /// Converts `self` to big endian from the target's endianness.
1506         ///
1507         /// On big endian this is a no-op. On little endian the bytes are
1508         /// swapped.
1509         ///
1510         /// # Examples
1511         ///
1512         /// Basic usage:
1513         ///
1514         /// ```
1515         /// let n = 0x0123456789ABCDEFu64;
1516         ///
1517         /// if cfg!(target_endian = "big") {
1518         ///     assert_eq!(n.to_be(), n)
1519         /// } else {
1520         ///     assert_eq!(n.to_be(), n.swap_bytes())
1521         /// }
1522         /// ```
1523         #[stable(feature = "rust1", since = "1.0.0")]
1524         #[inline]
1525         pub fn to_be(self) -> Self { // or not to be?
1526             if cfg!(target_endian = "big") { self } else { self.swap_bytes() }
1527         }
1528
1529         /// Converts `self` to little endian from the target's endianness.
1530         ///
1531         /// On little endian this is a no-op. On big endian the bytes are
1532         /// swapped.
1533         ///
1534         /// # Examples
1535         ///
1536         /// Basic usage:
1537         ///
1538         /// ```
1539         /// let n = 0x0123456789ABCDEFu64;
1540         ///
1541         /// if cfg!(target_endian = "little") {
1542         ///     assert_eq!(n.to_le(), n)
1543         /// } else {
1544         ///     assert_eq!(n.to_le(), n.swap_bytes())
1545         /// }
1546         /// ```
1547         #[stable(feature = "rust1", since = "1.0.0")]
1548         #[inline]
1549         pub fn to_le(self) -> Self {
1550             if cfg!(target_endian = "little") { self } else { self.swap_bytes() }
1551         }
1552
1553         /// Checked integer addition. Computes `self + other`, returning `None`
1554         /// if overflow occurred.
1555         ///
1556         /// # Examples
1557         ///
1558         /// Basic usage:
1559         ///
1560         /// ```
1561         /// assert_eq!(5u16.checked_add(65530), Some(65535));
1562         /// assert_eq!(6u16.checked_add(65530), None);
1563         /// ```
1564         #[stable(feature = "rust1", since = "1.0.0")]
1565         #[inline]
1566         pub fn checked_add(self, other: Self) -> Option<Self> {
1567             let (a, b) = self.overflowing_add(other);
1568             if b {None} else {Some(a)}
1569         }
1570
1571         /// Checked integer subtraction. Computes `self - other`, returning
1572         /// `None` if underflow occurred.
1573         ///
1574         /// # Examples
1575         ///
1576         /// Basic usage:
1577         ///
1578         /// ```
1579         /// assert_eq!(1u8.checked_sub(1), Some(0));
1580         /// assert_eq!(0u8.checked_sub(1), None);
1581         /// ```
1582         #[stable(feature = "rust1", since = "1.0.0")]
1583         #[inline]
1584         pub fn checked_sub(self, other: Self) -> Option<Self> {
1585             let (a, b) = self.overflowing_sub(other);
1586             if b {None} else {Some(a)}
1587         }
1588
1589         /// Checked integer multiplication. Computes `self * other`, returning
1590         /// `None` if underflow or overflow occurred.
1591         ///
1592         /// # Examples
1593         ///
1594         /// Basic usage:
1595         ///
1596         /// ```
1597         /// assert_eq!(5u8.checked_mul(51), Some(255));
1598         /// assert_eq!(5u8.checked_mul(52), None);
1599         /// ```
1600         #[stable(feature = "rust1", since = "1.0.0")]
1601         #[inline]
1602         pub fn checked_mul(self, other: Self) -> Option<Self> {
1603             let (a, b) = self.overflowing_mul(other);
1604             if b {None} else {Some(a)}
1605         }
1606
1607         /// Checked integer division. Computes `self / other`, returning `None`
1608         /// if `other == 0` or the operation results in underflow or overflow.
1609         ///
1610         /// # Examples
1611         ///
1612         /// Basic usage:
1613         ///
1614         /// ```
1615         /// assert_eq!(128u8.checked_div(2), Some(64));
1616         /// assert_eq!(1u8.checked_div(0), None);
1617         /// ```
1618         #[stable(feature = "rust1", since = "1.0.0")]
1619         #[inline]
1620         pub fn checked_div(self, other: Self) -> Option<Self> {
1621             match other {
1622                 0 => None,
1623                 other => Some(unsafe { intrinsics::unchecked_div(self, other) }),
1624             }
1625         }
1626
1627         /// Checked integer remainder. Computes `self % other`, returning `None`
1628         /// if `other == 0` or the operation results in underflow or overflow.
1629         ///
1630         /// # Examples
1631         ///
1632         /// Basic usage:
1633         ///
1634         /// ```
1635         /// assert_eq!(5u32.checked_rem(2), Some(1));
1636         /// assert_eq!(5u32.checked_rem(0), None);
1637         /// ```
1638         #[stable(feature = "wrapping", since = "1.7.0")]
1639         #[inline]
1640         pub fn checked_rem(self, other: Self) -> Option<Self> {
1641             if other == 0 {
1642                 None
1643             } else {
1644                 Some(unsafe { intrinsics::unchecked_rem(self, other) })
1645             }
1646         }
1647
1648         /// Checked negation. Computes `-self`, returning `None` unless `self ==
1649         /// 0`.
1650         ///
1651         /// Note that negating any positive integer will overflow.
1652         ///
1653         /// # Examples
1654         ///
1655         /// Basic usage:
1656         ///
1657         /// ```
1658         /// assert_eq!(0u32.checked_neg(), Some(0));
1659         /// assert_eq!(1u32.checked_neg(), None);
1660         /// ```
1661         #[stable(feature = "wrapping", since = "1.7.0")]
1662         #[inline]
1663         pub fn checked_neg(self) -> Option<Self> {
1664             let (a, b) = self.overflowing_neg();
1665             if b {None} else {Some(a)}
1666         }
1667
1668         /// Checked shift left. Computes `self << rhs`, returning `None`
1669         /// if `rhs` is larger than or equal to the number of bits in `self`.
1670         ///
1671         /// # Examples
1672         ///
1673         /// Basic usage:
1674         ///
1675         /// ```
1676         /// assert_eq!(0x10u32.checked_shl(4), Some(0x100));
1677         /// assert_eq!(0x10u32.checked_shl(33), None);
1678         /// ```
1679         #[stable(feature = "wrapping", since = "1.7.0")]
1680         #[inline]
1681         pub fn checked_shl(self, rhs: u32) -> Option<Self> {
1682             let (a, b) = self.overflowing_shl(rhs);
1683             if b {None} else {Some(a)}
1684         }
1685
1686         /// Checked shift right. Computes `self >> rhs`, returning `None`
1687         /// if `rhs` is larger than or equal to the number of bits in `self`.
1688         ///
1689         /// # Examples
1690         ///
1691         /// Basic usage:
1692         ///
1693         /// ```
1694         /// assert_eq!(0x10u32.checked_shr(4), Some(0x1));
1695         /// assert_eq!(0x10u32.checked_shr(33), None);
1696         /// ```
1697         #[stable(feature = "wrapping", since = "1.7.0")]
1698         #[inline]
1699         pub fn checked_shr(self, rhs: u32) -> Option<Self> {
1700             let (a, b) = self.overflowing_shr(rhs);
1701             if b {None} else {Some(a)}
1702         }
1703
1704         /// Saturating integer addition. Computes `self + other`, saturating at
1705         /// the numeric bounds instead of overflowing.
1706         ///
1707         /// # Examples
1708         ///
1709         /// Basic usage:
1710         ///
1711         /// ```
1712         /// assert_eq!(100u8.saturating_add(1), 101);
1713         /// assert_eq!(200u8.saturating_add(127), 255);
1714         /// ```
1715         #[stable(feature = "rust1", since = "1.0.0")]
1716         #[inline]
1717         pub fn saturating_add(self, other: Self) -> Self {
1718             match self.checked_add(other) {
1719                 Some(x) => x,
1720                 None => Self::max_value(),
1721             }
1722         }
1723
1724         /// Saturating integer subtraction. Computes `self - other`, saturating
1725         /// at the numeric bounds instead of overflowing.
1726         ///
1727         /// # Examples
1728         ///
1729         /// Basic usage:
1730         ///
1731         /// ```
1732         /// assert_eq!(100u8.saturating_sub(27), 73);
1733         /// assert_eq!(13u8.saturating_sub(127), 0);
1734         /// ```
1735         #[stable(feature = "rust1", since = "1.0.0")]
1736         #[inline]
1737         pub fn saturating_sub(self, other: Self) -> Self {
1738             match self.checked_sub(other) {
1739                 Some(x) => x,
1740                 None => Self::min_value(),
1741             }
1742         }
1743
1744         /// Saturating integer multiplication. Computes `self * other`,
1745         /// saturating at the numeric bounds instead of overflowing.
1746         ///
1747         /// # Examples
1748         ///
1749         /// Basic usage:
1750         ///
1751         /// ```
1752         /// use std::u32;
1753         ///
1754         /// assert_eq!(100u32.saturating_mul(127), 12700);
1755         /// assert_eq!((1u32 << 23).saturating_mul(1 << 23), u32::MAX);
1756         /// ```
1757         #[stable(feature = "wrapping", since = "1.7.0")]
1758         #[inline]
1759         pub fn saturating_mul(self, other: Self) -> Self {
1760             self.checked_mul(other).unwrap_or(Self::max_value())
1761         }
1762
1763         /// Wrapping (modular) addition. Computes `self + other`,
1764         /// wrapping around at the boundary of the type.
1765         ///
1766         /// # Examples
1767         ///
1768         /// Basic usage:
1769         ///
1770         /// ```
1771         /// assert_eq!(200u8.wrapping_add(55), 255);
1772         /// assert_eq!(200u8.wrapping_add(155), 99);
1773         /// ```
1774         #[stable(feature = "rust1", since = "1.0.0")]
1775         #[inline]
1776         pub fn wrapping_add(self, rhs: Self) -> Self {
1777             unsafe {
1778                 intrinsics::overflowing_add(self, rhs)
1779             }
1780         }
1781
1782         /// Wrapping (modular) subtraction. Computes `self - other`,
1783         /// wrapping around at the boundary of the type.
1784         ///
1785         /// # Examples
1786         ///
1787         /// Basic usage:
1788         ///
1789         /// ```
1790         /// assert_eq!(100u8.wrapping_sub(100), 0);
1791         /// assert_eq!(100u8.wrapping_sub(155), 201);
1792         /// ```
1793         #[stable(feature = "rust1", since = "1.0.0")]
1794         #[inline]
1795         pub fn wrapping_sub(self, rhs: Self) -> Self {
1796             unsafe {
1797                 intrinsics::overflowing_sub(self, rhs)
1798             }
1799         }
1800
1801         /// Wrapping (modular) multiplication. Computes `self *
1802         /// other`, wrapping around at the boundary of the type.
1803         ///
1804         /// # Examples
1805         ///
1806         /// Basic usage:
1807         ///
1808         /// ```
1809         /// assert_eq!(10u8.wrapping_mul(12), 120);
1810         /// assert_eq!(25u8.wrapping_mul(12), 44);
1811         /// ```
1812         #[stable(feature = "rust1", since = "1.0.0")]
1813         #[inline]
1814         pub fn wrapping_mul(self, rhs: Self) -> Self {
1815             unsafe {
1816                 intrinsics::overflowing_mul(self, rhs)
1817             }
1818         }
1819
1820         /// Wrapping (modular) division. Computes `self / other`.
1821         /// Wrapped division on unsigned types is just normal division.
1822         /// There's no way wrapping could ever happen.
1823         /// This function exists, so that all operations
1824         /// are accounted for in the wrapping operations.
1825         ///
1826         /// # Examples
1827         ///
1828         /// Basic usage:
1829         ///
1830         /// ```
1831         /// assert_eq!(100u8.wrapping_div(10), 10);
1832         /// ```
1833         #[stable(feature = "num_wrapping", since = "1.2.0")]
1834         #[inline(always)]
1835         pub fn wrapping_div(self, rhs: Self) -> Self {
1836             self / rhs
1837         }
1838
1839         /// Wrapping (modular) remainder. Computes `self % other`.
1840         /// Wrapped remainder calculation on unsigned types is
1841         /// just the regular remainder calculation.
1842         /// There's no way wrapping could ever happen.
1843         /// This function exists, so that all operations
1844         /// are accounted for in the wrapping operations.
1845         ///
1846         /// # Examples
1847         ///
1848         /// Basic usage:
1849         ///
1850         /// ```
1851         /// assert_eq!(100u8.wrapping_rem(10), 0);
1852         /// ```
1853         #[stable(feature = "num_wrapping", since = "1.2.0")]
1854         #[inline(always)]
1855         pub fn wrapping_rem(self, rhs: Self) -> Self {
1856             self % rhs
1857         }
1858
1859         /// Wrapping (modular) negation. Computes `-self`,
1860         /// wrapping around at the boundary of the type.
1861         ///
1862         /// Since unsigned types do not have negative equivalents
1863         /// all applications of this function will wrap (except for `-0`).
1864         /// For values smaller than the corresponding signed type's maximum
1865         /// the result is the same as casting the corresponding signed value.
1866         /// Any larger values are equivalent to `MAX + 1 - (val - MAX - 1)` where
1867         /// `MAX` is the corresponding signed type's maximum.
1868         ///
1869         /// # Examples
1870         ///
1871         /// Basic usage:
1872         ///
1873         /// ```
1874         /// assert_eq!(100u8.wrapping_neg(), 156);
1875         /// assert_eq!(0u8.wrapping_neg(), 0);
1876         /// assert_eq!(180u8.wrapping_neg(), 76);
1877         /// assert_eq!(180u8.wrapping_neg(), (127 + 1) - (180u8 - (127 + 1)));
1878         /// ```
1879         #[stable(feature = "num_wrapping", since = "1.2.0")]
1880         #[inline(always)]
1881         pub fn wrapping_neg(self) -> Self {
1882             self.overflowing_neg().0
1883         }
1884
1885         /// Panic-free bitwise shift-left; yields `self << mask(rhs)`,
1886         /// where `mask` removes any high-order bits of `rhs` that
1887         /// would cause the shift to exceed the bitwidth of the type.
1888         ///
1889         /// Note that this is *not* the same as a rotate-left; the
1890         /// RHS of a wrapping shift-left is restricted to the range
1891         /// of the type, rather than the bits shifted out of the LHS
1892         /// being returned to the other end. The primitive integer
1893         /// types all implement a `rotate_left` function, which may
1894         /// be what you want instead.
1895         ///
1896         /// # Examples
1897         ///
1898         /// Basic usage:
1899         ///
1900         /// ```
1901         /// assert_eq!(1u8.wrapping_shl(7), 128);
1902         /// assert_eq!(1u8.wrapping_shl(8), 1);
1903         /// ```
1904         #[stable(feature = "num_wrapping", since = "1.2.0")]
1905         #[inline(always)]
1906         pub fn wrapping_shl(self, rhs: u32) -> Self {
1907             unsafe {
1908                 intrinsics::unchecked_shl(self, (rhs & ($BITS - 1)) as $SelfT)
1909             }
1910         }
1911
1912         /// Panic-free bitwise shift-right; yields `self >> mask(rhs)`,
1913         /// where `mask` removes any high-order bits of `rhs` that
1914         /// would cause the shift to exceed the bitwidth of the type.
1915         ///
1916         /// Note that this is *not* the same as a rotate-right; the
1917         /// RHS of a wrapping shift-right is restricted to the range
1918         /// of the type, rather than the bits shifted out of the LHS
1919         /// being returned to the other end. The primitive integer
1920         /// types all implement a `rotate_right` function, which may
1921         /// be what you want instead.
1922         ///
1923         /// # Examples
1924         ///
1925         /// Basic usage:
1926         ///
1927         /// ```
1928         /// assert_eq!(128u8.wrapping_shr(7), 1);
1929         /// assert_eq!(128u8.wrapping_shr(8), 128);
1930         /// ```
1931         #[stable(feature = "num_wrapping", since = "1.2.0")]
1932         #[inline(always)]
1933         pub fn wrapping_shr(self, rhs: u32) -> Self {
1934             unsafe {
1935                 intrinsics::unchecked_shr(self, (rhs & ($BITS - 1)) as $SelfT)
1936             }
1937         }
1938
1939         /// Calculates `self` + `rhs`
1940         ///
1941         /// Returns a tuple of the addition along with a boolean indicating
1942         /// whether an arithmetic overflow would occur. If an overflow would
1943         /// have occurred then the wrapped value is returned.
1944         ///
1945         /// # Examples
1946         ///
1947         /// Basic usage
1948         ///
1949         /// ```
1950         /// use std::u32;
1951         ///
1952         /// assert_eq!(5u32.overflowing_add(2), (7, false));
1953         /// assert_eq!(u32::MAX.overflowing_add(1), (0, true));
1954         /// ```
1955         #[inline]
1956         #[stable(feature = "wrapping", since = "1.7.0")]
1957         pub fn overflowing_add(self, rhs: Self) -> (Self, bool) {
1958             unsafe {
1959                 let (a, b) = $add_with_overflow(self as $ActualT,
1960                                                 rhs as $ActualT);
1961                 (a as Self, b)
1962             }
1963         }
1964
1965         /// Calculates `self` - `rhs`
1966         ///
1967         /// Returns a tuple of the subtraction along with a boolean indicating
1968         /// whether an arithmetic overflow would occur. If an overflow would
1969         /// have occurred then the wrapped value is returned.
1970         ///
1971         /// # Examples
1972         ///
1973         /// Basic usage
1974         ///
1975         /// ```
1976         /// use std::u32;
1977         ///
1978         /// assert_eq!(5u32.overflowing_sub(2), (3, false));
1979         /// assert_eq!(0u32.overflowing_sub(1), (u32::MAX, true));
1980         /// ```
1981         #[inline]
1982         #[stable(feature = "wrapping", since = "1.7.0")]
1983         pub fn overflowing_sub(self, rhs: Self) -> (Self, bool) {
1984             unsafe {
1985                 let (a, b) = $sub_with_overflow(self as $ActualT,
1986                                                 rhs as $ActualT);
1987                 (a as Self, b)
1988             }
1989         }
1990
1991         /// Calculates the multiplication of `self` and `rhs`.
1992         ///
1993         /// Returns a tuple of the multiplication along with a boolean
1994         /// indicating whether an arithmetic overflow would occur. If an
1995         /// overflow would have occurred then the wrapped value is returned.
1996         ///
1997         /// # Examples
1998         ///
1999         /// Basic usage
2000         ///
2001         /// ```
2002         /// assert_eq!(5u32.overflowing_mul(2), (10, false));
2003         /// assert_eq!(1_000_000_000u32.overflowing_mul(10), (1410065408, true));
2004         /// ```
2005         #[inline]
2006         #[stable(feature = "wrapping", since = "1.7.0")]
2007         pub fn overflowing_mul(self, rhs: Self) -> (Self, bool) {
2008             unsafe {
2009                 let (a, b) = $mul_with_overflow(self as $ActualT,
2010                                                 rhs as $ActualT);
2011                 (a as Self, b)
2012             }
2013         }
2014
2015         /// Calculates the divisor when `self` is divided by `rhs`.
2016         ///
2017         /// Returns a tuple of the divisor along with a boolean indicating
2018         /// whether an arithmetic overflow would occur. Note that for unsigned
2019         /// integers overflow never occurs, so the second value is always
2020         /// `false`.
2021         ///
2022         /// # Panics
2023         ///
2024         /// This function will panic if `rhs` is 0.
2025         ///
2026         /// # Examples
2027         ///
2028         /// Basic usage
2029         ///
2030         /// ```
2031         /// assert_eq!(5u32.overflowing_div(2), (2, false));
2032         /// ```
2033         #[inline]
2034         #[stable(feature = "wrapping", since = "1.7.0")]
2035         pub fn overflowing_div(self, rhs: Self) -> (Self, bool) {
2036             (self / rhs, false)
2037         }
2038
2039         /// Calculates the remainder when `self` is divided by `rhs`.
2040         ///
2041         /// Returns a tuple of the remainder after dividing along with a boolean
2042         /// indicating whether an arithmetic overflow would occur. Note that for
2043         /// unsigned integers overflow never occurs, so the second value is
2044         /// always `false`.
2045         ///
2046         /// # Panics
2047         ///
2048         /// This function will panic if `rhs` is 0.
2049         ///
2050         /// # Examples
2051         ///
2052         /// Basic usage
2053         ///
2054         /// ```
2055         /// assert_eq!(5u32.overflowing_rem(2), (1, false));
2056         /// ```
2057         #[inline]
2058         #[stable(feature = "wrapping", since = "1.7.0")]
2059         pub fn overflowing_rem(self, rhs: Self) -> (Self, bool) {
2060             (self % rhs, false)
2061         }
2062
2063         /// Negates self in an overflowing fashion.
2064         ///
2065         /// Returns `!self + 1` using wrapping operations to return the value
2066         /// that represents the negation of this unsigned value. Note that for
2067         /// positive unsigned values overflow always occurs, but negating 0 does
2068         /// not overflow.
2069         ///
2070         /// # Examples
2071         ///
2072         /// Basic usage
2073         ///
2074         /// ```
2075         /// assert_eq!(0u32.overflowing_neg(), (0, false));
2076         /// assert_eq!(2u32.overflowing_neg(), (-2i32 as u32, true));
2077         /// ```
2078         #[inline]
2079         #[stable(feature = "wrapping", since = "1.7.0")]
2080         pub fn overflowing_neg(self) -> (Self, bool) {
2081             ((!self).wrapping_add(1), self != 0)
2082         }
2083
2084         /// Shifts self left by `rhs` bits.
2085         ///
2086         /// Returns a tuple of the shifted version of self along with a boolean
2087         /// indicating whether the shift value was larger than or equal to the
2088         /// number of bits. If the shift value is too large, then value is
2089         /// masked (N-1) where N is the number of bits, and this value is then
2090         /// used to perform the shift.
2091         ///
2092         /// # Examples
2093         ///
2094         /// Basic usage
2095         ///
2096         /// ```
2097         /// assert_eq!(0x10u32.overflowing_shl(4), (0x100, false));
2098         /// assert_eq!(0x10u32.overflowing_shl(36), (0x100, true));
2099         /// ```
2100         #[inline]
2101         #[stable(feature = "wrapping", since = "1.7.0")]
2102         pub fn overflowing_shl(self, rhs: u32) -> (Self, bool) {
2103             (self.wrapping_shl(rhs), (rhs > ($BITS - 1)))
2104         }
2105
2106         /// Shifts self right by `rhs` bits.
2107         ///
2108         /// Returns a tuple of the shifted version of self along with a boolean
2109         /// indicating whether the shift value was larger than or equal to the
2110         /// number of bits. If the shift value is too large, then value is
2111         /// masked (N-1) where N is the number of bits, and this value is then
2112         /// used to perform the shift.
2113         ///
2114         /// # Examples
2115         ///
2116         /// Basic usage
2117         ///
2118         /// ```
2119         /// assert_eq!(0x10u32.overflowing_shr(4), (0x1, false));
2120         /// assert_eq!(0x10u32.overflowing_shr(36), (0x1, true));
2121         /// ```
2122         #[inline]
2123         #[stable(feature = "wrapping", since = "1.7.0")]
2124         pub fn overflowing_shr(self, rhs: u32) -> (Self, bool) {
2125             (self.wrapping_shr(rhs), (rhs > ($BITS - 1)))
2126
2127         }
2128
2129         /// Raises self to the power of `exp`, using exponentiation by squaring.
2130         ///
2131         /// # Examples
2132         ///
2133         /// Basic usage:
2134         ///
2135         /// ```
2136         /// assert_eq!(2u32.pow(4), 16);
2137         /// ```
2138         #[stable(feature = "rust1", since = "1.0.0")]
2139         #[inline]
2140         #[rustc_inherit_overflow_checks]
2141         pub fn pow(self, mut exp: u32) -> Self {
2142             let mut base = self;
2143             let mut acc = 1;
2144
2145             while exp > 1 {
2146                 if (exp & 1) == 1 {
2147                     acc = acc * base;
2148                 }
2149                 exp /= 2;
2150                 base = base * base;
2151             }
2152
2153             // Deal with the final bit of the exponent separately, since
2154             // squaring the base afterwards is not necessary and may cause a
2155             // needless overflow.
2156             if exp == 1 {
2157                 acc = acc * base;
2158             }
2159
2160             acc
2161         }
2162
2163         /// Returns `true` if and only if `self == 2^k` for some `k`.
2164         ///
2165         /// # Examples
2166         ///
2167         /// Basic usage:
2168         ///
2169         /// ```
2170         /// assert!(16u8.is_power_of_two());
2171         /// assert!(!10u8.is_power_of_two());
2172         /// ```
2173         #[stable(feature = "rust1", since = "1.0.0")]
2174         #[inline]
2175         pub fn is_power_of_two(self) -> bool {
2176             (self.wrapping_sub(1)) & self == 0 && !(self == 0)
2177         }
2178
2179         // Returns one less than next power of two.
2180         // (For 8u8 next power of two is 8u8 and for 6u8 it is 8u8)
2181         //
2182         // 8u8.one_less_than_next_power_of_two() == 7
2183         // 6u8.one_less_than_next_power_of_two() == 7
2184         //
2185         // This method cannot overflow, as in the `next_power_of_two`
2186         // overflow cases it instead ends up returning the maximum value
2187         // of the type, and can return 0 for 0.
2188         #[inline]
2189         fn one_less_than_next_power_of_two(self) -> Self {
2190             if self <= 1 { return 0; }
2191
2192             // Because `p > 0`, it cannot consist entirely of leading zeros.
2193             // That means the shift is always in-bounds, and some processors
2194             // (such as intel pre-haswell) have more efficient ctlz
2195             // intrinsics when the argument is non-zero.
2196             let p = self - 1;
2197             let z = unsafe { $ctlz_nonzero(p) };
2198             <$SelfT>::max_value() >> z
2199         }
2200
2201         /// Returns the smallest power of two greater than or equal to `self`.
2202         ///
2203         /// When return value overflows (i.e. `self > (1 << (N-1))` for type
2204         /// `uN`), it panics in debug mode and return value is wrapped to 0 in
2205         /// release mode (the only situation in which method can return 0).
2206         ///
2207         /// # Examples
2208         ///
2209         /// Basic usage:
2210         ///
2211         /// ```
2212         /// assert_eq!(2u8.next_power_of_two(), 2);
2213         /// assert_eq!(3u8.next_power_of_two(), 4);
2214         /// ```
2215         #[stable(feature = "rust1", since = "1.0.0")]
2216         #[inline]
2217         pub fn next_power_of_two(self) -> Self {
2218             self.one_less_than_next_power_of_two() + 1
2219         }
2220
2221         /// Returns the smallest power of two greater than or equal to `n`. If
2222         /// the next power of two is greater than the type's maximum value,
2223         /// `None` is returned, otherwise the power of two is wrapped in `Some`.
2224         ///
2225         /// # Examples
2226         ///
2227         /// Basic usage:
2228         ///
2229         /// ```
2230         /// assert_eq!(2u8.checked_next_power_of_two(), Some(2));
2231         /// assert_eq!(3u8.checked_next_power_of_two(), Some(4));
2232         /// assert_eq!(200u8.checked_next_power_of_two(), None);
2233         /// ```
2234         #[stable(feature = "rust1", since = "1.0.0")]
2235         pub fn checked_next_power_of_two(self) -> Option<Self> {
2236             self.one_less_than_next_power_of_two().checked_add(1)
2237         }
2238     }
2239 }
2240
2241 #[cfg(stage0)]
2242 unsafe fn ctlz_nonzero<T>(x: T) -> T { intrinsics::ctlz(x) }
2243 #[cfg(not(stage0))]
2244 unsafe fn ctlz_nonzero<T>(x: T) -> T { intrinsics::ctlz_nonzero(x) }
2245
2246 #[lang = "u8"]
2247 impl u8 {
2248     uint_impl! { u8, u8, 8,
2249         intrinsics::ctpop,
2250         intrinsics::ctlz,
2251         ctlz_nonzero,
2252         intrinsics::cttz,
2253         intrinsics::bswap,
2254         intrinsics::add_with_overflow,
2255         intrinsics::sub_with_overflow,
2256         intrinsics::mul_with_overflow }
2257 }
2258
2259 #[lang = "u16"]
2260 impl u16 {
2261     uint_impl! { u16, u16, 16,
2262         intrinsics::ctpop,
2263         intrinsics::ctlz,
2264         ctlz_nonzero,
2265         intrinsics::cttz,
2266         intrinsics::bswap,
2267         intrinsics::add_with_overflow,
2268         intrinsics::sub_with_overflow,
2269         intrinsics::mul_with_overflow }
2270 }
2271
2272 #[lang = "u32"]
2273 impl u32 {
2274     uint_impl! { u32, u32, 32,
2275         intrinsics::ctpop,
2276         intrinsics::ctlz,
2277         ctlz_nonzero,
2278         intrinsics::cttz,
2279         intrinsics::bswap,
2280         intrinsics::add_with_overflow,
2281         intrinsics::sub_with_overflow,
2282         intrinsics::mul_with_overflow }
2283 }
2284
2285 #[lang = "u64"]
2286 impl u64 {
2287     uint_impl! { u64, u64, 64,
2288         intrinsics::ctpop,
2289         intrinsics::ctlz,
2290         ctlz_nonzero,
2291         intrinsics::cttz,
2292         intrinsics::bswap,
2293         intrinsics::add_with_overflow,
2294         intrinsics::sub_with_overflow,
2295         intrinsics::mul_with_overflow }
2296 }
2297
2298 #[lang = "u128"]
2299 impl u128 {
2300     uint_impl! { u128, u128, 128,
2301         intrinsics::ctpop,
2302         intrinsics::ctlz,
2303         ctlz_nonzero,
2304         intrinsics::cttz,
2305         intrinsics::bswap,
2306         intrinsics::add_with_overflow,
2307         intrinsics::sub_with_overflow,
2308         intrinsics::mul_with_overflow }
2309 }
2310
2311 #[cfg(target_pointer_width = "16")]
2312 #[lang = "usize"]
2313 impl usize {
2314     uint_impl! { usize, u16, 16,
2315         intrinsics::ctpop,
2316         intrinsics::ctlz,
2317         ctlz_nonzero,
2318         intrinsics::cttz,
2319         intrinsics::bswap,
2320         intrinsics::add_with_overflow,
2321         intrinsics::sub_with_overflow,
2322         intrinsics::mul_with_overflow }
2323 }
2324 #[cfg(target_pointer_width = "32")]
2325 #[lang = "usize"]
2326 impl usize {
2327     uint_impl! { usize, u32, 32,
2328         intrinsics::ctpop,
2329         intrinsics::ctlz,
2330         ctlz_nonzero,
2331         intrinsics::cttz,
2332         intrinsics::bswap,
2333         intrinsics::add_with_overflow,
2334         intrinsics::sub_with_overflow,
2335         intrinsics::mul_with_overflow }
2336 }
2337
2338 #[cfg(target_pointer_width = "64")]
2339 #[lang = "usize"]
2340 impl usize {
2341     uint_impl! { usize, u64, 64,
2342         intrinsics::ctpop,
2343         intrinsics::ctlz,
2344         ctlz_nonzero,
2345         intrinsics::cttz,
2346         intrinsics::bswap,
2347         intrinsics::add_with_overflow,
2348         intrinsics::sub_with_overflow,
2349         intrinsics::mul_with_overflow }
2350 }
2351
2352 /// A classification of floating point numbers.
2353 ///
2354 /// This `enum` is used as the return type for [`f32::classify`] and [`f64::classify`]. See
2355 /// their documentation for more.
2356 ///
2357 /// [`f32::classify`]: ../../std/primitive.f32.html#method.classify
2358 /// [`f64::classify`]: ../../std/primitive.f64.html#method.classify
2359 ///
2360 /// # Examples
2361 ///
2362 /// ```
2363 /// use std::num::FpCategory;
2364 /// use std::f32;
2365 ///
2366 /// let num = 12.4_f32;
2367 /// let inf = f32::INFINITY;
2368 /// let zero = 0f32;
2369 /// let sub: f32 = 1.1754942e-38;
2370 /// let nan = f32::NAN;
2371 ///
2372 /// assert_eq!(num.classify(), FpCategory::Normal);
2373 /// assert_eq!(inf.classify(), FpCategory::Infinite);
2374 /// assert_eq!(zero.classify(), FpCategory::Zero);
2375 /// assert_eq!(nan.classify(), FpCategory::Nan);
2376 /// assert_eq!(sub.classify(), FpCategory::Subnormal);
2377 /// ```
2378 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
2379 #[stable(feature = "rust1", since = "1.0.0")]
2380 pub enum FpCategory {
2381     /// "Not a Number", often obtained by dividing by zero.
2382     #[stable(feature = "rust1", since = "1.0.0")]
2383     Nan,
2384
2385     /// Positive or negative infinity.
2386     #[stable(feature = "rust1", since = "1.0.0")]
2387     Infinite,
2388
2389     /// Positive or negative zero.
2390     #[stable(feature = "rust1", since = "1.0.0")]
2391     Zero,
2392
2393     /// De-normalized floating point representation (less precise than `Normal`).
2394     #[stable(feature = "rust1", since = "1.0.0")]
2395     Subnormal,
2396
2397     /// A regular floating point number.
2398     #[stable(feature = "rust1", since = "1.0.0")]
2399     Normal,
2400 }
2401
2402 /// A built-in floating point number.
2403 #[doc(hidden)]
2404 #[unstable(feature = "core_float",
2405            reason = "stable interface is via `impl f{32,64}` in later crates",
2406            issue = "32110")]
2407 pub trait Float: Sized {
2408     /// Returns `true` if this value is NaN and false otherwise.
2409     #[stable(feature = "core", since = "1.6.0")]
2410     fn is_nan(self) -> bool;
2411     /// Returns `true` if this value is positive infinity or negative infinity and
2412     /// false otherwise.
2413     #[stable(feature = "core", since = "1.6.0")]
2414     fn is_infinite(self) -> bool;
2415     /// Returns `true` if this number is neither infinite nor NaN.
2416     #[stable(feature = "core", since = "1.6.0")]
2417     fn is_finite(self) -> bool;
2418     /// Returns `true` if this number is neither zero, infinite, denormal, or NaN.
2419     #[stable(feature = "core", since = "1.6.0")]
2420     fn is_normal(self) -> bool;
2421     /// Returns the category that this number falls into.
2422     #[stable(feature = "core", since = "1.6.0")]
2423     fn classify(self) -> FpCategory;
2424
2425     /// Computes the absolute value of `self`. Returns `Float::nan()` if the
2426     /// number is `Float::nan()`.
2427     #[stable(feature = "core", since = "1.6.0")]
2428     fn abs(self) -> Self;
2429     /// Returns a number that represents the sign of `self`.
2430     ///
2431     /// - `1.0` if the number is positive, `+0.0` or `Float::infinity()`
2432     /// - `-1.0` if the number is negative, `-0.0` or `Float::neg_infinity()`
2433     /// - `Float::nan()` if the number is `Float::nan()`
2434     #[stable(feature = "core", since = "1.6.0")]
2435     fn signum(self) -> Self;
2436
2437     /// Returns `true` if `self` is positive, including `+0.0` and
2438     /// `Float::infinity()`.
2439     #[stable(feature = "core", since = "1.6.0")]
2440     fn is_sign_positive(self) -> bool;
2441     /// Returns `true` if `self` is negative, including `-0.0` and
2442     /// `Float::neg_infinity()`.
2443     #[stable(feature = "core", since = "1.6.0")]
2444     fn is_sign_negative(self) -> bool;
2445
2446     /// Take the reciprocal (inverse) of a number, `1/x`.
2447     #[stable(feature = "core", since = "1.6.0")]
2448     fn recip(self) -> Self;
2449
2450     /// Raise a number to an integer power.
2451     ///
2452     /// Using this function is generally faster than using `powf`
2453     #[stable(feature = "core", since = "1.6.0")]
2454     fn powi(self, n: i32) -> Self;
2455
2456     /// Convert radians to degrees.
2457     #[stable(feature = "deg_rad_conversions", since="1.7.0")]
2458     fn to_degrees(self) -> Self;
2459     /// Convert degrees to radians.
2460     #[stable(feature = "deg_rad_conversions", since="1.7.0")]
2461     fn to_radians(self) -> Self;
2462 }
2463
2464 macro_rules! from_str_radix_int_impl {
2465     ($($t:ty)*) => {$(
2466         #[stable(feature = "rust1", since = "1.0.0")]
2467         impl FromStr for $t {
2468             type Err = ParseIntError;
2469             fn from_str(src: &str) -> Result<Self, ParseIntError> {
2470                 from_str_radix(src, 10)
2471             }
2472         }
2473     )*}
2474 }
2475 from_str_radix_int_impl! { isize i8 i16 i32 i64 i128 usize u8 u16 u32 u64 u128 }
2476
2477 /// The error type returned when a checked integral type conversion fails.
2478 #[unstable(feature = "try_from", issue = "33417")]
2479 #[derive(Debug, Copy, Clone)]
2480 pub struct TryFromIntError(());
2481
2482 impl TryFromIntError {
2483     #[unstable(feature = "int_error_internals",
2484                reason = "available through Error trait and this method should \
2485                          not be exposed publicly",
2486                issue = "0")]
2487     #[doc(hidden)]
2488     pub fn __description(&self) -> &str {
2489         "out of range integral type conversion attempted"
2490     }
2491 }
2492
2493 #[unstable(feature = "try_from", issue = "33417")]
2494 impl fmt::Display for TryFromIntError {
2495     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
2496         self.__description().fmt(fmt)
2497     }
2498 }
2499
2500 macro_rules! same_sign_try_from_int_impl {
2501     ($storage:ty, $target:ty, $($source:ty),*) => {$(
2502         #[unstable(feature = "try_from", issue = "33417")]
2503         impl TryFrom<$source> for $target {
2504             type Error = TryFromIntError;
2505
2506             fn try_from(u: $source) -> Result<$target, TryFromIntError> {
2507                 let min = <$target as FromStrRadixHelper>::min_value() as $storage;
2508                 let max = <$target as FromStrRadixHelper>::max_value() as $storage;
2509                 if u as $storage < min || u as $storage > max {
2510                     Err(TryFromIntError(()))
2511                 } else {
2512                     Ok(u as $target)
2513                 }
2514             }
2515         }
2516     )*}
2517 }
2518
2519 same_sign_try_from_int_impl!(u128, u8, u8, u16, u32, u64, u128, usize);
2520 same_sign_try_from_int_impl!(i128, i8, i8, i16, i32, i64, i128, isize);
2521 same_sign_try_from_int_impl!(u128, u16, u8, u16, u32, u64, u128, usize);
2522 same_sign_try_from_int_impl!(i128, i16, i8, i16, i32, i64, i128, isize);
2523 same_sign_try_from_int_impl!(u128, u32, u8, u16, u32, u64, u128, usize);
2524 same_sign_try_from_int_impl!(i128, i32, i8, i16, i32, i64, i128, isize);
2525 same_sign_try_from_int_impl!(u128, u64, u8, u16, u32, u64, u128, usize);
2526 same_sign_try_from_int_impl!(i128, i64, i8, i16, i32, i64, i128, isize);
2527 same_sign_try_from_int_impl!(u128, u128, u8, u16, u32, u64, u128, usize);
2528 same_sign_try_from_int_impl!(i128, i128, i8, i16, i32, i64, i128, isize);
2529 same_sign_try_from_int_impl!(u128, usize, u8, u16, u32, u64, u128, usize);
2530 same_sign_try_from_int_impl!(i128, isize, i8, i16, i32, i64, i128, isize);
2531
2532 macro_rules! cross_sign_from_int_impl {
2533     ($unsigned:ty, $($signed:ty),*) => {$(
2534         #[unstable(feature = "try_from", issue = "33417")]
2535         impl TryFrom<$unsigned> for $signed {
2536             type Error = TryFromIntError;
2537
2538             fn try_from(u: $unsigned) -> Result<$signed, TryFromIntError> {
2539                 let max = <$signed as FromStrRadixHelper>::max_value() as u128;
2540                 if u as u128 > max {
2541                     Err(TryFromIntError(()))
2542                 } else {
2543                     Ok(u as $signed)
2544                 }
2545             }
2546         }
2547
2548         #[unstable(feature = "try_from", issue = "33417")]
2549         impl TryFrom<$signed> for $unsigned {
2550             type Error = TryFromIntError;
2551
2552             fn try_from(u: $signed) -> Result<$unsigned, TryFromIntError> {
2553                 let max = <$unsigned as FromStrRadixHelper>::max_value() as u128;
2554                 if u < 0 || u as u128 > max {
2555                     Err(TryFromIntError(()))
2556                 } else {
2557                     Ok(u as $unsigned)
2558                 }
2559             }
2560         }
2561     )*}
2562 }
2563
2564 cross_sign_from_int_impl!(u8, i8, i16, i32, i64, i128, isize);
2565 cross_sign_from_int_impl!(u16, i8, i16, i32, i64, i128, isize);
2566 cross_sign_from_int_impl!(u32, i8, i16, i32, i64, i128, isize);
2567 cross_sign_from_int_impl!(u64, i8, i16, i32, i64, i128, isize);
2568 cross_sign_from_int_impl!(u128, i8, i16, i32, i64, i128, isize);
2569 cross_sign_from_int_impl!(usize, i8, i16, i32, i64, i128, isize);
2570
2571 #[doc(hidden)]
2572 trait FromStrRadixHelper: PartialOrd + Copy {
2573     fn min_value() -> Self;
2574     fn max_value() -> Self;
2575     fn from_u32(u: u32) -> Self;
2576     fn checked_mul(&self, other: u32) -> Option<Self>;
2577     fn checked_sub(&self, other: u32) -> Option<Self>;
2578     fn checked_add(&self, other: u32) -> Option<Self>;
2579 }
2580
2581 macro_rules! doit {
2582     ($($t:ty)*) => ($(impl FromStrRadixHelper for $t {
2583         fn min_value() -> Self { Self::min_value() }
2584         fn max_value() -> Self { Self::max_value() }
2585         fn from_u32(u: u32) -> Self { u as Self }
2586         fn checked_mul(&self, other: u32) -> Option<Self> {
2587             Self::checked_mul(*self, other as Self)
2588         }
2589         fn checked_sub(&self, other: u32) -> Option<Self> {
2590             Self::checked_sub(*self, other as Self)
2591         }
2592         fn checked_add(&self, other: u32) -> Option<Self> {
2593             Self::checked_add(*self, other as Self)
2594         }
2595     })*)
2596 }
2597 doit! { i8 i16 i32 i64 i128 isize u8 u16 u32 u64 u128 usize }
2598
2599 fn from_str_radix<T: FromStrRadixHelper>(src: &str, radix: u32) -> Result<T, ParseIntError> {
2600     use self::IntErrorKind::*;
2601     use self::ParseIntError as PIE;
2602
2603     assert!(radix >= 2 && radix <= 36,
2604            "from_str_radix_int: must lie in the range `[2, 36]` - found {}",
2605            radix);
2606
2607     if src.is_empty() {
2608         return Err(PIE { kind: Empty });
2609     }
2610
2611     let is_signed_ty = T::from_u32(0) > T::min_value();
2612
2613     // all valid digits are ascii, so we will just iterate over the utf8 bytes
2614     // and cast them to chars. .to_digit() will safely return None for anything
2615     // other than a valid ascii digit for the given radix, including the first-byte
2616     // of multi-byte sequences
2617     let src = src.as_bytes();
2618
2619     let (is_positive, digits) = match src[0] {
2620         b'+' => (true, &src[1..]),
2621         b'-' if is_signed_ty => (false, &src[1..]),
2622         _ => (true, src),
2623     };
2624
2625     if digits.is_empty() {
2626         return Err(PIE { kind: Empty });
2627     }
2628
2629     let mut result = T::from_u32(0);
2630     if is_positive {
2631         // The number is positive
2632         for &c in digits {
2633             let x = match (c as char).to_digit(radix) {
2634                 Some(x) => x,
2635                 None => return Err(PIE { kind: InvalidDigit }),
2636             };
2637             result = match result.checked_mul(radix) {
2638                 Some(result) => result,
2639                 None => return Err(PIE { kind: Overflow }),
2640             };
2641             result = match result.checked_add(x) {
2642                 Some(result) => result,
2643                 None => return Err(PIE { kind: Overflow }),
2644             };
2645         }
2646     } else {
2647         // The number is negative
2648         for &c in digits {
2649             let x = match (c as char).to_digit(radix) {
2650                 Some(x) => x,
2651                 None => return Err(PIE { kind: InvalidDigit }),
2652             };
2653             result = match result.checked_mul(radix) {
2654                 Some(result) => result,
2655                 None => return Err(PIE { kind: Underflow }),
2656             };
2657             result = match result.checked_sub(x) {
2658                 Some(result) => result,
2659                 None => return Err(PIE { kind: Underflow }),
2660             };
2661         }
2662     }
2663     Ok(result)
2664 }
2665
2666 /// An error which can be returned when parsing an integer.
2667 ///
2668 /// This error is used as the error type for the `from_str_radix()` functions
2669 /// on the primitive integer types, such as [`i8::from_str_radix`].
2670 ///
2671 /// [`i8::from_str_radix`]: ../../std/primitive.i8.html#method.from_str_radix
2672 #[derive(Debug, Clone, PartialEq, Eq)]
2673 #[stable(feature = "rust1", since = "1.0.0")]
2674 pub struct ParseIntError {
2675     kind: IntErrorKind,
2676 }
2677
2678 #[derive(Debug, Clone, PartialEq, Eq)]
2679 enum IntErrorKind {
2680     Empty,
2681     InvalidDigit,
2682     Overflow,
2683     Underflow,
2684 }
2685
2686 impl ParseIntError {
2687     #[unstable(feature = "int_error_internals",
2688                reason = "available through Error trait and this method should \
2689                          not be exposed publicly",
2690                issue = "0")]
2691     #[doc(hidden)]
2692     pub fn __description(&self) -> &str {
2693         match self.kind {
2694             IntErrorKind::Empty => "cannot parse integer from empty string",
2695             IntErrorKind::InvalidDigit => "invalid digit found in string",
2696             IntErrorKind::Overflow => "number too large to fit in target type",
2697             IntErrorKind::Underflow => "number too small to fit in target type",
2698         }
2699     }
2700 }
2701
2702 #[stable(feature = "rust1", since = "1.0.0")]
2703 impl fmt::Display for ParseIntError {
2704     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
2705         self.__description().fmt(f)
2706     }
2707 }
2708
2709 #[stable(feature = "rust1", since = "1.0.0")]
2710 pub use num::dec2flt::ParseFloatError;
2711
2712 // Conversion traits for primitive integer and float types
2713 // Conversions T -> T are covered by a blanket impl and therefore excluded
2714 // Some conversions from and to usize/isize are not implemented due to portability concerns
2715 macro_rules! impl_from {
2716     ($Small: ty, $Large: ty, #[$attr:meta]) => {
2717         #[$attr]
2718         impl From<$Small> for $Large {
2719             #[inline]
2720             fn from(small: $Small) -> $Large {
2721                 small as $Large
2722             }
2723         }
2724     }
2725 }
2726
2727 // Unsigned -> Unsigned
2728 impl_from! { u8, u16, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2729 impl_from! { u8, u32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2730 impl_from! { u8, u64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2731 impl_from! { u8, u128, #[unstable(feature = "i128", issue = "35118")] }
2732 impl_from! { u8, usize, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2733 impl_from! { u16, u32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2734 impl_from! { u16, u64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2735 impl_from! { u16, u128, #[unstable(feature = "i128", issue = "35118")] }
2736 impl_from! { u32, u64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2737 impl_from! { u32, u128, #[unstable(feature = "i128", issue = "35118")] }
2738 impl_from! { u64, u128, #[unstable(feature = "i128", issue = "35118")] }
2739
2740 // Signed -> Signed
2741 impl_from! { i8, i16, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2742 impl_from! { i8, i32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2743 impl_from! { i8, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2744 impl_from! { i8, i128, #[unstable(feature = "i128", issue = "35118")] }
2745 impl_from! { i8, isize, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2746 impl_from! { i16, i32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2747 impl_from! { i16, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2748 impl_from! { i16, i128, #[unstable(feature = "i128", issue = "35118")] }
2749 impl_from! { i32, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2750 impl_from! { i32, i128, #[unstable(feature = "i128", issue = "35118")] }
2751 impl_from! { i64, i128, #[unstable(feature = "i128", issue = "35118")] }
2752
2753 // Unsigned -> Signed
2754 impl_from! { u8, i16, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2755 impl_from! { u8, i32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2756 impl_from! { u8, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2757 impl_from! { u8, i128, #[unstable(feature = "i128", issue = "35118")] }
2758 impl_from! { u16, i32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2759 impl_from! { u16, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2760 impl_from! { u16, i128, #[unstable(feature = "i128", issue = "35118")] }
2761 impl_from! { u32, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2762 impl_from! { u32, i128, #[unstable(feature = "i128", issue = "35118")] }
2763 impl_from! { u64, i128, #[unstable(feature = "i128", issue = "35118")] }
2764
2765 // Note: integers can only be represented with full precision in a float if
2766 // they fit in the significand, which is 24 bits in f32 and 53 bits in f64.
2767 // Lossy float conversions are not implemented at this time.
2768
2769 // Signed -> Float
2770 impl_from! { i8, f32, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
2771 impl_from! { i8, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
2772 impl_from! { i16, f32, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
2773 impl_from! { i16, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
2774 impl_from! { i32, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
2775
2776 // Unsigned -> Float
2777 impl_from! { u8, f32, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
2778 impl_from! { u8, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
2779 impl_from! { u16, f32, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
2780 impl_from! { u16, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
2781 impl_from! { u32, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
2782
2783 // Float -> Float
2784 impl_from! { f32, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }