src/libcore/num/mod.rs

   1 // Copyright 2012-2014 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 //! Numeric traits and functions for the built-in numeric types.
  12
  13 #![stable(feature = "rust1", since = "1.0.0")]
  14
  15 use convert::TryFrom;
  16 use fmt;
  17 use intrinsics;
  18 use mem::size_of;
  19 use str::FromStr;
  20
  21 /// Provides intentionally-wrapped arithmetic on `T`.
  22 ///
  23 /// Operations like `+` on `u32` values is intended to never overflow,
  24 /// and in some debug configurations overflow is detected and results
  25 /// in a panic. While most arithmetic falls into this category, some
  26 /// code explicitly expects and relies upon modular arithmetic (e.g.,
  27 /// hashing).
  28 ///
  29 /// Wrapping arithmetic can be achieved either through methods like
  30 /// `wrapping_add`, or through the `Wrapping<T>` type, which says that
  31 /// all standard arithmetic operations on the underlying value are
  32 /// intended to have wrapping semantics.
  33 ///
  34 /// # Examples
  35 ///
  36 /// ```
  37 /// use std::num::Wrapping;
  38 ///
  39 /// let zero = Wrapping(0u32);
  40 /// let one = Wrapping(1u32);
  41 ///
  42 /// assert_eq!(std::u32::MAX, (zero - one).0);
  43 /// ```
  44 #[stable(feature = "rust1", since = "1.0.0")]
  45 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Copy, Default, Hash)]
  46 pub struct Wrapping<T>(#[stable(feature = "rust1", since = "1.0.0")]
  47                        pub T);
  48
  49 #[stable(feature = "rust1", since = "1.0.0")]
  50 impl<T: fmt::Debug> fmt::Debug for Wrapping<T> {
  51     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
  52         self.0.fmt(f)
  53     }
  54 }
  55
  56 #[stable(feature = "wrapping_display", since = "1.10.0")]
  57 impl<T: fmt::Display> fmt::Display for Wrapping<T> {
  58     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
  59         self.0.fmt(f)
  60     }
  61 }
  62
  63 #[stable(feature = "wrapping_fmt", since = "1.11.0")]
  64 impl<T: fmt::Binary> fmt::Binary for Wrapping<T> {
  65     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
  66         self.0.fmt(f)
  67     }
  68 }
  69
  70 #[stable(feature = "wrapping_fmt", since = "1.11.0")]
  71 impl<T: fmt::Octal> fmt::Octal for Wrapping<T> {
  72     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
  73         self.0.fmt(f)
  74     }
  75 }
  76
  77 #[stable(feature = "wrapping_fmt", since = "1.11.0")]
  78 impl<T: fmt::LowerHex> fmt::LowerHex for Wrapping<T> {
  79     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
  80         self.0.fmt(f)
  81     }
  82 }
  83
  84 #[stable(feature = "wrapping_fmt", since = "1.11.0")]
  85 impl<T: fmt::UpperHex> fmt::UpperHex for Wrapping<T> {
  86     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
  87         self.0.fmt(f)
  88     }
  89 }
  90
  91 mod wrapping;
  92
  93 // All these modules are technically private and only exposed for coretests:
  94 pub mod flt2dec;
  95 pub mod dec2flt;
  96 pub mod bignum;
  97 pub mod diy_float;
  98
  99 // `Int` + `SignedInt` implemented for signed integers
 100 macro_rules! int_impl {
 101     ($SelfT:ty, $ActualT:ident, $UnsignedT:ty, $BITS:expr,
 102      $add_with_overflow:path,
 103      $sub_with_overflow:path,
 104      $mul_with_overflow:path) => {
 105         /// Returns the smallest value that can be represented by this integer type.
 106         ///
 107         /// # Examples
 108         ///
 109         /// ```
 110         /// assert_eq!(i8::min_value(), -128);
 111         /// ```
 112         #[stable(feature = "rust1", since = "1.0.0")]
 113         #[inline]
 114         pub const fn min_value() -> Self {
 115             !0 ^ ((!0 as $UnsignedT) >> 1) as Self
 116         }
 117
 118         /// Returns the largest value that can be represented by this integer type.
 119         ///
 120         /// # Examples
 121         ///
 122         /// ```
 123         /// assert_eq!(i8::max_value(), 127);
 124         /// ```
 125         #[stable(feature = "rust1", since = "1.0.0")]
 126         #[inline]
 127         pub const fn max_value() -> Self {
 128             !Self::min_value()
 129         }
 130
 131         /// Converts a string slice in a given base to an integer.
 132         ///
 133         /// Leading and trailing whitespace represent an error.
 134         ///
 135         /// # Examples
 136         ///
 137         /// Basic usage:
 138         ///
 139         /// ```
 140         /// assert_eq!(i32::from_str_radix("A", 16), Ok(10));
 141         /// ```
 142         #[stable(feature = "rust1", since = "1.0.0")]
 143         pub fn from_str_radix(src: &str, radix: u32) -> Result<Self, ParseIntError> {
 144             from_str_radix(src, radix)
 145         }
 146
 147         /// Returns the number of ones in the binary representation of `self`.
 148         ///
 149         /// # Examples
 150         ///
 151         /// Basic usage:
 152         ///
 153         /// ```
 154         /// let n = -0b1000_0000i8;
 155         ///
 156         /// assert_eq!(n.count_ones(), 1);
 157         /// ```
 158         #[stable(feature = "rust1", since = "1.0.0")]
 159         #[inline]
 160         pub fn count_ones(self) -> u32 { (self as $UnsignedT).count_ones() }
 161
 162         /// Returns the number of zeros in the binary representation of `self`.
 163         ///
 164         /// # Examples
 165         ///
 166         /// Basic usage:
 167         ///
 168         /// ```
 169         /// let n = -0b1000_0000i8;
 170         ///
 171         /// assert_eq!(n.count_zeros(), 7);
 172         /// ```
 173         #[stable(feature = "rust1", since = "1.0.0")]
 174         #[inline]
 175         pub fn count_zeros(self) -> u32 {
 176             (!self).count_ones()
 177         }
 178
 179         /// Returns the number of leading zeros in the binary representation
 180         /// of `self`.
 181         ///
 182         /// # Examples
 183         ///
 184         /// Basic usage:
 185         ///
 186         /// ```
 187         /// let n = -1i16;
 188         ///
 189         /// assert_eq!(n.leading_zeros(), 0);
 190         /// ```
 191         #[stable(feature = "rust1", since = "1.0.0")]
 192         #[inline]
 193         pub fn leading_zeros(self) -> u32 {
 194             (self as $UnsignedT).leading_zeros()
 195         }
 196
 197         /// Returns the number of trailing zeros in the binary representation
 198         /// of `self`.
 199         ///
 200         /// # Examples
 201         ///
 202         /// Basic usage:
 203         ///
 204         /// ```
 205         /// let n = -4i8;
 206         ///
 207         /// assert_eq!(n.trailing_zeros(), 2);
 208         /// ```
 209         #[stable(feature = "rust1", since = "1.0.0")]
 210         #[inline]
 211         pub fn trailing_zeros(self) -> u32 {
 212             (self as $UnsignedT).trailing_zeros()
 213         }
 214
 215         /// Shifts the bits to the left by a specified amount, `n`,
 216         /// wrapping the truncated bits to the end of the resulting integer.
 217         ///
 218         /// Please note this isn't the same operation as `<<`!
 219         ///
 220         /// # Examples
 221         ///
 222         /// Basic usage:
 223         ///
 224         /// ```
 225         /// let n = 0x0123456789ABCDEFi64;
 226         /// let m = -0x76543210FEDCBA99i64;
 227         ///
 228         /// assert_eq!(n.rotate_left(32), m);
 229         /// ```
 230         #[stable(feature = "rust1", since = "1.0.0")]
 231         #[inline]
 232         pub fn rotate_left(self, n: u32) -> Self {
 233             (self as $UnsignedT).rotate_left(n) as Self
 234         }
 235
 236         /// Shifts the bits to the right by a specified amount, `n`,
 237         /// wrapping the truncated bits to the beginning of the resulting
 238         /// integer.
 239         ///
 240         /// Please note this isn't the same operation as `>>`!
 241         ///
 242         /// # Examples
 243         ///
 244         /// Basic usage:
 245         ///
 246         /// ```
 247         /// let n = 0x0123456789ABCDEFi64;
 248         /// let m = -0xFEDCBA987654322i64;
 249         ///
 250         /// assert_eq!(n.rotate_right(4), m);
 251         /// ```
 252         #[stable(feature = "rust1", since = "1.0.0")]
 253         #[inline]
 254         pub fn rotate_right(self, n: u32) -> Self {
 255             (self as $UnsignedT).rotate_right(n) as Self
 256         }
 257
 258         /// Reverses the byte order of the integer.
 259         ///
 260         /// # Examples
 261         ///
 262         /// Basic usage:
 263         ///
 264         /// ```
 265         /// let n =  0x0123456789ABCDEFi64;
 266         /// let m = -0x1032547698BADCFFi64;
 267         ///
 268         /// assert_eq!(n.swap_bytes(), m);
 269         /// ```
 270         #[stable(feature = "rust1", since = "1.0.0")]
 271         #[inline]
 272         pub fn swap_bytes(self) -> Self {
 273             (self as $UnsignedT).swap_bytes() as Self
 274         }
 275
 276         /// Converts an integer from big endian to the target's endianness.
 277         ///
 278         /// On big endian this is a no-op. On little endian the bytes are
 279         /// swapped.
 280         ///
 281         /// # Examples
 282         ///
 283         /// Basic usage:
 284         ///
 285         /// ```
 286         /// let n = 0x0123456789ABCDEFi64;
 287         ///
 288         /// if cfg!(target_endian = "big") {
 289         ///     assert_eq!(i64::from_be(n), n)
 290         /// } else {
 291         ///     assert_eq!(i64::from_be(n), n.swap_bytes())
 292         /// }
 293         /// ```
 294         #[stable(feature = "rust1", since = "1.0.0")]
 295         #[inline]
 296         pub fn from_be(x: Self) -> Self {
 297             if cfg!(target_endian = "big") { x } else { x.swap_bytes() }
 298         }
 299
 300         /// Converts an integer from little endian to the target's endianness.
 301         ///
 302         /// On little endian this is a no-op. On big endian the bytes are
 303         /// swapped.
 304         ///
 305         /// # Examples
 306         ///
 307         /// Basic usage:
 308         ///
 309         /// ```
 310         /// let n = 0x0123456789ABCDEFi64;
 311         ///
 312         /// if cfg!(target_endian = "little") {
 313         ///     assert_eq!(i64::from_le(n), n)
 314         /// } else {
 315         ///     assert_eq!(i64::from_le(n), n.swap_bytes())
 316         /// }
 317         /// ```
 318         #[stable(feature = "rust1", since = "1.0.0")]
 319         #[inline]
 320         pub fn from_le(x: Self) -> Self {
 321             if cfg!(target_endian = "little") { x } else { x.swap_bytes() }
 322         }
 323
 324         /// Converts `self` to big endian from the target's endianness.
 325         ///
 326         /// On big endian this is a no-op. On little endian the bytes are
 327         /// swapped.
 328         ///
 329         /// # Examples
 330         ///
 331         /// Basic usage:
 332         ///
 333         /// ```
 334         /// let n = 0x0123456789ABCDEFi64;
 335         ///
 336         /// if cfg!(target_endian = "big") {
 337         ///     assert_eq!(n.to_be(), n)
 338         /// } else {
 339         ///     assert_eq!(n.to_be(), n.swap_bytes())
 340         /// }
 341         /// ```
 342         #[stable(feature = "rust1", since = "1.0.0")]
 343         #[inline]
 344         pub fn to_be(self) -> Self { // or not to be?
 345             if cfg!(target_endian = "big") { self } else { self.swap_bytes() }
 346         }
 347
 348         /// Converts `self` to little endian from the target's endianness.
 349         ///
 350         /// On little endian this is a no-op. On big endian the bytes are
 351         /// swapped.
 352         ///
 353         /// # Examples
 354         ///
 355         /// Basic usage:
 356         ///
 357         /// ```
 358         /// let n = 0x0123456789ABCDEFi64;
 359         ///
 360         /// if cfg!(target_endian = "little") {
 361         ///     assert_eq!(n.to_le(), n)
 362         /// } else {
 363         ///     assert_eq!(n.to_le(), n.swap_bytes())
 364         /// }
 365         /// ```
 366         #[stable(feature = "rust1", since = "1.0.0")]
 367         #[inline]
 368         pub fn to_le(self) -> Self {
 369             if cfg!(target_endian = "little") { self } else { self.swap_bytes() }
 370         }
 371
 372         /// Checked integer addition. Computes `self + other`, returning `None`
 373         /// if overflow occurred.
 374         ///
 375         /// # Examples
 376         ///
 377         /// Basic usage:
 378         ///
 379         /// ```
 380         /// assert_eq!(7i16.checked_add(32760), Some(32767));
 381         /// assert_eq!(8i16.checked_add(32760), None);
 382         /// ```
 383         #[stable(feature = "rust1", since = "1.0.0")]
 384         #[inline]
 385         pub fn checked_add(self, other: Self) -> Option<Self> {
 386             let (a, b) = self.overflowing_add(other);
 387             if b {None} else {Some(a)}
 388         }
 389
 390         /// Checked integer subtraction. Computes `self - other`, returning
 391         /// `None` if underflow occurred.
 392         ///
 393         /// # Examples
 394         ///
 395         /// Basic usage:
 396         ///
 397         /// ```
 398         /// assert_eq!((-127i8).checked_sub(1), Some(-128));
 399         /// assert_eq!((-128i8).checked_sub(1), None);
 400         /// ```
 401         #[stable(feature = "rust1", since = "1.0.0")]
 402         #[inline]
 403         pub fn checked_sub(self, other: Self) -> Option<Self> {
 404             let (a, b) = self.overflowing_sub(other);
 405             if b {None} else {Some(a)}
 406         }
 407
 408         /// Checked integer multiplication. Computes `self * other`, returning
 409         /// `None` if underflow or overflow occurred.
 410         ///
 411         /// # Examples
 412         ///
 413         /// Basic usage:
 414         ///
 415         /// ```
 416         /// assert_eq!(6i8.checked_mul(21), Some(126));
 417         /// assert_eq!(6i8.checked_mul(22), None);
 418         /// ```
 419         #[stable(feature = "rust1", since = "1.0.0")]
 420         #[inline]
 421         pub fn checked_mul(self, other: Self) -> Option<Self> {
 422             let (a, b) = self.overflowing_mul(other);
 423             if b {None} else {Some(a)}
 424         }
 425
 426         /// Checked integer division. Computes `self / other`, returning `None`
 427         /// if `other == 0` or the operation results in underflow or overflow.
 428         ///
 429         /// # Examples
 430         ///
 431         /// Basic usage:
 432         ///
 433         /// ```
 434         /// assert_eq!((-127i8).checked_div(-1), Some(127));
 435         /// assert_eq!((-128i8).checked_div(-1), None);
 436         /// assert_eq!((1i8).checked_div(0), None);
 437         /// ```
 438         #[stable(feature = "rust1", since = "1.0.0")]
 439         #[inline]
 440         pub fn checked_div(self, other: Self) -> Option<Self> {
 441             if other == 0 || (self == Self::min_value() && other == -1) {
 442                 None
 443             } else {
 444                 Some(unsafe { intrinsics::unchecked_div(self, other) })
 445             }
 446         }
 447
 448         /// Checked integer remainder. Computes `self % other`, returning `None`
 449         /// if `other == 0` or the operation results in underflow or overflow.
 450         ///
 451         /// # Examples
 452         ///
 453         /// Basic usage:
 454         ///
 455         /// ```
 456         /// use std::i32;
 457         ///
 458         /// assert_eq!(5i32.checked_rem(2), Some(1));
 459         /// assert_eq!(5i32.checked_rem(0), None);
 460         /// assert_eq!(i32::MIN.checked_rem(-1), None);
 461         /// ```
 462         #[stable(feature = "wrapping", since = "1.7.0")]
 463         #[inline]
 464         pub fn checked_rem(self, other: Self) -> Option<Self> {
 465             if other == 0 || (self == Self::min_value() && other == -1) {
 466                 None
 467             } else {
 468                 Some(unsafe { intrinsics::unchecked_rem(self, other) })
 469             }
 470         }
 471
 472         /// Checked negation. Computes `-self`, returning `None` if `self ==
 473         /// MIN`.
 474         ///
 475         /// # Examples
 476         ///
 477         /// Basic usage:
 478         ///
 479         /// ```
 480         /// use std::i32;
 481         ///
 482         /// assert_eq!(5i32.checked_neg(), Some(-5));
 483         /// assert_eq!(i32::MIN.checked_neg(), None);
 484         /// ```
 485         #[stable(feature = "wrapping", since = "1.7.0")]
 486         #[inline]
 487         pub fn checked_neg(self) -> Option<Self> {
 488             let (a, b) = self.overflowing_neg();
 489             if b {None} else {Some(a)}
 490         }
 491
 492         /// Checked shift left. Computes `self << rhs`, returning `None`
 493         /// if `rhs` is larger than or equal to the number of bits in `self`.
 494         ///
 495         /// # Examples
 496         ///
 497         /// Basic usage:
 498         ///
 499         /// ```
 500         /// assert_eq!(0x10i32.checked_shl(4), Some(0x100));
 501         /// assert_eq!(0x10i32.checked_shl(33), None);
 502         /// ```
 503         #[stable(feature = "wrapping", since = "1.7.0")]
 504         #[inline]
 505         pub fn checked_shl(self, rhs: u32) -> Option<Self> {
 506             let (a, b) = self.overflowing_shl(rhs);
 507             if b {None} else {Some(a)}
 508         }
 509
 510         /// Checked shift right. Computes `self >> rhs`, returning `None`
 511         /// if `rhs` is larger than or equal to the number of bits in `self`.
 512         ///
 513         /// # Examples
 514         ///
 515         /// Basic usage:
 516         ///
 517         /// ```
 518         /// assert_eq!(0x10i32.checked_shr(4), Some(0x1));
 519         /// assert_eq!(0x10i32.checked_shr(33), None);
 520         /// ```
 521         #[stable(feature = "wrapping", since = "1.7.0")]
 522         #[inline]
 523         pub fn checked_shr(self, rhs: u32) -> Option<Self> {
 524             let (a, b) = self.overflowing_shr(rhs);
 525             if b {None} else {Some(a)}
 526         }
 527
 528         /// Checked absolute value. Computes `self.abs()`, returning `None` if
 529         /// `self == MIN`.
 530         ///
 531         /// # Examples
 532         ///
 533         /// Basic usage:
 534         ///
 535         /// ```
 536         /// use std::i32;
 537         ///
 538         /// assert_eq!((-5i32).checked_abs(), Some(5));
 539         /// assert_eq!(i32::MIN.checked_abs(), None);
 540         /// ```
 541         #[stable(feature = "no_panic_abs", since = "1.13.0")]
 542         #[inline]
 543         pub fn checked_abs(self) -> Option<Self> {
 544             if self.is_negative() {
 545                 self.checked_neg()
 546             } else {
 547                 Some(self)
 548             }
 549         }
 550
 551         /// Saturating integer addition. Computes `self + other`, saturating at
 552         /// the numeric bounds instead of overflowing.
 553         ///
 554         /// # Examples
 555         ///
 556         /// Basic usage:
 557         ///
 558         /// ```
 559         /// assert_eq!(100i8.saturating_add(1), 101);
 560         /// assert_eq!(100i8.saturating_add(127), 127);
 561         /// ```
 562         #[stable(feature = "rust1", since = "1.0.0")]
 563         #[inline]
 564         pub fn saturating_add(self, other: Self) -> Self {
 565             match self.checked_add(other) {
 566                 Some(x) => x,
 567                 None if other >= 0 => Self::max_value(),
 568                 None => Self::min_value(),
 569             }
 570         }
 571
 572         /// Saturating integer subtraction. Computes `self - other`, saturating
 573         /// at the numeric bounds instead of overflowing.
 574         ///
 575         /// # Examples
 576         ///
 577         /// Basic usage:
 578         ///
 579         /// ```
 580         /// assert_eq!(100i8.saturating_sub(127), -27);
 581         /// assert_eq!((-100i8).saturating_sub(127), -128);
 582         /// ```
 583         #[stable(feature = "rust1", since = "1.0.0")]
 584         #[inline]
 585         pub fn saturating_sub(self, other: Self) -> Self {
 586             match self.checked_sub(other) {
 587                 Some(x) => x,
 588                 None if other >= 0 => Self::min_value(),
 589                 None => Self::max_value(),
 590             }
 591         }
 592
 593         /// Saturating integer multiplication. Computes `self * other`,
 594         /// saturating at the numeric bounds instead of overflowing.
 595         ///
 596         /// # Examples
 597         ///
 598         /// Basic usage:
 599         ///
 600         /// ```
 601         /// use std::i32;
 602         ///
 603         /// assert_eq!(100i32.saturating_mul(127), 12700);
 604         /// assert_eq!((1i32 << 23).saturating_mul(1 << 23), i32::MAX);
 605         /// assert_eq!((-1i32 << 23).saturating_mul(1 << 23), i32::MIN);
 606         /// ```
 607         #[stable(feature = "wrapping", since = "1.7.0")]
 608         #[inline]
 609         pub fn saturating_mul(self, other: Self) -> Self {
 610             self.checked_mul(other).unwrap_or_else(|| {
 611                 if (self < 0 && other < 0) || (self > 0 && other > 0) {
 612                     Self::max_value()
 613                 } else {
 614                     Self::min_value()
 615                 }
 616             })
 617         }
 618
 619         /// Wrapping (modular) addition. Computes `self + other`,
 620         /// wrapping around at the boundary of the type.
 621         ///
 622         /// # Examples
 623         ///
 624         /// Basic usage:
 625         ///
 626         /// ```
 627         /// assert_eq!(100i8.wrapping_add(27), 127);
 628         /// assert_eq!(100i8.wrapping_add(127), -29);
 629         /// ```
 630         #[stable(feature = "rust1", since = "1.0.0")]
 631         #[inline]
 632         pub fn wrapping_add(self, rhs: Self) -> Self {
 633             unsafe {
 634                 intrinsics::overflowing_add(self, rhs)
 635             }
 636         }
 637
 638         /// Wrapping (modular) subtraction. Computes `self - other`,
 639         /// wrapping around at the boundary of the type.
 640         ///
 641         /// # Examples
 642         ///
 643         /// Basic usage:
 644         ///
 645         /// ```
 646         /// assert_eq!(0i8.wrapping_sub(127), -127);
 647         /// assert_eq!((-2i8).wrapping_sub(127), 127);
 648         /// ```
 649         #[stable(feature = "rust1", since = "1.0.0")]
 650         #[inline]
 651         pub fn wrapping_sub(self, rhs: Self) -> Self {
 652             unsafe {
 653                 intrinsics::overflowing_sub(self, rhs)
 654             }
 655         }
 656
 657         /// Wrapping (modular) multiplication. Computes `self *
 658         /// other`, wrapping around at the boundary of the type.
 659         ///
 660         /// # Examples
 661         ///
 662         /// Basic usage:
 663         ///
 664         /// ```
 665         /// assert_eq!(10i8.wrapping_mul(12), 120);
 666         /// assert_eq!(11i8.wrapping_mul(12), -124);
 667         /// ```
 668         #[stable(feature = "rust1", since = "1.0.0")]
 669         #[inline]
 670         pub fn wrapping_mul(self, rhs: Self) -> Self {
 671             unsafe {
 672                 intrinsics::overflowing_mul(self, rhs)
 673             }
 674         }
 675
 676         /// Wrapping (modular) division. Computes `self / other`,
 677         /// wrapping around at the boundary of the type.
 678         ///
 679         /// The only case where such wrapping can occur is when one
 680         /// divides `MIN / -1` on a signed type (where `MIN` is the
 681         /// negative minimal value for the type); this is equivalent
 682         /// to `-MIN`, a positive value that is too large to represent
 683         /// in the type. In such a case, this function returns `MIN`
 684         /// itself.
 685         ///
 686         /// # Panics
 687         ///
 688         /// This function will panic if `rhs` is 0.
 689         ///
 690         /// # Examples
 691         ///
 692         /// Basic usage:
 693         ///
 694         /// ```
 695         /// assert_eq!(100u8.wrapping_div(10), 10);
 696         /// assert_eq!((-128i8).wrapping_div(-1), -128);
 697         /// ```
 698         #[stable(feature = "num_wrapping", since = "1.2.0")]
 699         #[inline(always)]
 700         pub fn wrapping_div(self, rhs: Self) -> Self {
 701             self.overflowing_div(rhs).0
 702         }
 703
 704         /// Wrapping (modular) remainder. Computes `self % other`,
 705         /// wrapping around at the boundary of the type.
 706         ///
 707         /// Such wrap-around never actually occurs mathematically;
 708         /// implementation artifacts make `x % y` invalid for `MIN /
 709         /// -1` on a signed type (where `MIN` is the negative
 710         /// minimal value). In such a case, this function returns `0`.
 711         ///
 712         /// # Panics
 713         ///
 714         /// This function will panic if `rhs` is 0.
 715         ///
 716         /// # Examples
 717         ///
 718         /// Basic usage:
 719         ///
 720         /// ```
 721         /// assert_eq!(100i8.wrapping_rem(10), 0);
 722         /// assert_eq!((-128i8).wrapping_rem(-1), 0);
 723         /// ```
 724         #[stable(feature = "num_wrapping", since = "1.2.0")]
 725         #[inline(always)]
 726         pub fn wrapping_rem(self, rhs: Self) -> Self {
 727             self.overflowing_rem(rhs).0
 728         }
 729
 730         /// Wrapping (modular) negation. Computes `-self`,
 731         /// wrapping around at the boundary of the type.
 732         ///
 733         /// The only case where such wrapping can occur is when one
 734         /// negates `MIN` on a signed type (where `MIN` is the
 735         /// negative minimal value for the type); this is a positive
 736         /// value that is too large to represent in the type. In such
 737         /// a case, this function returns `MIN` itself.
 738         ///
 739         /// # Examples
 740         ///
 741         /// Basic usage:
 742         ///
 743         /// ```
 744         /// assert_eq!(100i8.wrapping_neg(), -100);
 745         /// assert_eq!((-128i8).wrapping_neg(), -128);
 746         /// ```
 747         #[stable(feature = "num_wrapping", since = "1.2.0")]
 748         #[inline(always)]
 749         pub fn wrapping_neg(self) -> Self {
 750             self.overflowing_neg().0
 751         }
 752
 753         /// Panic-free bitwise shift-left; yields `self << mask(rhs)`,
 754         /// where `mask` removes any high-order bits of `rhs` that
 755         /// would cause the shift to exceed the bitwidth of the type.
 756         ///
 757         /// Note that this is *not* the same as a rotate-left; the
 758         /// RHS of a wrapping shift-left is restricted to the range
 759         /// of the type, rather than the bits shifted out of the LHS
 760         /// being returned to the other end. The primitive integer
 761         /// types all implement a `rotate_left` function, which may
 762         /// be what you want instead.
 763         ///
 764         /// # Examples
 765         ///
 766         /// Basic usage:
 767         ///
 768         /// ```
 769         /// assert_eq!((-1i8).wrapping_shl(7), -128);
 770         /// assert_eq!((-1i8).wrapping_shl(8), -1);
 771         /// ```
 772         #[stable(feature = "num_wrapping", since = "1.2.0")]
 773         #[inline(always)]
 774         pub fn wrapping_shl(self, rhs: u32) -> Self {
 775             unsafe {
 776                 intrinsics::unchecked_shl(self, (rhs & ($BITS - 1)) as $SelfT)
 777             }
 778         }
 779
 780         /// Panic-free bitwise shift-right; yields `self >> mask(rhs)`,
 781         /// where `mask` removes any high-order bits of `rhs` that
 782         /// would cause the shift to exceed the bitwidth of the type.
 783         ///
 784         /// Note that this is *not* the same as a rotate-right; the
 785         /// RHS of a wrapping shift-right is restricted to the range
 786         /// of the type, rather than the bits shifted out of the LHS
 787         /// being returned to the other end. The primitive integer
 788         /// types all implement a `rotate_right` function, which may
 789         /// be what you want instead.
 790         ///
 791         /// # Examples
 792         ///
 793         /// Basic usage:
 794         ///
 795         /// ```
 796         /// assert_eq!((-128i8).wrapping_shr(7), -1);
 797         /// assert_eq!((-128i8).wrapping_shr(8), -128);
 798         /// ```
 799         #[stable(feature = "num_wrapping", since = "1.2.0")]
 800         #[inline(always)]
 801         pub fn wrapping_shr(self, rhs: u32) -> Self {
 802             unsafe {
 803                 intrinsics::unchecked_shr(self, (rhs & ($BITS - 1)) as $SelfT)
 804             }
 805         }
 806
 807         /// Wrapping (modular) absolute value. Computes `self.abs()`,
 808         /// wrapping around at the boundary of the type.
 809         ///
 810         /// The only case where such wrapping can occur is when one takes
 811         /// the absolute value of the negative minimal value for the type
 812         /// this is a positive value that is too large to represent in the
 813         /// type. In such a case, this function returns `MIN` itself.
 814         ///
 815         /// # Examples
 816         ///
 817         /// Basic usage:
 818         ///
 819         /// ```
 820         /// assert_eq!(100i8.wrapping_abs(), 100);
 821         /// assert_eq!((-100i8).wrapping_abs(), 100);
 822         /// assert_eq!((-128i8).wrapping_abs(), -128);
 823         /// assert_eq!((-128i8).wrapping_abs() as u8, 128);
 824         /// ```
 825         #[stable(feature = "no_panic_abs", since = "1.13.0")]
 826         #[inline(always)]
 827         pub fn wrapping_abs(self) -> Self {
 828             if self.is_negative() {
 829                 self.wrapping_neg()
 830             } else {
 831                 self
 832             }
 833         }
 834
 835         /// Calculates `self` + `rhs`
 836         ///
 837         /// Returns a tuple of the addition along with a boolean indicating
 838         /// whether an arithmetic overflow would occur. If an overflow would
 839         /// have occurred then the wrapped value is returned.
 840         ///
 841         /// # Examples
 842         ///
 843         /// Basic usage
 844         ///
 845         /// ```
 846         /// use std::i32;
 847         ///
 848         /// assert_eq!(5i32.overflowing_add(2), (7, false));
 849         /// assert_eq!(i32::MAX.overflowing_add(1), (i32::MIN, true));
 850         /// ```
 851         #[inline]
 852         #[stable(feature = "wrapping", since = "1.7.0")]
 853         pub fn overflowing_add(self, rhs: Self) -> (Self, bool) {
 854             unsafe {
 855                 let (a, b) = $add_with_overflow(self as $ActualT,
 856                                                 rhs as $ActualT);
 857                 (a as Self, b)
 858             }
 859         }
 860
 861         /// Calculates `self` - `rhs`
 862         ///
 863         /// Returns a tuple of the subtraction along with a boolean indicating
 864         /// whether an arithmetic overflow would occur. If an overflow would
 865         /// have occurred then the wrapped value is returned.
 866         ///
 867         /// # Examples
 868         ///
 869         /// Basic usage
 870         ///
 871         /// ```
 872         /// use std::i32;
 873         ///
 874         /// assert_eq!(5i32.overflowing_sub(2), (3, false));
 875         /// assert_eq!(i32::MIN.overflowing_sub(1), (i32::MAX, true));
 876         /// ```
 877         #[inline]
 878         #[stable(feature = "wrapping", since = "1.7.0")]
 879         pub fn overflowing_sub(self, rhs: Self) -> (Self, bool) {
 880             unsafe {
 881                 let (a, b) = $sub_with_overflow(self as $ActualT,
 882                                                 rhs as $ActualT);
 883                 (a as Self, b)
 884             }
 885         }
 886
 887         /// Calculates the multiplication of `self` and `rhs`.
 888         ///
 889         /// Returns a tuple of the multiplication along with a boolean
 890         /// indicating whether an arithmetic overflow would occur. If an
 891         /// overflow would have occurred then the wrapped value is returned.
 892         ///
 893         /// # Examples
 894         ///
 895         /// Basic usage
 896         ///
 897         /// ```
 898         /// assert_eq!(5i32.overflowing_mul(2), (10, false));
 899         /// assert_eq!(1_000_000_000i32.overflowing_mul(10), (1410065408, true));
 900         /// ```
 901         #[inline]
 902         #[stable(feature = "wrapping", since = "1.7.0")]
 903         pub fn overflowing_mul(self, rhs: Self) -> (Self, bool) {
 904             unsafe {
 905                 let (a, b) = $mul_with_overflow(self as $ActualT,
 906                                                 rhs as $ActualT);
 907                 (a as Self, b)
 908             }
 909         }
 910
 911         /// Calculates the divisor when `self` is divided by `rhs`.
 912         ///
 913         /// Returns a tuple of the divisor along with a boolean indicating
 914         /// whether an arithmetic overflow would occur. If an overflow would
 915         /// occur then self is returned.
 916         ///
 917         /// # Panics
 918         ///
 919         /// This function will panic if `rhs` is 0.
 920         ///
 921         /// # Examples
 922         ///
 923         /// Basic usage
 924         ///
 925         /// ```
 926         /// use std::i32;
 927         ///
 928         /// assert_eq!(5i32.overflowing_div(2), (2, false));
 929         /// assert_eq!(i32::MIN.overflowing_div(-1), (i32::MIN, true));
 930         /// ```
 931         #[inline]
 932         #[stable(feature = "wrapping", since = "1.7.0")]
 933         pub fn overflowing_div(self, rhs: Self) -> (Self, bool) {
 934             if self == Self::min_value() && rhs == -1 {
 935                 (self, true)
 936             } else {
 937                 (self / rhs, false)
 938             }
 939         }
 940
 941         /// Calculates the remainder when `self` is divided by `rhs`.
 942         ///
 943         /// Returns a tuple of the remainder after dividing along with a boolean
 944         /// indicating whether an arithmetic overflow would occur. If an
 945         /// overflow would occur then 0 is returned.
 946         ///
 947         /// # Panics
 948         ///
 949         /// This function will panic if `rhs` is 0.
 950         ///
 951         /// # Examples
 952         ///
 953         /// Basic usage
 954         ///
 955         /// ```
 956         /// use std::i32;
 957         ///
 958         /// assert_eq!(5i32.overflowing_rem(2), (1, false));
 959         /// assert_eq!(i32::MIN.overflowing_rem(-1), (0, true));
 960         /// ```
 961         #[inline]
 962         #[stable(feature = "wrapping", since = "1.7.0")]
 963         pub fn overflowing_rem(self, rhs: Self) -> (Self, bool) {
 964             if self == Self::min_value() && rhs == -1 {
 965                 (0, true)
 966             } else {
 967                 (self % rhs, false)
 968             }
 969         }
 970
 971         /// Negates self, overflowing if this is equal to the minimum value.
 972         ///
 973         /// Returns a tuple of the negated version of self along with a boolean
 974         /// indicating whether an overflow happened. If `self` is the minimum
 975         /// value (e.g. `i32::MIN` for values of type `i32`), then the minimum
 976         /// value will be returned again and `true` will be returned for an
 977         /// overflow happening.
 978         ///
 979         /// # Examples
 980         ///
 981         /// Basic usage
 982         ///
 983         /// ```
 984         /// use std::i32;
 985         ///
 986         /// assert_eq!(2i32.overflowing_neg(), (-2, false));
 987         /// assert_eq!(i32::MIN.overflowing_neg(), (i32::MIN, true));
 988         /// ```
 989         #[inline]
 990         #[stable(feature = "wrapping", since = "1.7.0")]
 991         pub fn overflowing_neg(self) -> (Self, bool) {
 992             if self == Self::min_value() {
 993                 (Self::min_value(), true)
 994             } else {
 995                 (-self, false)
 996             }
 997         }
 998
 999         /// Shifts self left by `rhs` bits.
1000         ///
1001         /// Returns a tuple of the shifted version of self along with a boolean
1002         /// indicating whether the shift value was larger than or equal to the
1003         /// number of bits. If the shift value is too large, then value is
1004         /// masked (N-1) where N is the number of bits, and this value is then
1005         /// used to perform the shift.
1006         ///
1007         /// # Examples
1008         ///
1009         /// Basic usage
1010         ///
1011         /// ```
1012         /// assert_eq!(0x10i32.overflowing_shl(4), (0x100, false));
1013         /// assert_eq!(0x10i32.overflowing_shl(36), (0x100, true));
1014         /// ```
1015         #[inline]
1016         #[stable(feature = "wrapping", since = "1.7.0")]
1017         pub fn overflowing_shl(self, rhs: u32) -> (Self, bool) {
1018             (self.wrapping_shl(rhs), (rhs > ($BITS - 1)))
1019         }
1020
1021         /// Shifts self right by `rhs` bits.
1022         ///
1023         /// Returns a tuple of the shifted version of self along with a boolean
1024         /// indicating whether the shift value was larger than or equal to the
1025         /// number of bits. If the shift value is too large, then value is
1026         /// masked (N-1) where N is the number of bits, and this value is then
1027         /// used to perform the shift.
1028         ///
1029         /// # Examples
1030         ///
1031         /// Basic usage
1032         ///
1033         /// ```
1034         /// assert_eq!(0x10i32.overflowing_shr(4), (0x1, false));
1035         /// assert_eq!(0x10i32.overflowing_shr(36), (0x1, true));
1036         /// ```
1037         #[inline]
1038         #[stable(feature = "wrapping", since = "1.7.0")]
1039         pub fn overflowing_shr(self, rhs: u32) -> (Self, bool) {
1040             (self.wrapping_shr(rhs), (rhs > ($BITS - 1)))
1041         }
1042
1043         /// Computes the absolute value of `self`.
1044         ///
1045         /// Returns a tuple of the absolute version of self along with a
1046         /// boolean indicating whether an overflow happened. If self is the
1047         /// minimum value (e.g. i32::MIN for values of type i32), then the
1048         /// minimum value will be returned again and true will be returned for
1049         /// an overflow happening.
1050         ///
1051         /// # Examples
1052         ///
1053         /// Basic usage:
1054         ///
1055         /// ```
1056         /// assert_eq!(10i8.overflowing_abs(), (10,false));
1057         /// assert_eq!((-10i8).overflowing_abs(), (10,false));
1058         /// assert_eq!((-128i8).overflowing_abs(), (-128,true));
1059         /// ```
1060         #[stable(feature = "no_panic_abs", since = "1.13.0")]
1061         #[inline]
1062         pub fn overflowing_abs(self) -> (Self, bool) {
1063             if self.is_negative() {
1064                 self.overflowing_neg()
1065             } else {
1066                 (self, false)
1067             }
1068         }
1069
1070         /// Raises self to the power of `exp`, using exponentiation by squaring.
1071         ///
1072         /// # Examples
1073         ///
1074         /// Basic usage:
1075         ///
1076         /// ```
1077         /// let x: i32 = 2; // or any other integer type
1078         ///
1079         /// assert_eq!(x.pow(4), 16);
1080         /// ```
1081         #[stable(feature = "rust1", since = "1.0.0")]
1082         #[inline]
1083         #[rustc_inherit_overflow_checks]
1084         pub fn pow(self, mut exp: u32) -> Self {
1085             let mut base = self;
1086             let mut acc = 1;
1087
1088             while exp > 1 {
1089                 if (exp & 1) == 1 {
1090                     acc = acc * base;
1091                 }
1092                 exp /= 2;
1093                 base = base * base;
1094             }
1095
1096             // Deal with the final bit of the exponent separately, since
1097             // squaring the base afterwards is not necessary and may cause a
1098             // needless overflow.
1099             if exp == 1 {
1100                 acc = acc * base;
1101             }
1102
1103             acc
1104         }
1105
1106         /// Computes the absolute value of `self`.
1107         ///
1108         /// # Overflow behavior
1109         ///
1110         /// The absolute value of `i32::min_value()` cannot be represented as an
1111         /// `i32`, and attempting to calculate it will cause an overflow. This
1112         /// means that code in debug mode will trigger a panic on this case and
1113         /// optimized code will return `i32::min_value()` without a panic.
1114         ///
1115         /// # Examples
1116         ///
1117         /// Basic usage:
1118         ///
1119         /// ```
1120         /// assert_eq!(10i8.abs(), 10);
1121         /// assert_eq!((-10i8).abs(), 10);
1122         /// ```
1123         #[stable(feature = "rust1", since = "1.0.0")]
1124         #[inline]
1125         #[rustc_inherit_overflow_checks]
1126         pub fn abs(self) -> Self {
1127             if self.is_negative() {
1128                 // Note that the #[inline] above means that the overflow
1129                 // semantics of this negation depend on the crate we're being
1130                 // inlined into.
1131                 -self
1132             } else {
1133                 self
1134             }
1135         }
1136
1137         /// Returns a number representing sign of `self`.
1138         ///
1139         /// - `0` if the number is zero
1140         /// - `1` if the number is positive
1141         /// - `-1` if the number is negative
1142         ///
1143         /// # Examples
1144         ///
1145         /// Basic usage:
1146         ///
1147         /// ```
1148         /// assert_eq!(10i8.signum(), 1);
1149         /// assert_eq!(0i8.signum(), 0);
1150         /// assert_eq!((-10i8).signum(), -1);
1151         /// ```
1152         #[stable(feature = "rust1", since = "1.0.0")]
1153         #[inline]
1154         pub fn signum(self) -> Self {
1155             match self {
1156                 n if n > 0 =>  1,
1157                 0          =>  0,
1158                 _          => -1,
1159             }
1160         }
1161
1162         /// Returns `true` if `self` is positive and `false` if the number
1163         /// is zero or negative.
1164         ///
1165         /// # Examples
1166         ///
1167         /// Basic usage:
1168         ///
1169         /// ```
1170         /// assert!(10i8.is_positive());
1171         /// assert!(!(-10i8).is_positive());
1172         /// ```
1173         #[stable(feature = "rust1", since = "1.0.0")]
1174         #[inline]
1175         pub fn is_positive(self) -> bool { self > 0 }
1176
1177         /// Returns `true` if `self` is negative and `false` if the number
1178         /// is zero or positive.
1179         ///
1180         /// # Examples
1181         ///
1182         /// Basic usage:
1183         ///
1184         /// ```
1185         /// assert!((-10i8).is_negative());
1186         /// assert!(!10i8.is_negative());
1187         /// ```
1188         #[stable(feature = "rust1", since = "1.0.0")]
1189         #[inline]
1190         pub fn is_negative(self) -> bool { self < 0 }
1191     }
1192 }
1193
1194 #[lang = "i8"]
1195 impl i8 {
1196     int_impl! { i8, i8, u8, 8,
1197         intrinsics::add_with_overflow,
1198         intrinsics::sub_with_overflow,
1199         intrinsics::mul_with_overflow }
1200 }
1201
1202 #[lang = "i16"]
1203 impl i16 {
1204     int_impl! { i16, i16, u16, 16,
1205         intrinsics::add_with_overflow,
1206         intrinsics::sub_with_overflow,
1207         intrinsics::mul_with_overflow }
1208 }
1209
1210 #[lang = "i32"]
1211 impl i32 {
1212     int_impl! { i32, i32, u32, 32,
1213         intrinsics::add_with_overflow,
1214         intrinsics::sub_with_overflow,
1215         intrinsics::mul_with_overflow }
1216 }
1217
1218 #[lang = "i64"]
1219 impl i64 {
1220     int_impl! { i64, i64, u64, 64,
1221         intrinsics::add_with_overflow,
1222         intrinsics::sub_with_overflow,
1223         intrinsics::mul_with_overflow }
1224 }
1225
1226 #[lang = "i128"]
1227 impl i128 {
1228     int_impl! { i128, i128, u128, 128,
1229         intrinsics::add_with_overflow,
1230         intrinsics::sub_with_overflow,
1231         intrinsics::mul_with_overflow }
1232 }
1233
1234 #[cfg(target_pointer_width = "16")]
1235 #[lang = "isize"]
1236 impl isize {
1237     int_impl! { isize, i16, u16, 16,
1238         intrinsics::add_with_overflow,
1239         intrinsics::sub_with_overflow,
1240         intrinsics::mul_with_overflow }
1241 }
1242
1243 #[cfg(target_pointer_width = "32")]
1244 #[lang = "isize"]
1245 impl isize {
1246     int_impl! { isize, i32, u32, 32,
1247         intrinsics::add_with_overflow,
1248         intrinsics::sub_with_overflow,
1249         intrinsics::mul_with_overflow }
1250 }
1251
1252 #[cfg(target_pointer_width = "64")]
1253 #[lang = "isize"]
1254 impl isize {
1255     int_impl! { isize, i64, u64, 64,
1256         intrinsics::add_with_overflow,
1257         intrinsics::sub_with_overflow,
1258         intrinsics::mul_with_overflow }
1259 }
1260
1261 // `Int` + `UnsignedInt` implemented for unsigned integers
1262 macro_rules! uint_impl {
1263     ($SelfT:ty, $ActualT:ty, $BITS:expr,
1264      $ctpop:path,
1265      $ctlz: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 the smallest power of two greater than or equal to `self`.
2180         /// Unspecified behavior on overflow.
2181         ///
2182         /// # Examples
2183         ///
2184         /// Basic usage:
2185         ///
2186         /// ```
2187         /// assert_eq!(2u8.next_power_of_two(), 2);
2188         /// assert_eq!(3u8.next_power_of_two(), 4);
2189         /// ```
2190         #[stable(feature = "rust1", since = "1.0.0")]
2191         #[inline]
2192         pub fn next_power_of_two(self) -> Self {
2193             let bits = size_of::<Self>() * 8;
2194             let one: Self = 1;
2195             one << ((bits - self.wrapping_sub(one).leading_zeros() as usize) % bits)
2196         }
2197
2198         /// Returns the smallest power of two greater than or equal to `n`. If
2199         /// the next power of two is greater than the type's maximum value,
2200         /// `None` is returned, otherwise the power of two is wrapped in `Some`.
2201         ///
2202         /// # Examples
2203         ///
2204         /// Basic usage:
2205         ///
2206         /// ```
2207         /// assert_eq!(2u8.checked_next_power_of_two(), Some(2));
2208         /// assert_eq!(3u8.checked_next_power_of_two(), Some(4));
2209         /// assert_eq!(200u8.checked_next_power_of_two(), None);
2210         /// ```
2211         #[stable(feature = "rust1", since = "1.0.0")]
2212         pub fn checked_next_power_of_two(self) -> Option<Self> {
2213             let npot = self.next_power_of_two();
2214             if npot >= self {
2215                 Some(npot)
2216             } else {
2217                 None
2218             }
2219         }
2220     }
2221 }
2222
2223 #[lang = "u8"]
2224 impl u8 {
2225     uint_impl! { u8, u8, 8,
2226         intrinsics::ctpop,
2227         intrinsics::ctlz,
2228         intrinsics::cttz,
2229         intrinsics::bswap,
2230         intrinsics::add_with_overflow,
2231         intrinsics::sub_with_overflow,
2232         intrinsics::mul_with_overflow }
2233 }
2234
2235 #[lang = "u16"]
2236 impl u16 {
2237     uint_impl! { u16, u16, 16,
2238         intrinsics::ctpop,
2239         intrinsics::ctlz,
2240         intrinsics::cttz,
2241         intrinsics::bswap,
2242         intrinsics::add_with_overflow,
2243         intrinsics::sub_with_overflow,
2244         intrinsics::mul_with_overflow }
2245 }
2246
2247 #[lang = "u32"]
2248 impl u32 {
2249     uint_impl! { u32, u32, 32,
2250         intrinsics::ctpop,
2251         intrinsics::ctlz,
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 = "u64"]
2260 impl u64 {
2261     uint_impl! { u64, u64, 64,
2262         intrinsics::ctpop,
2263         intrinsics::ctlz,
2264         intrinsics::cttz,
2265         intrinsics::bswap,
2266         intrinsics::add_with_overflow,
2267         intrinsics::sub_with_overflow,
2268         intrinsics::mul_with_overflow }
2269 }
2270
2271 #[lang = "u128"]
2272 impl u128 {
2273     uint_impl! { u128, u128, 128,
2274         intrinsics::ctpop,
2275         intrinsics::ctlz,
2276         intrinsics::cttz,
2277         intrinsics::bswap,
2278         intrinsics::add_with_overflow,
2279         intrinsics::sub_with_overflow,
2280         intrinsics::mul_with_overflow }
2281 }
2282
2283 #[cfg(target_pointer_width = "16")]
2284 #[lang = "usize"]
2285 impl usize {
2286     uint_impl! { usize, u16, 16,
2287         intrinsics::ctpop,
2288         intrinsics::ctlz,
2289         intrinsics::cttz,
2290         intrinsics::bswap,
2291         intrinsics::add_with_overflow,
2292         intrinsics::sub_with_overflow,
2293         intrinsics::mul_with_overflow }
2294 }
2295 #[cfg(target_pointer_width = "32")]
2296 #[lang = "usize"]
2297 impl usize {
2298     uint_impl! { usize, u32, 32,
2299         intrinsics::ctpop,
2300         intrinsics::ctlz,
2301         intrinsics::cttz,
2302         intrinsics::bswap,
2303         intrinsics::add_with_overflow,
2304         intrinsics::sub_with_overflow,
2305         intrinsics::mul_with_overflow }
2306 }
2307
2308 #[cfg(target_pointer_width = "64")]
2309 #[lang = "usize"]
2310 impl usize {
2311     uint_impl! { usize, u64, 64,
2312         intrinsics::ctpop,
2313         intrinsics::ctlz,
2314         intrinsics::cttz,
2315         intrinsics::bswap,
2316         intrinsics::add_with_overflow,
2317         intrinsics::sub_with_overflow,
2318         intrinsics::mul_with_overflow }
2319 }
2320
2321 /// A classification of floating point numbers.
2322 ///
2323 /// This `enum` is used as the return type for [`f32::classify`] and [`f64::classify`]. See
2324 /// their documentation for more.
2325 ///
2326 /// [`f32::classify`]: ../../std/primitive.f32.html#method.classify
2327 /// [`f64::classify`]: ../../std/primitive.f64.html#method.classify
2328 ///
2329 /// # Examples
2330 ///
2331 /// ```
2332 /// use std::num::FpCategory;
2333 /// use std::f32;
2334 ///
2335 /// let num = 12.4_f32;
2336 /// let inf = f32::INFINITY;
2337 /// let zero = 0f32;
2338 /// let sub: f32 = 1.1754942e-38;
2339 /// let nan = f32::NAN;
2340 ///
2341 /// assert_eq!(num.classify(), FpCategory::Normal);
2342 /// assert_eq!(inf.classify(), FpCategory::Infinite);
2343 /// assert_eq!(zero.classify(), FpCategory::Zero);
2344 /// assert_eq!(nan.classify(), FpCategory::Nan);
2345 /// assert_eq!(sub.classify(), FpCategory::Subnormal);
2346 /// ```
2347 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
2348 #[stable(feature = "rust1", since = "1.0.0")]
2349 pub enum FpCategory {
2350     /// "Not a Number", often obtained by dividing by zero.
2351     #[stable(feature = "rust1", since = "1.0.0")]
2352     Nan,
2353
2354     /// Positive or negative infinity.
2355     #[stable(feature = "rust1", since = "1.0.0")]
2356     Infinite,
2357
2358     /// Positive or negative zero.
2359     #[stable(feature = "rust1", since = "1.0.0")]
2360     Zero,
2361
2362     /// De-normalized floating point representation (less precise than `Normal`).
2363     #[stable(feature = "rust1", since = "1.0.0")]
2364     Subnormal,
2365
2366     /// A regular floating point number.
2367     #[stable(feature = "rust1", since = "1.0.0")]
2368     Normal,
2369 }
2370
2371 /// A built-in floating point number.
2372 #[doc(hidden)]
2373 #[unstable(feature = "core_float",
2374            reason = "stable interface is via `impl f{32,64}` in later crates",
2375            issue = "32110")]
2376 pub trait Float: Sized {
2377     /// Returns `true` if this value is NaN and false otherwise.
2378     #[stable(feature = "core", since = "1.6.0")]
2379     fn is_nan(self) -> bool;
2380     /// Returns `true` if this value is positive infinity or negative infinity and
2381     /// false otherwise.
2382     #[stable(feature = "core", since = "1.6.0")]
2383     fn is_infinite(self) -> bool;
2384     /// Returns `true` if this number is neither infinite nor NaN.
2385     #[stable(feature = "core", since = "1.6.0")]
2386     fn is_finite(self) -> bool;
2387     /// Returns `true` if this number is neither zero, infinite, denormal, or NaN.
2388     #[stable(feature = "core", since = "1.6.0")]
2389     fn is_normal(self) -> bool;
2390     /// Returns the category that this number falls into.
2391     #[stable(feature = "core", since = "1.6.0")]
2392     fn classify(self) -> FpCategory;
2393
2394     /// Computes the absolute value of `self`. Returns `Float::nan()` if the
2395     /// number is `Float::nan()`.
2396     #[stable(feature = "core", since = "1.6.0")]
2397     fn abs(self) -> Self;
2398     /// Returns a number that represents the sign of `self`.
2399     ///
2400     /// - `1.0` if the number is positive, `+0.0` or `Float::infinity()`
2401     /// - `-1.0` if the number is negative, `-0.0` or `Float::neg_infinity()`
2402     /// - `Float::nan()` if the number is `Float::nan()`
2403     #[stable(feature = "core", since = "1.6.0")]
2404     fn signum(self) -> Self;
2405
2406     /// Returns `true` if `self` is positive, including `+0.0` and
2407     /// `Float::infinity()`.
2408     #[stable(feature = "core", since = "1.6.0")]
2409     fn is_sign_positive(self) -> bool;
2410     /// Returns `true` if `self` is negative, including `-0.0` and
2411     /// `Float::neg_infinity()`.
2412     #[stable(feature = "core", since = "1.6.0")]
2413     fn is_sign_negative(self) -> bool;
2414
2415     /// Take the reciprocal (inverse) of a number, `1/x`.
2416     #[stable(feature = "core", since = "1.6.0")]
2417     fn recip(self) -> Self;
2418
2419     /// Raise a number to an integer power.
2420     ///
2421     /// Using this function is generally faster than using `powf`
2422     #[stable(feature = "core", since = "1.6.0")]
2423     fn powi(self, n: i32) -> Self;
2424
2425     /// Convert radians to degrees.
2426     #[stable(feature = "deg_rad_conversions", since="1.7.0")]
2427     fn to_degrees(self) -> Self;
2428     /// Convert degrees to radians.
2429     #[stable(feature = "deg_rad_conversions", since="1.7.0")]
2430     fn to_radians(self) -> Self;
2431 }
2432
2433 macro_rules! from_str_radix_int_impl {
2434     ($($t:ty)*) => {$(
2435         #[stable(feature = "rust1", since = "1.0.0")]
2436         impl FromStr for $t {
2437             type Err = ParseIntError;
2438             fn from_str(src: &str) -> Result<Self, ParseIntError> {
2439                 from_str_radix(src, 10)
2440             }
2441         }
2442     )*}
2443 }
2444 from_str_radix_int_impl! { isize i8 i16 i32 i64 i128 usize u8 u16 u32 u64 u128 }
2445
2446 /// The error type returned when a checked integral type conversion fails.
2447 #[unstable(feature = "try_from", issue = "33417")]
2448 #[derive(Debug, Copy, Clone)]
2449 pub struct TryFromIntError(());
2450
2451 impl TryFromIntError {
2452     #[unstable(feature = "int_error_internals",
2453                reason = "available through Error trait and this method should \
2454                          not be exposed publicly",
2455                issue = "0")]
2456     #[doc(hidden)]
2457     pub fn __description(&self) -> &str {
2458         "out of range integral type conversion attempted"
2459     }
2460 }
2461
2462 #[unstable(feature = "try_from", issue = "33417")]
2463 impl fmt::Display for TryFromIntError {
2464     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
2465         self.__description().fmt(fmt)
2466     }
2467 }
2468
2469 macro_rules! same_sign_try_from_int_impl {
2470     ($storage:ty, $target:ty, $($source:ty),*) => {$(
2471         #[unstable(feature = "try_from", issue = "33417")]
2472         impl TryFrom<$source> for $target {
2473             type Error = TryFromIntError;
2474
2475             fn try_from(u: $source) -> Result<$target, TryFromIntError> {
2476                 let min = <$target as FromStrRadixHelper>::min_value() as $storage;
2477                 let max = <$target as FromStrRadixHelper>::max_value() as $storage;
2478                 if u as $storage < min || u as $storage > max {
2479                     Err(TryFromIntError(()))
2480                 } else {
2481                     Ok(u as $target)
2482                 }
2483             }
2484         }
2485     )*}
2486 }
2487
2488 same_sign_try_from_int_impl!(u128, u8, u8, u16, u32, u64, u128, usize);
2489 same_sign_try_from_int_impl!(i128, i8, i8, i16, i32, i64, i128, isize);
2490 same_sign_try_from_int_impl!(u128, u16, u8, u16, u32, u64, u128, usize);
2491 same_sign_try_from_int_impl!(i128, i16, i8, i16, i32, i64, i128, isize);
2492 same_sign_try_from_int_impl!(u128, u32, u8, u16, u32, u64, u128, usize);
2493 same_sign_try_from_int_impl!(i128, i32, i8, i16, i32, i64, i128, isize);
2494 same_sign_try_from_int_impl!(u128, u64, u8, u16, u32, u64, u128, usize);
2495 same_sign_try_from_int_impl!(i128, i64, i8, i16, i32, i64, i128, isize);
2496 same_sign_try_from_int_impl!(u128, u128, u8, u16, u32, u64, u128, usize);
2497 same_sign_try_from_int_impl!(i128, i128, i8, i16, i32, i64, i128, isize);
2498 same_sign_try_from_int_impl!(u128, usize, u8, u16, u32, u64, u128, usize);
2499 same_sign_try_from_int_impl!(i128, isize, i8, i16, i32, i64, i128, isize);
2500
2501 macro_rules! cross_sign_from_int_impl {
2502     ($unsigned:ty, $($signed:ty),*) => {$(
2503         #[unstable(feature = "try_from", issue = "33417")]
2504         impl TryFrom<$unsigned> for $signed {
2505             type Error = TryFromIntError;
2506
2507             fn try_from(u: $unsigned) -> Result<$signed, TryFromIntError> {
2508                 let max = <$signed as FromStrRadixHelper>::max_value() as u128;
2509                 if u as u128 > max {
2510                     Err(TryFromIntError(()))
2511                 } else {
2512                     Ok(u as $signed)
2513                 }
2514             }
2515         }
2516
2517         #[unstable(feature = "try_from", issue = "33417")]
2518         impl TryFrom<$signed> for $unsigned {
2519             type Error = TryFromIntError;
2520
2521             fn try_from(u: $signed) -> Result<$unsigned, TryFromIntError> {
2522                 let max = <$unsigned as FromStrRadixHelper>::max_value() as u128;
2523                 if u < 0 || u as u128 > max {
2524                     Err(TryFromIntError(()))
2525                 } else {
2526                     Ok(u as $unsigned)
2527                 }
2528             }
2529         }
2530     )*}
2531 }
2532
2533 cross_sign_from_int_impl!(u8, i8, i16, i32, i64, i128, isize);
2534 cross_sign_from_int_impl!(u16, i8, i16, i32, i64, i128, isize);
2535 cross_sign_from_int_impl!(u32, i8, i16, i32, i64, i128, isize);
2536 cross_sign_from_int_impl!(u64, i8, i16, i32, i64, i128, isize);
2537 cross_sign_from_int_impl!(u128, i8, i16, i32, i64, i128, isize);
2538 cross_sign_from_int_impl!(usize, i8, i16, i32, i64, i128, isize);
2539
2540 #[doc(hidden)]
2541 trait FromStrRadixHelper: PartialOrd + Copy {
2542     fn min_value() -> Self;
2543     fn max_value() -> Self;
2544     fn from_u32(u: u32) -> Self;
2545     fn checked_mul(&self, other: u32) -> Option<Self>;
2546     fn checked_sub(&self, other: u32) -> Option<Self>;
2547     fn checked_add(&self, other: u32) -> Option<Self>;
2548 }
2549
2550 macro_rules! doit {
2551     ($($t:ty)*) => ($(impl FromStrRadixHelper for $t {
2552         fn min_value() -> Self { Self::min_value() }
2553         fn max_value() -> Self { Self::max_value() }
2554         fn from_u32(u: u32) -> Self { u as Self }
2555         fn checked_mul(&self, other: u32) -> Option<Self> {
2556             Self::checked_mul(*self, other as Self)
2557         }
2558         fn checked_sub(&self, other: u32) -> Option<Self> {
2559             Self::checked_sub(*self, other as Self)
2560         }
2561         fn checked_add(&self, other: u32) -> Option<Self> {
2562             Self::checked_add(*self, other as Self)
2563         }
2564     })*)
2565 }
2566 doit! { i8 i16 i32 i64 i128 isize u8 u16 u32 u64 u128 usize }
2567
2568 fn from_str_radix<T: FromStrRadixHelper>(src: &str, radix: u32) -> Result<T, ParseIntError> {
2569     use self::IntErrorKind::*;
2570     use self::ParseIntError as PIE;
2571
2572     assert!(radix >= 2 && radix <= 36,
2573            "from_str_radix_int: must lie in the range `[2, 36]` - found {}",
2574            radix);
2575
2576     if src.is_empty() {
2577         return Err(PIE { kind: Empty });
2578     }
2579
2580     let is_signed_ty = T::from_u32(0) > T::min_value();
2581
2582     // all valid digits are ascii, so we will just iterate over the utf8 bytes
2583     // and cast them to chars. .to_digit() will safely return None for anything
2584     // other than a valid ascii digit for the given radix, including the first-byte
2585     // of multi-byte sequences
2586     let src = src.as_bytes();
2587
2588     let (is_positive, digits) = match src[0] {
2589         b'+' => (true, &src[1..]),
2590         b'-' if is_signed_ty => (false, &src[1..]),
2591         _ => (true, src),
2592     };
2593
2594     if digits.is_empty() {
2595         return Err(PIE { kind: Empty });
2596     }
2597
2598     let mut result = T::from_u32(0);
2599     if is_positive {
2600         // The number is positive
2601         for &c in digits {
2602             let x = match (c as char).to_digit(radix) {
2603                 Some(x) => x,
2604                 None => return Err(PIE { kind: InvalidDigit }),
2605             };
2606             result = match result.checked_mul(radix) {
2607                 Some(result) => result,
2608                 None => return Err(PIE { kind: Overflow }),
2609             };
2610             result = match result.checked_add(x) {
2611                 Some(result) => result,
2612                 None => return Err(PIE { kind: Overflow }),
2613             };
2614         }
2615     } else {
2616         // The number is negative
2617         for &c in digits {
2618             let x = match (c as char).to_digit(radix) {
2619                 Some(x) => x,
2620                 None => return Err(PIE { kind: InvalidDigit }),
2621             };
2622             result = match result.checked_mul(radix) {
2623                 Some(result) => result,
2624                 None => return Err(PIE { kind: Underflow }),
2625             };
2626             result = match result.checked_sub(x) {
2627                 Some(result) => result,
2628                 None => return Err(PIE { kind: Underflow }),
2629             };
2630         }
2631     }
2632     Ok(result)
2633 }
2634
2635 /// An error which can be returned when parsing an integer.
2636 ///
2637 /// This error is used as the error type for the `from_str_radix()` functions
2638 /// on the primitive integer types, such as [`i8::from_str_radix`].
2639 ///
2640 /// [`i8::from_str_radix`]: ../../std/primitive.i8.html#method.from_str_radix
2641 #[derive(Debug, Clone, PartialEq, Eq)]
2642 #[stable(feature = "rust1", since = "1.0.0")]
2643 pub struct ParseIntError {
2644     kind: IntErrorKind,
2645 }
2646
2647 #[derive(Debug, Clone, PartialEq, Eq)]
2648 enum IntErrorKind {
2649     Empty,
2650     InvalidDigit,
2651     Overflow,
2652     Underflow,
2653 }
2654
2655 impl ParseIntError {
2656     #[unstable(feature = "int_error_internals",
2657                reason = "available through Error trait and this method should \
2658                          not be exposed publicly",
2659                issue = "0")]
2660     #[doc(hidden)]
2661     pub fn __description(&self) -> &str {
2662         match self.kind {
2663             IntErrorKind::Empty => "cannot parse integer from empty string",
2664             IntErrorKind::InvalidDigit => "invalid digit found in string",
2665             IntErrorKind::Overflow => "number too large to fit in target type",
2666             IntErrorKind::Underflow => "number too small to fit in target type",
2667         }
2668     }
2669 }
2670
2671 #[stable(feature = "rust1", since = "1.0.0")]
2672 impl fmt::Display for ParseIntError {
2673     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
2674         self.__description().fmt(f)
2675     }
2676 }
2677
2678 #[stable(feature = "rust1", since = "1.0.0")]
2679 pub use num::dec2flt::ParseFloatError;
2680
2681 // Conversion traits for primitive integer and float types
2682 // Conversions T -> T are covered by a blanket impl and therefore excluded
2683 // Some conversions from and to usize/isize are not implemented due to portability concerns
2684 macro_rules! impl_from {
2685     ($Small: ty, $Large: ty, #[$attr:meta]) => {
2686         #[$attr]
2687         impl From<$Small> for $Large {
2688             #[inline]
2689             fn from(small: $Small) -> $Large {
2690                 small as $Large
2691             }
2692         }
2693     }
2694 }
2695
2696 // Unsigned -> Unsigned
2697 impl_from! { u8, u16, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2698 impl_from! { u8, u32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2699 impl_from! { u8, u64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2700 impl_from! { u8, u128, #[unstable(feature = "i128", issue = "35118")] }
2701 impl_from! { u8, usize, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2702 impl_from! { u16, u32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2703 impl_from! { u16, u64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2704 impl_from! { u16, u128, #[unstable(feature = "i128", issue = "35118")] }
2705 impl_from! { u32, u64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2706 impl_from! { u32, u128, #[unstable(feature = "i128", issue = "35118")] }
2707 impl_from! { u64, u128, #[unstable(feature = "i128", issue = "35118")] }
2708
2709 // Signed -> Signed
2710 impl_from! { i8, i16, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2711 impl_from! { i8, i32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2712 impl_from! { i8, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2713 impl_from! { i8, i128, #[unstable(feature = "i128", issue = "35118")] }
2714 impl_from! { i8, isize, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2715 impl_from! { i16, i32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2716 impl_from! { i16, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2717 impl_from! { i16, i128, #[unstable(feature = "i128", issue = "35118")] }
2718 impl_from! { i32, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2719 impl_from! { i32, i128, #[unstable(feature = "i128", issue = "35118")] }
2720 impl_from! { i64, i128, #[unstable(feature = "i128", issue = "35118")] }
2721
2722 // Unsigned -> Signed
2723 impl_from! { u8, i16, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2724 impl_from! { u8, i32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2725 impl_from! { u8, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2726 impl_from! { u8, i128, #[unstable(feature = "i128", issue = "35118")] }
2727 impl_from! { u16, i32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2728 impl_from! { u16, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2729 impl_from! { u16, i128, #[unstable(feature = "i128", issue = "35118")] }
2730 impl_from! { u32, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
2731 impl_from! { u32, i128, #[unstable(feature = "i128", issue = "35118")] }
2732 impl_from! { u64, i128, #[unstable(feature = "i128", issue = "35118")] }
2733
2734 // Note: integers can only be represented with full precision in a float if
2735 // they fit in the significand, which is 24 bits in f32 and 53 bits in f64.
2736 // Lossy float conversions are not implemented at this time.
2737
2738 // Signed -> Float
2739 impl_from! { i8, f32, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
2740 impl_from! { i8, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
2741 impl_from! { i16, f32, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
2742 impl_from! { i16, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
2743 impl_from! { i32, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
2744
2745 // Unsigned -> Float
2746 impl_from! { u8, f32, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
2747 impl_from! { u8, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
2748 impl_from! { u16, f32, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
2749 impl_from! { u16, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
2750 impl_from! { u32, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
2751
2752 // Float -> Float
2753 impl_from! { f32, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }