]> git.lizzy.rs Git - rust.git/blob - src/libcore/num/mod.rs
integer parsing should accept leading plus
[rust.git] / 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 #![allow(missing_docs)]
15
16 use self::wrapping::OverflowingOps;
17
18 use char::CharExt;
19 use cmp::{Eq, PartialOrd};
20 use fmt;
21 use intrinsics;
22 use marker::{Copy, Sized};
23 use mem::size_of;
24 use option::Option::{self, Some, None};
25 use result::Result::{self, Ok, Err};
26 use str::{FromStr, StrExt};
27 use slice::SliceExt;
28
29 /// Provides intentionally-wrapped arithmetic on `T`.
30 ///
31 /// Operations like `+` on `u32` values is intended to never overflow,
32 /// and in some debug configurations overflow is detected and results
33 /// in a panic. While most arithmetic falls into this category, some
34 /// code explicitly expects and relies upon modular arithmetic (e.g.,
35 /// hashing).
36 ///
37 /// Wrapping arithmetic can be achieved either through methods like
38 /// `wrapping_add`, or through the `Wrapping<T>` type, which says that
39 /// all standard arithmetic operations on the underlying value are
40 /// intended to have wrapping semantics.
41 #[stable(feature = "rust1", since = "1.0.0")]
42 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Copy, Debug)]
43 pub struct Wrapping<T>(#[stable(feature = "rust1", since = "1.0.0")] pub T);
44
45 pub mod wrapping;
46
47 // All these modules are technically private and only exposed for libcoretest:
48 pub mod flt2dec;
49 pub mod dec2flt;
50 pub mod bignum;
51 pub mod diy_float;
52
53 /// Types that have a "zero" value.
54 ///
55 /// This trait is intended for use in conjunction with `Add`, as an identity:
56 /// `x + T::zero() == x`.
57 #[unstable(feature = "zero_one",
58            reason = "unsure of placement, wants to use associated constants",
59            issue = "27739")]
60 pub trait Zero {
61     /// The "zero" (usually, additive identity) for this type.
62     fn zero() -> Self;
63 }
64
65 /// Types that have a "one" value.
66 ///
67 /// This trait is intended for use in conjunction with `Mul`, as an identity:
68 /// `x * T::one() == x`.
69 #[unstable(feature = "zero_one",
70            reason = "unsure of placement, wants to use associated constants",
71            issue = "27739")]
72 pub trait One {
73     /// The "one" (usually, multiplicative identity) for this type.
74     fn one() -> Self;
75 }
76
77 macro_rules! zero_one_impl {
78     ($($t:ty)*) => ($(
79         impl Zero for $t {
80             #[inline]
81             fn zero() -> Self { 0 }
82         }
83         impl One for $t {
84             #[inline]
85             fn one() -> Self { 1 }
86         }
87     )*)
88 }
89 zero_one_impl! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
90
91 macro_rules! zero_one_impl_float {
92     ($($t:ty)*) => ($(
93         impl Zero for $t {
94             #[inline]
95             fn zero() -> Self { 0.0 }
96         }
97         impl One for $t {
98             #[inline]
99             fn one() -> Self { 1.0 }
100         }
101     )*)
102 }
103 zero_one_impl_float! { f32 f64 }
104
105 macro_rules! checked_op {
106     ($U:ty, $op:path, $x:expr, $y:expr) => {{
107         let (result, overflowed) = unsafe { $op($x as $U, $y as $U) };
108         if overflowed { None } else { Some(result as Self) }
109     }}
110 }
111
112 /// Swapping a single byte is a no-op. This is marked as `unsafe` for
113 /// consistency with the other `bswap` intrinsics.
114 unsafe fn bswap8(x: u8) -> u8 { x }
115
116 // `Int` + `SignedInt` implemented for signed integers
117 macro_rules! int_impl {
118     ($ActualT:ty, $UnsignedT:ty, $BITS:expr,
119      $add_with_overflow:path,
120      $sub_with_overflow:path,
121      $mul_with_overflow:path) => {
122         /// Returns the smallest value that can be represented by this integer type.
123         #[stable(feature = "rust1", since = "1.0.0")]
124         #[inline]
125         pub fn min_value() -> Self {
126             (-1 as Self) << ($BITS - 1)
127         }
128
129         /// Returns the largest value that can be represented by this integer type.
130         #[stable(feature = "rust1", since = "1.0.0")]
131         #[inline]
132         pub fn max_value() -> Self {
133             let min = Self::min_value(); !min
134         }
135
136         /// Converts a string slice in a given base to an integer.
137         ///
138         /// Leading and trailing whitespace represent an error.
139         ///
140         /// # Examples
141         ///
142         /// ```
143         /// assert_eq!(u32::from_str_radix("A", 16), Ok(10));
144         /// ```
145         #[stable(feature = "rust1", since = "1.0.0")]
146         pub fn from_str_radix(src: &str, radix: u32) -> Result<Self, ParseIntError> {
147             from_str_radix(src, radix)
148         }
149
150         /// Returns the number of ones in the binary representation of `self`.
151         ///
152         /// # Examples
153         ///
154         /// ```rust
155         /// let n = 0b01001100u8;
156         ///
157         /// assert_eq!(n.count_ones(), 3);
158         /// ```
159         #[stable(feature = "rust1", since = "1.0.0")]
160         #[inline]
161         pub fn count_ones(self) -> u32 { (self as $UnsignedT).count_ones() }
162
163         /// Returns the number of zeros in the binary representation of `self`.
164         ///
165         /// # Examples
166         ///
167         /// ```rust
168         /// let n = 0b01001100u8;
169         ///
170         /// assert_eq!(n.count_zeros(), 5);
171         /// ```
172         #[stable(feature = "rust1", since = "1.0.0")]
173         #[inline]
174         pub fn count_zeros(self) -> u32 {
175             (!self).count_ones()
176         }
177
178         /// Returns the number of leading zeros in the binary representation
179         /// of `self`.
180         ///
181         /// # Examples
182         ///
183         /// ```rust
184         /// let n = 0b0101000u16;
185         ///
186         /// assert_eq!(n.leading_zeros(), 10);
187         /// ```
188         #[stable(feature = "rust1", since = "1.0.0")]
189         #[inline]
190         pub fn leading_zeros(self) -> u32 {
191             (self as $UnsignedT).leading_zeros()
192         }
193
194         /// Returns the number of trailing zeros in the binary representation
195         /// of `self`.
196         ///
197         /// # Examples
198         ///
199         /// ```rust
200         /// let n = 0b0101000u16;
201         ///
202         /// assert_eq!(n.trailing_zeros(), 3);
203         /// ```
204         #[stable(feature = "rust1", since = "1.0.0")]
205         #[inline]
206         pub fn trailing_zeros(self) -> u32 {
207             (self as $UnsignedT).trailing_zeros()
208         }
209
210         /// Shifts the bits to the left by a specified amount, `n`,
211         /// wrapping the truncated bits to the end of the resulting integer.
212         ///
213         /// # Examples
214         ///
215         /// ```rust
216         /// let n = 0x0123456789ABCDEFu64;
217         /// let m = 0x3456789ABCDEF012u64;
218         ///
219         /// assert_eq!(n.rotate_left(12), m);
220         /// ```
221         #[stable(feature = "rust1", since = "1.0.0")]
222         #[inline]
223         pub fn rotate_left(self, n: u32) -> Self {
224             (self as $UnsignedT).rotate_left(n) as Self
225         }
226
227         /// Shifts the bits to the right by a specified amount, `n`,
228         /// wrapping the truncated bits to the beginning of the resulting
229         /// integer.
230         ///
231         /// # Examples
232         ///
233         /// ```rust
234         /// let n = 0x0123456789ABCDEFu64;
235         /// let m = 0xDEF0123456789ABCu64;
236         ///
237         /// assert_eq!(n.rotate_right(12), m);
238         /// ```
239         #[stable(feature = "rust1", since = "1.0.0")]
240         #[inline]
241         pub fn rotate_right(self, n: u32) -> Self {
242             (self as $UnsignedT).rotate_right(n) as Self
243         }
244
245         /// Reverses the byte order of the integer.
246         ///
247         /// # Examples
248         ///
249         /// ```rust
250         /// let n = 0x0123456789ABCDEFu64;
251         /// let m = 0xEFCDAB8967452301u64;
252         ///
253         /// assert_eq!(n.swap_bytes(), m);
254         /// ```
255         #[stable(feature = "rust1", since = "1.0.0")]
256         #[inline]
257         pub fn swap_bytes(self) -> Self {
258             (self as $UnsignedT).swap_bytes() as Self
259         }
260
261         /// Converts an integer from big endian to the target's endianness.
262         ///
263         /// On big endian this is a no-op. On little endian the bytes are
264         /// swapped.
265         ///
266         /// # Examples
267         ///
268         /// ```rust
269         /// let n = 0x0123456789ABCDEFu64;
270         ///
271         /// if cfg!(target_endian = "big") {
272         ///     assert_eq!(u64::from_be(n), n)
273         /// } else {
274         ///     assert_eq!(u64::from_be(n), n.swap_bytes())
275         /// }
276         /// ```
277         #[stable(feature = "rust1", since = "1.0.0")]
278         #[inline]
279         pub fn from_be(x: Self) -> Self {
280             if cfg!(target_endian = "big") { x } else { x.swap_bytes() }
281         }
282
283         /// Converts an integer from little endian to the target's endianness.
284         ///
285         /// On little endian this is a no-op. On big endian the bytes are
286         /// swapped.
287         ///
288         /// # Examples
289         ///
290         /// ```rust
291         /// let n = 0x0123456789ABCDEFu64;
292         ///
293         /// if cfg!(target_endian = "little") {
294         ///     assert_eq!(u64::from_le(n), n)
295         /// } else {
296         ///     assert_eq!(u64::from_le(n), n.swap_bytes())
297         /// }
298         /// ```
299         #[stable(feature = "rust1", since = "1.0.0")]
300         #[inline]
301         pub fn from_le(x: Self) -> Self {
302             if cfg!(target_endian = "little") { x } else { x.swap_bytes() }
303         }
304
305         /// Converts `self` to big endian from the target's endianness.
306         ///
307         /// On big endian this is a no-op. On little endian the bytes are
308         /// swapped.
309         ///
310         /// # Examples
311         ///
312         /// ```rust
313         /// let n = 0x0123456789ABCDEFu64;
314         ///
315         /// if cfg!(target_endian = "big") {
316         ///     assert_eq!(n.to_be(), n)
317         /// } else {
318         ///     assert_eq!(n.to_be(), n.swap_bytes())
319         /// }
320         /// ```
321         #[stable(feature = "rust1", since = "1.0.0")]
322         #[inline]
323         pub fn to_be(self) -> Self { // or not to be?
324             if cfg!(target_endian = "big") { self } else { self.swap_bytes() }
325         }
326
327         /// Converts `self` to little endian from the target's endianness.
328         ///
329         /// On little endian this is a no-op. On big endian the bytes are
330         /// swapped.
331         ///
332         /// # Examples
333         ///
334         /// ```rust
335         /// let n = 0x0123456789ABCDEFu64;
336         ///
337         /// if cfg!(target_endian = "little") {
338         ///     assert_eq!(n.to_le(), n)
339         /// } else {
340         ///     assert_eq!(n.to_le(), n.swap_bytes())
341         /// }
342         /// ```
343         #[stable(feature = "rust1", since = "1.0.0")]
344         #[inline]
345         pub fn to_le(self) -> Self {
346             if cfg!(target_endian = "little") { self } else { self.swap_bytes() }
347         }
348
349         /// Checked integer addition. Computes `self + other`, returning `None`
350         /// if overflow occurred.
351         ///
352         /// # Examples
353         ///
354         /// ```rust
355         /// assert_eq!(5u16.checked_add(65530), Some(65535));
356         /// assert_eq!(6u16.checked_add(65530), None);
357         /// ```
358         #[stable(feature = "rust1", since = "1.0.0")]
359         #[inline]
360         pub fn checked_add(self, other: Self) -> Option<Self> {
361             checked_op!($ActualT, $add_with_overflow, self, other)
362         }
363
364         /// Checked integer subtraction. Computes `self - other`, returning
365         /// `None` if underflow occurred.
366         ///
367         /// # Examples
368         ///
369         /// ```rust
370         /// assert_eq!((-127i8).checked_sub(1), Some(-128));
371         /// assert_eq!((-128i8).checked_sub(1), None);
372         /// ```
373         #[stable(feature = "rust1", since = "1.0.0")]
374         #[inline]
375         pub fn checked_sub(self, other: Self) -> Option<Self> {
376             checked_op!($ActualT, $sub_with_overflow, self, other)
377         }
378
379         /// Checked integer multiplication. Computes `self * other`, returning
380         /// `None` if underflow or overflow occurred.
381         ///
382         /// # Examples
383         ///
384         /// ```rust
385         /// assert_eq!(5u8.checked_mul(51), Some(255));
386         /// assert_eq!(5u8.checked_mul(52), None);
387         /// ```
388         #[stable(feature = "rust1", since = "1.0.0")]
389         #[inline]
390         pub fn checked_mul(self, other: Self) -> Option<Self> {
391             checked_op!($ActualT, $mul_with_overflow, self, other)
392         }
393
394         /// Checked integer division. Computes `self / other`, returning `None`
395         /// if `other == 0` or the operation results in underflow or overflow.
396         ///
397         /// # Examples
398         ///
399         /// ```rust
400         /// assert_eq!((-127i8).checked_div(-1), Some(127));
401         /// assert_eq!((-128i8).checked_div(-1), None);
402         /// assert_eq!((1i8).checked_div(0), None);
403         /// ```
404         #[stable(feature = "rust1", since = "1.0.0")]
405         #[inline]
406         pub fn checked_div(self, v: Self) -> Option<Self> {
407             match v {
408                 0   => None,
409                -1 if self == Self::min_value()
410                     => None,
411                 v   => Some(self / v),
412             }
413         }
414
415         /// Saturating integer addition. Computes `self + other`, saturating at
416         /// the numeric bounds instead of overflowing.
417         #[stable(feature = "rust1", since = "1.0.0")]
418         #[inline]
419         pub fn saturating_add(self, other: Self) -> Self {
420             match self.checked_add(other) {
421                 Some(x)                       => x,
422                 None if other >= Self::zero() => Self::max_value(),
423                 None => Self::min_value(),
424             }
425         }
426
427         /// Saturating integer subtraction. Computes `self - other`, saturating
428         /// at the numeric bounds instead of overflowing.
429         #[stable(feature = "rust1", since = "1.0.0")]
430         #[inline]
431         pub fn saturating_sub(self, other: Self) -> Self {
432             match self.checked_sub(other) {
433                 Some(x)                      => x,
434                 None if other >= Self::zero() => Self::min_value(),
435                 None => Self::max_value(),
436             }
437         }
438
439         /// Wrapping (modular) addition. Computes `self + other`,
440         /// wrapping around at the boundary of the type.
441         #[stable(feature = "rust1", since = "1.0.0")]
442         #[inline]
443         pub fn wrapping_add(self, rhs: Self) -> Self {
444             unsafe {
445                 intrinsics::overflowing_add(self, rhs)
446             }
447         }
448
449         /// Wrapping (modular) subtraction. Computes `self - other`,
450         /// wrapping around at the boundary of the type.
451         #[stable(feature = "rust1", since = "1.0.0")]
452         #[inline]
453         pub fn wrapping_sub(self, rhs: Self) -> Self {
454             unsafe {
455                 intrinsics::overflowing_sub(self, rhs)
456             }
457         }
458
459         /// Wrapping (modular) multiplication. Computes `self *
460         /// other`, wrapping around at the boundary of the type.
461         #[stable(feature = "rust1", since = "1.0.0")]
462         #[inline]
463         pub fn wrapping_mul(self, rhs: Self) -> Self {
464             unsafe {
465                 intrinsics::overflowing_mul(self, rhs)
466             }
467         }
468
469         /// Wrapping (modular) division. Computes `self / other`,
470         /// wrapping around at the boundary of the type.
471         ///
472         /// The only case where such wrapping can occur is when one
473         /// divides `MIN / -1` on a signed type (where `MIN` is the
474         /// negative minimal value for the type); this is equivalent
475         /// to `-MIN`, a positive value that is too large to represent
476         /// in the type. In such a case, this function returns `MIN`
477         /// itself.
478         #[stable(feature = "num_wrapping", since = "1.2.0")]
479         #[inline(always)]
480         pub fn wrapping_div(self, rhs: Self) -> Self {
481             self.overflowing_div(rhs).0
482         }
483
484         /// Wrapping (modular) remainder. Computes `self % other`,
485         /// wrapping around at the boundary of the type.
486         ///
487         /// Such wrap-around never actually occurs mathematically;
488         /// implementation artifacts make `x % y` invalid for `MIN /
489         /// -1` on a signed type (where `MIN` is the negative
490         /// minimal value). In such a case, this function returns `0`.
491         #[stable(feature = "num_wrapping", since = "1.2.0")]
492         #[inline(always)]
493         pub fn wrapping_rem(self, rhs: Self) -> Self {
494             self.overflowing_rem(rhs).0
495         }
496
497         /// Wrapping (modular) negation. Computes `-self`,
498         /// wrapping around at the boundary of the type.
499         ///
500         /// The only case where such wrapping can occur is when one
501         /// negates `MIN` on a signed type (where `MIN` is the
502         /// negative minimal value for the type); this is a positive
503         /// value that is too large to represent in the type. In such
504         /// a case, this function returns `MIN` itself.
505         #[stable(feature = "num_wrapping", since = "1.2.0")]
506         #[inline(always)]
507         pub fn wrapping_neg(self) -> Self {
508             self.overflowing_neg().0
509         }
510
511         /// Panic-free bitwise shift-left; yields `self << mask(rhs)`,
512         /// where `mask` removes any high-order bits of `rhs` that
513         /// would cause the shift to exceed the bitwidth of the type.
514         #[stable(feature = "num_wrapping", since = "1.2.0")]
515         #[inline(always)]
516         pub fn wrapping_shl(self, rhs: u32) -> Self {
517             self.overflowing_shl(rhs).0
518         }
519
520         /// Panic-free bitwise shift-left; yields `self >> mask(rhs)`,
521         /// where `mask` removes any high-order bits of `rhs` that
522         /// would cause the shift to exceed the bitwidth of the type.
523         #[stable(feature = "num_wrapping", since = "1.2.0")]
524         #[inline(always)]
525         pub fn wrapping_shr(self, rhs: u32) -> Self {
526             self.overflowing_shr(rhs).0
527         }
528
529         /// Raises self to the power of `exp`, using exponentiation by squaring.
530         ///
531         /// # Examples
532         ///
533         /// ```
534         /// let x: i32 = 2; // or any other integer type
535         ///
536         /// assert_eq!(x.pow(4), 16);
537         /// ```
538         #[stable(feature = "rust1", since = "1.0.0")]
539         #[inline]
540         pub fn pow(self, mut exp: u32) -> Self {
541             let mut base = self;
542             let mut acc = Self::one();
543
544             while exp > 1 {
545                 if (exp & 1) == 1 {
546                     acc = acc * base;
547                 }
548                 exp /= 2;
549                 base = base * base;
550             }
551
552             // Deal with the final bit of the exponent separately, since
553             // squaring the base afterwards is not necessary and may cause a
554             // needless overflow.
555             if exp == 1 {
556                 acc = acc * base;
557             }
558
559             acc
560         }
561
562         /// Computes the absolute value of `self`.
563         ///
564         /// # Overflow behavior
565         ///
566         /// The absolute value of `i32::min_value()` cannot be represented as an
567         /// `i32`, and attempting to calculate it will cause an overflow. This
568         /// means that code in debug mode will trigger a panic on this case and
569         /// optimized code will return `i32::min_value()` without a panic.
570         #[stable(feature = "rust1", since = "1.0.0")]
571         #[inline]
572         pub fn abs(self) -> Self {
573             if self.is_negative() {
574                 // Note that the #[inline] above means that the overflow
575                 // semantics of this negation depend on the crate we're being
576                 // inlined into.
577                 -self
578             } else {
579                 self
580             }
581         }
582
583         /// Returns a number representing sign of `self`.
584         ///
585         /// - `0` if the number is zero
586         /// - `1` if the number is positive
587         /// - `-1` if the number is negative
588         #[stable(feature = "rust1", since = "1.0.0")]
589         #[inline]
590         pub fn signum(self) -> Self {
591             match self {
592                 n if n > 0 =>  1,
593                 0          =>  0,
594                 _          => -1,
595             }
596         }
597
598         /// Returns `true` if `self` is positive and `false` if the number
599         /// is zero or negative.
600         #[stable(feature = "rust1", since = "1.0.0")]
601         #[inline]
602         pub fn is_positive(self) -> bool { self > 0 }
603
604         /// Returns `true` if `self` is negative and `false` if the number
605         /// is zero or positive.
606         #[stable(feature = "rust1", since = "1.0.0")]
607         #[inline]
608         pub fn is_negative(self) -> bool { self < 0 }
609     }
610 }
611
612 #[lang = "i8"]
613 impl i8 {
614     int_impl! { i8, u8, 8,
615         intrinsics::i8_add_with_overflow,
616         intrinsics::i8_sub_with_overflow,
617         intrinsics::i8_mul_with_overflow }
618 }
619
620 #[lang = "i16"]
621 impl i16 {
622     int_impl! { i16, u16, 16,
623         intrinsics::i16_add_with_overflow,
624         intrinsics::i16_sub_with_overflow,
625         intrinsics::i16_mul_with_overflow }
626 }
627
628 #[lang = "i32"]
629 impl i32 {
630     int_impl! { i32, u32, 32,
631         intrinsics::i32_add_with_overflow,
632         intrinsics::i32_sub_with_overflow,
633         intrinsics::i32_mul_with_overflow }
634 }
635
636 #[lang = "i64"]
637 impl i64 {
638     int_impl! { i64, u64, 64,
639         intrinsics::i64_add_with_overflow,
640         intrinsics::i64_sub_with_overflow,
641         intrinsics::i64_mul_with_overflow }
642 }
643
644 #[cfg(target_pointer_width = "32")]
645 #[lang = "isize"]
646 impl isize {
647     int_impl! { i32, u32, 32,
648         intrinsics::i32_add_with_overflow,
649         intrinsics::i32_sub_with_overflow,
650         intrinsics::i32_mul_with_overflow }
651 }
652
653 #[cfg(target_pointer_width = "64")]
654 #[lang = "isize"]
655 impl isize {
656     int_impl! { i64, u64, 64,
657         intrinsics::i64_add_with_overflow,
658         intrinsics::i64_sub_with_overflow,
659         intrinsics::i64_mul_with_overflow }
660 }
661
662 // `Int` + `UnsignedInt` implemented for signed integers
663 macro_rules! uint_impl {
664     ($ActualT:ty, $BITS:expr,
665      $ctpop:path,
666      $ctlz:path,
667      $cttz:path,
668      $bswap:path,
669      $add_with_overflow:path,
670      $sub_with_overflow:path,
671      $mul_with_overflow:path) => {
672         /// Returns the smallest value that can be represented by this integer type.
673         #[stable(feature = "rust1", since = "1.0.0")]
674         #[inline]
675         pub fn min_value() -> Self { 0 }
676
677         /// Returns the largest value that can be represented by this integer type.
678         #[stable(feature = "rust1", since = "1.0.0")]
679         #[inline]
680         pub fn max_value() -> Self { !0 }
681
682         /// Converts a string slice in a given base to an integer.
683         ///
684         /// Leading and trailing whitespace represent an error.
685         ///
686         /// # Arguments
687         ///
688         /// * src - A string slice
689         /// * radix - The base to use. Must lie in the range [2 .. 36]
690         ///
691         /// # Return value
692         ///
693         /// `Err(ParseIntError)` if the string did not represent a valid number.
694         /// Otherwise, `Ok(n)` where `n` is the integer represented by `src`.
695         #[stable(feature = "rust1", since = "1.0.0")]
696         pub fn from_str_radix(src: &str, radix: u32) -> Result<Self, ParseIntError> {
697             from_str_radix(src, radix)
698         }
699
700         /// Returns the number of ones in the binary representation of `self`.
701         ///
702         /// # Examples
703         ///
704         /// ```rust
705         /// let n = 0b01001100u8;
706         ///
707         /// assert_eq!(n.count_ones(), 3);
708         /// ```
709         #[stable(feature = "rust1", since = "1.0.0")]
710         #[inline]
711         pub fn count_ones(self) -> u32 {
712             unsafe { $ctpop(self as $ActualT) as u32 }
713         }
714
715         /// Returns the number of zeros in the binary representation of `self`.
716         ///
717         /// # Examples
718         ///
719         /// ```rust
720         /// let n = 0b01001100u8;
721         ///
722         /// assert_eq!(n.count_zeros(), 5);
723         /// ```
724         #[stable(feature = "rust1", since = "1.0.0")]
725         #[inline]
726         pub fn count_zeros(self) -> u32 {
727             (!self).count_ones()
728         }
729
730         /// Returns the number of leading zeros in the binary representation
731         /// of `self`.
732         ///
733         /// # Examples
734         ///
735         /// ```rust
736         /// let n = 0b0101000u16;
737         ///
738         /// assert_eq!(n.leading_zeros(), 10);
739         /// ```
740         #[stable(feature = "rust1", since = "1.0.0")]
741         #[inline]
742         pub fn leading_zeros(self) -> u32 {
743             unsafe { $ctlz(self as $ActualT) as u32 }
744         }
745
746         /// Returns the number of trailing zeros in the binary representation
747         /// of `self`.
748         ///
749         /// # Examples
750         ///
751         /// ```rust
752         /// let n = 0b0101000u16;
753         ///
754         /// assert_eq!(n.trailing_zeros(), 3);
755         /// ```
756         #[stable(feature = "rust1", since = "1.0.0")]
757         #[inline]
758         pub fn trailing_zeros(self) -> u32 {
759             // As of LLVM 3.6 the codegen for the zero-safe cttz8 intrinsic
760             // emits two conditional moves on x86_64. By promoting the value to
761             // u16 and setting bit 8, we get better code without any conditional
762             // operations.
763             // FIXME: There's a LLVM patch (http://reviews.llvm.org/D9284)
764             // pending, remove this workaround once LLVM generates better code
765             // for cttz8.
766             unsafe {
767                 if $BITS == 8 {
768                     intrinsics::cttz16(self as u16 | 0x100) as u32
769                 } else {
770                     $cttz(self as $ActualT) as u32
771                 }
772             }
773         }
774
775         /// Shifts the bits to the left by a specified amount, `n`,
776         /// wrapping the truncated bits to the end of the resulting integer.
777         ///
778         /// # Examples
779         ///
780         /// ```rust
781         /// let n = 0x0123456789ABCDEFu64;
782         /// let m = 0x3456789ABCDEF012u64;
783         ///
784         /// assert_eq!(n.rotate_left(12), m);
785         /// ```
786         #[stable(feature = "rust1", since = "1.0.0")]
787         #[inline]
788         pub fn rotate_left(self, n: u32) -> Self {
789             // Protect against undefined behaviour for over-long bit shifts
790             let n = n % $BITS;
791             (self << n) | (self >> (($BITS - n) % $BITS))
792         }
793
794         /// Shifts the bits to the right by a specified amount, `n`,
795         /// wrapping the truncated bits to the beginning of the resulting
796         /// integer.
797         ///
798         /// # Examples
799         ///
800         /// ```rust
801         /// let n = 0x0123456789ABCDEFu64;
802         /// let m = 0xDEF0123456789ABCu64;
803         ///
804         /// assert_eq!(n.rotate_right(12), m);
805         /// ```
806         #[stable(feature = "rust1", since = "1.0.0")]
807         #[inline]
808         pub fn rotate_right(self, n: u32) -> Self {
809             // Protect against undefined behaviour for over-long bit shifts
810             let n = n % $BITS;
811             (self >> n) | (self << (($BITS - n) % $BITS))
812         }
813
814         /// Reverses the byte order of the integer.
815         ///
816         /// # Examples
817         ///
818         /// ```rust
819         /// let n = 0x0123456789ABCDEFu64;
820         /// let m = 0xEFCDAB8967452301u64;
821         ///
822         /// assert_eq!(n.swap_bytes(), m);
823         /// ```
824         #[stable(feature = "rust1", since = "1.0.0")]
825         #[inline]
826         pub fn swap_bytes(self) -> Self {
827             unsafe { $bswap(self as $ActualT) as Self }
828         }
829
830         /// Converts an integer from big endian to the target's endianness.
831         ///
832         /// On big endian this is a no-op. On little endian the bytes are
833         /// swapped.
834         ///
835         /// # Examples
836         ///
837         /// ```rust
838         /// let n = 0x0123456789ABCDEFu64;
839         ///
840         /// if cfg!(target_endian = "big") {
841         ///     assert_eq!(u64::from_be(n), n)
842         /// } else {
843         ///     assert_eq!(u64::from_be(n), n.swap_bytes())
844         /// }
845         /// ```
846         #[stable(feature = "rust1", since = "1.0.0")]
847         #[inline]
848         pub fn from_be(x: Self) -> Self {
849             if cfg!(target_endian = "big") { x } else { x.swap_bytes() }
850         }
851
852         /// Converts an integer from little endian to the target's endianness.
853         ///
854         /// On little endian this is a no-op. On big endian the bytes are
855         /// swapped.
856         ///
857         /// # Examples
858         ///
859         /// ```rust
860         /// let n = 0x0123456789ABCDEFu64;
861         ///
862         /// if cfg!(target_endian = "little") {
863         ///     assert_eq!(u64::from_le(n), n)
864         /// } else {
865         ///     assert_eq!(u64::from_le(n), n.swap_bytes())
866         /// }
867         /// ```
868         #[stable(feature = "rust1", since = "1.0.0")]
869         #[inline]
870         pub fn from_le(x: Self) -> Self {
871             if cfg!(target_endian = "little") { x } else { x.swap_bytes() }
872         }
873
874         /// Converts `self` to big endian from the target's endianness.
875         ///
876         /// On big endian this is a no-op. On little endian the bytes are
877         /// swapped.
878         ///
879         /// # Examples
880         ///
881         /// ```rust
882         /// let n = 0x0123456789ABCDEFu64;
883         ///
884         /// if cfg!(target_endian = "big") {
885         ///     assert_eq!(n.to_be(), n)
886         /// } else {
887         ///     assert_eq!(n.to_be(), n.swap_bytes())
888         /// }
889         /// ```
890         #[stable(feature = "rust1", since = "1.0.0")]
891         #[inline]
892         pub fn to_be(self) -> Self { // or not to be?
893             if cfg!(target_endian = "big") { self } else { self.swap_bytes() }
894         }
895
896         /// Converts `self` to little endian from the target's endianness.
897         ///
898         /// On little endian this is a no-op. On big endian the bytes are
899         /// swapped.
900         ///
901         /// # Examples
902         ///
903         /// ```rust
904         /// let n = 0x0123456789ABCDEFu64;
905         ///
906         /// if cfg!(target_endian = "little") {
907         ///     assert_eq!(n.to_le(), n)
908         /// } else {
909         ///     assert_eq!(n.to_le(), n.swap_bytes())
910         /// }
911         /// ```
912         #[stable(feature = "rust1", since = "1.0.0")]
913         #[inline]
914         pub fn to_le(self) -> Self {
915             if cfg!(target_endian = "little") { self } else { self.swap_bytes() }
916         }
917
918         /// Checked integer addition. Computes `self + other`, returning `None`
919         /// if overflow occurred.
920         ///
921         /// # Examples
922         ///
923         /// ```rust
924         /// assert_eq!(5u16.checked_add(65530), Some(65535));
925         /// assert_eq!(6u16.checked_add(65530), None);
926         /// ```
927         #[stable(feature = "rust1", since = "1.0.0")]
928         #[inline]
929         pub fn checked_add(self, other: Self) -> Option<Self> {
930             checked_op!($ActualT, $add_with_overflow, self, other)
931         }
932
933         /// Checked integer subtraction. Computes `self - other`, returning
934         /// `None` if underflow occurred.
935         ///
936         /// # Examples
937         ///
938         /// ```rust
939         /// assert_eq!((-127i8).checked_sub(1), Some(-128));
940         /// assert_eq!((-128i8).checked_sub(1), None);
941         /// ```
942         #[stable(feature = "rust1", since = "1.0.0")]
943         #[inline]
944         pub fn checked_sub(self, other: Self) -> Option<Self> {
945             checked_op!($ActualT, $sub_with_overflow, self, other)
946         }
947
948         /// Checked integer multiplication. Computes `self * other`, returning
949         /// `None` if underflow or overflow occurred.
950         ///
951         /// # Examples
952         ///
953         /// ```rust
954         /// assert_eq!(5u8.checked_mul(51), Some(255));
955         /// assert_eq!(5u8.checked_mul(52), None);
956         /// ```
957         #[stable(feature = "rust1", since = "1.0.0")]
958         #[inline]
959         pub fn checked_mul(self, other: Self) -> Option<Self> {
960             checked_op!($ActualT, $mul_with_overflow, self, other)
961         }
962
963         /// Checked integer division. Computes `self / other`, returning `None`
964         /// if `other == 0` or the operation results in underflow or overflow.
965         ///
966         /// # Examples
967         ///
968         /// ```rust
969         /// assert_eq!((-127i8).checked_div(-1), Some(127));
970         /// assert_eq!((-128i8).checked_div(-1), None);
971         /// assert_eq!((1i8).checked_div(0), None);
972         /// ```
973         #[stable(feature = "rust1", since = "1.0.0")]
974         #[inline]
975         pub fn checked_div(self, v: Self) -> Option<Self> {
976             match v {
977                 0 => None,
978                 v => Some(self / v),
979             }
980         }
981
982         /// Saturating integer addition. Computes `self + other`, saturating at
983         /// the numeric bounds instead of overflowing.
984         #[stable(feature = "rust1", since = "1.0.0")]
985         #[inline]
986         pub fn saturating_add(self, other: Self) -> Self {
987             match self.checked_add(other) {
988                 Some(x)                       => x,
989                 None if other >= Self::zero() => Self::max_value(),
990                 None => Self::min_value(),
991             }
992         }
993
994         /// Saturating integer subtraction. Computes `self - other`, saturating
995         /// at the numeric bounds instead of overflowing.
996         #[stable(feature = "rust1", since = "1.0.0")]
997         #[inline]
998         pub fn saturating_sub(self, other: Self) -> Self {
999             match self.checked_sub(other) {
1000                 Some(x)                       => x,
1001                 None if other >= Self::zero() => Self::min_value(),
1002                 None => Self::max_value(),
1003             }
1004         }
1005
1006         /// Wrapping (modular) addition. Computes `self + other`,
1007         /// wrapping around at the boundary of the type.
1008         #[stable(feature = "rust1", since = "1.0.0")]
1009         #[inline]
1010         pub fn wrapping_add(self, rhs: Self) -> Self {
1011             unsafe {
1012                 intrinsics::overflowing_add(self, rhs)
1013             }
1014         }
1015
1016         /// Wrapping (modular) subtraction. Computes `self - other`,
1017         /// wrapping around at the boundary of the type.
1018         #[stable(feature = "rust1", since = "1.0.0")]
1019         #[inline]
1020         pub fn wrapping_sub(self, rhs: Self) -> Self {
1021             unsafe {
1022                 intrinsics::overflowing_sub(self, rhs)
1023             }
1024         }
1025
1026         /// Wrapping (modular) multiplication. Computes `self *
1027         /// other`, wrapping around at the boundary of the type.
1028         #[stable(feature = "rust1", since = "1.0.0")]
1029         #[inline]
1030         pub fn wrapping_mul(self, rhs: Self) -> Self {
1031             unsafe {
1032                 intrinsics::overflowing_mul(self, rhs)
1033             }
1034         }
1035
1036         /// Wrapping (modular) division. Computes `self / other`,
1037         /// wrapping around at the boundary of the type.
1038         ///
1039         /// The only case where such wrapping can occur is when one
1040         /// divides `MIN / -1` on a signed type (where `MIN` is the
1041         /// negative minimal value for the type); this is equivalent
1042         /// to `-MIN`, a positive value that is too large to represent
1043         /// in the type. In such a case, this function returns `MIN`
1044         /// itself.
1045         #[stable(feature = "num_wrapping", since = "1.2.0")]
1046         #[inline(always)]
1047         pub fn wrapping_div(self, rhs: Self) -> Self {
1048             self.overflowing_div(rhs).0
1049         }
1050
1051         /// Wrapping (modular) remainder. Computes `self % other`,
1052         /// wrapping around at the boundary of the type.
1053         ///
1054         /// Such wrap-around never actually occurs mathematically;
1055         /// implementation artifacts make `x % y` invalid for `MIN /
1056         /// -1` on a signed type (where `MIN` is the negative
1057         /// minimal value). In such a case, this function returns `0`.
1058         #[stable(feature = "num_wrapping", since = "1.2.0")]
1059         #[inline(always)]
1060         pub fn wrapping_rem(self, rhs: Self) -> Self {
1061             self.overflowing_rem(rhs).0
1062         }
1063
1064         /// Wrapping (modular) negation. Computes `-self`,
1065         /// wrapping around at the boundary of the type.
1066         ///
1067         /// The only case where such wrapping can occur is when one
1068         /// negates `MIN` on a signed type (where `MIN` is the
1069         /// negative minimal value for the type); this is a positive
1070         /// value that is too large to represent in the type. In such
1071         /// a case, this function returns `MIN` itself.
1072         #[stable(feature = "num_wrapping", since = "1.2.0")]
1073         #[inline(always)]
1074         pub fn wrapping_neg(self) -> Self {
1075             self.overflowing_neg().0
1076         }
1077
1078         /// Panic-free bitwise shift-left; yields `self << mask(rhs)`,
1079         /// where `mask` removes any high-order bits of `rhs` that
1080         /// would cause the shift to exceed the bitwidth of the type.
1081         #[stable(feature = "num_wrapping", since = "1.2.0")]
1082         #[inline(always)]
1083         pub fn wrapping_shl(self, rhs: u32) -> Self {
1084             self.overflowing_shl(rhs).0
1085         }
1086
1087         /// Panic-free bitwise shift-left; yields `self >> mask(rhs)`,
1088         /// where `mask` removes any high-order bits of `rhs` that
1089         /// would cause the shift to exceed the bitwidth of the type.
1090         #[stable(feature = "num_wrapping", since = "1.2.0")]
1091         #[inline(always)]
1092         pub fn wrapping_shr(self, rhs: u32) -> Self {
1093             self.overflowing_shr(rhs).0
1094         }
1095
1096         /// Raises self to the power of `exp`, using exponentiation by squaring.
1097         ///
1098         /// # Examples
1099         ///
1100         /// ```rust
1101         /// assert_eq!(2i32.pow(4), 16);
1102         /// ```
1103         #[stable(feature = "rust1", since = "1.0.0")]
1104         #[inline]
1105         pub fn pow(self, mut exp: u32) -> Self {
1106             let mut base = self;
1107             let mut acc = Self::one();
1108
1109             let mut prev_base = self;
1110             let mut base_oflo = false;
1111             while exp > 0 {
1112                 if (exp & 1) == 1 {
1113                     if base_oflo {
1114                         // ensure overflow occurs in the same manner it
1115                         // would have otherwise (i.e. signal any exception
1116                         // it would have otherwise).
1117                         acc = acc * (prev_base * prev_base);
1118                     } else {
1119                         acc = acc * base;
1120                     }
1121                 }
1122                 prev_base = base;
1123                 let (new_base, new_base_oflo) = base.overflowing_mul(base);
1124                 base = new_base;
1125                 base_oflo = new_base_oflo;
1126                 exp /= 2;
1127             }
1128             acc
1129         }
1130
1131         /// Returns `true` if and only if `self == 2^k` for some `k`.
1132         #[stable(feature = "rust1", since = "1.0.0")]
1133         #[inline]
1134         pub fn is_power_of_two(self) -> bool {
1135             (self.wrapping_sub(Self::one())) & self == Self::zero() &&
1136                 !(self == Self::zero())
1137         }
1138
1139         /// Returns the smallest power of two greater than or equal to `self`.
1140         /// Unspecified behavior on overflow.
1141         #[stable(feature = "rust1", since = "1.0.0")]
1142         #[inline]
1143         pub fn next_power_of_two(self) -> Self {
1144             let bits = size_of::<Self>() * 8;
1145             let one: Self = Self::one();
1146             one << ((bits - self.wrapping_sub(one).leading_zeros() as usize) % bits)
1147         }
1148
1149         /// Returns the smallest power of two greater than or equal to `n`. If
1150         /// the next power of two is greater than the type's maximum value,
1151         /// `None` is returned, otherwise the power of two is wrapped in `Some`.
1152         #[stable(feature = "rust1", since = "1.0.0")]
1153         pub fn checked_next_power_of_two(self) -> Option<Self> {
1154             let npot = self.next_power_of_two();
1155             if npot >= self {
1156                 Some(npot)
1157             } else {
1158                 None
1159             }
1160         }
1161     }
1162 }
1163
1164 #[lang = "u8"]
1165 impl u8 {
1166     uint_impl! { u8, 8,
1167         intrinsics::ctpop8,
1168         intrinsics::ctlz8,
1169         intrinsics::cttz8,
1170         bswap8,
1171         intrinsics::u8_add_with_overflow,
1172         intrinsics::u8_sub_with_overflow,
1173         intrinsics::u8_mul_with_overflow }
1174 }
1175
1176 #[lang = "u16"]
1177 impl u16 {
1178     uint_impl! { u16, 16,
1179         intrinsics::ctpop16,
1180         intrinsics::ctlz16,
1181         intrinsics::cttz16,
1182         intrinsics::bswap16,
1183         intrinsics::u16_add_with_overflow,
1184         intrinsics::u16_sub_with_overflow,
1185         intrinsics::u16_mul_with_overflow }
1186 }
1187
1188 #[lang = "u32"]
1189 impl u32 {
1190     uint_impl! { u32, 32,
1191         intrinsics::ctpop32,
1192         intrinsics::ctlz32,
1193         intrinsics::cttz32,
1194         intrinsics::bswap32,
1195         intrinsics::u32_add_with_overflow,
1196         intrinsics::u32_sub_with_overflow,
1197         intrinsics::u32_mul_with_overflow }
1198 }
1199
1200
1201 #[lang = "u64"]
1202 impl u64 {
1203     uint_impl! { u64, 64,
1204         intrinsics::ctpop64,
1205         intrinsics::ctlz64,
1206         intrinsics::cttz64,
1207         intrinsics::bswap64,
1208         intrinsics::u64_add_with_overflow,
1209         intrinsics::u64_sub_with_overflow,
1210         intrinsics::u64_mul_with_overflow }
1211 }
1212
1213 #[cfg(target_pointer_width = "32")]
1214 #[lang = "usize"]
1215 impl usize {
1216     uint_impl! { u32, 32,
1217         intrinsics::ctpop32,
1218         intrinsics::ctlz32,
1219         intrinsics::cttz32,
1220         intrinsics::bswap32,
1221         intrinsics::u32_add_with_overflow,
1222         intrinsics::u32_sub_with_overflow,
1223         intrinsics::u32_mul_with_overflow }
1224 }
1225
1226 #[cfg(target_pointer_width = "64")]
1227 #[lang = "usize"]
1228 impl usize {
1229     uint_impl! { u64, 64,
1230         intrinsics::ctpop64,
1231         intrinsics::ctlz64,
1232         intrinsics::cttz64,
1233         intrinsics::bswap64,
1234         intrinsics::u64_add_with_overflow,
1235         intrinsics::u64_sub_with_overflow,
1236         intrinsics::u64_mul_with_overflow }
1237 }
1238
1239 /// Used for representing the classification of floating point numbers
1240 #[derive(Copy, Clone, PartialEq, Debug)]
1241 #[stable(feature = "rust1", since = "1.0.0")]
1242 pub enum FpCategory {
1243     /// "Not a Number", often obtained by dividing by zero
1244     #[stable(feature = "rust1", since = "1.0.0")]
1245     Nan,
1246
1247     /// Positive or negative infinity
1248     #[stable(feature = "rust1", since = "1.0.0")]
1249     Infinite ,
1250
1251     /// Positive or negative zero
1252     #[stable(feature = "rust1", since = "1.0.0")]
1253     Zero,
1254
1255     /// De-normalized floating point representation (less precise than `Normal`)
1256     #[stable(feature = "rust1", since = "1.0.0")]
1257     Subnormal,
1258
1259     /// A regular floating point number
1260     #[stable(feature = "rust1", since = "1.0.0")]
1261     Normal,
1262 }
1263
1264 /// A built-in floating point number.
1265 #[doc(hidden)]
1266 #[unstable(feature = "core_float",
1267            reason = "stable interface is via `impl f{32,64}` in later crates",
1268            issue = "27702")]
1269 pub trait Float: Sized {
1270     /// Returns the NaN value.
1271     fn nan() -> Self;
1272     /// Returns the infinite value.
1273     fn infinity() -> Self;
1274     /// Returns the negative infinite value.
1275     fn neg_infinity() -> Self;
1276     /// Returns -0.0.
1277     fn neg_zero() -> Self;
1278     /// Returns 0.0.
1279     fn zero() -> Self;
1280     /// Returns 1.0.
1281     fn one() -> Self;
1282     /// Parses the string `s` with the radix `r` as a float.
1283     fn from_str_radix(s: &str, r: u32) -> Result<Self, ParseFloatError>;
1284
1285     /// Returns true if this value is NaN and false otherwise.
1286     fn is_nan(self) -> bool;
1287     /// Returns true if this value is positive infinity or negative infinity and
1288     /// false otherwise.
1289     fn is_infinite(self) -> bool;
1290     /// Returns true if this number is neither infinite nor NaN.
1291     fn is_finite(self) -> bool;
1292     /// Returns true if this number is neither zero, infinite, denormal, or NaN.
1293     fn is_normal(self) -> bool;
1294     /// Returns the category that this number falls into.
1295     fn classify(self) -> FpCategory;
1296
1297     /// Returns the mantissa, exponent and sign as integers, respectively.
1298     fn integer_decode(self) -> (u64, i16, i8);
1299
1300     /// Computes the absolute value of `self`. Returns `Float::nan()` if the
1301     /// number is `Float::nan()`.
1302     fn abs(self) -> Self;
1303     /// Returns a number that represents the sign of `self`.
1304     ///
1305     /// - `1.0` if the number is positive, `+0.0` or `Float::infinity()`
1306     /// - `-1.0` if the number is negative, `-0.0` or `Float::neg_infinity()`
1307     /// - `Float::nan()` if the number is `Float::nan()`
1308     fn signum(self) -> Self;
1309     /// Returns `true` if `self` is positive, including `+0.0` and
1310     /// `Float::infinity()`.
1311     fn is_positive(self) -> bool;
1312     /// Returns `true` if `self` is negative, including `-0.0` and
1313     /// `Float::neg_infinity()`.
1314     fn is_negative(self) -> bool;
1315
1316     /// Take the reciprocal (inverse) of a number, `1/x`.
1317     fn recip(self) -> Self;
1318
1319     /// Raise a number to an integer power.
1320     ///
1321     /// Using this function is generally faster than using `powf`
1322     fn powi(self, n: i32) -> Self;
1323
1324     /// Convert radians to degrees.
1325     fn to_degrees(self) -> Self;
1326     /// Convert degrees to radians.
1327     fn to_radians(self) -> Self;
1328 }
1329
1330 macro_rules! from_str_radix_int_impl {
1331     ($($t:ty)*) => {$(
1332         #[stable(feature = "rust1", since = "1.0.0")]
1333         impl FromStr for $t {
1334             type Err = ParseIntError;
1335             fn from_str(src: &str) -> Result<Self, ParseIntError> {
1336                 from_str_radix(src, 10)
1337             }
1338         }
1339     )*}
1340 }
1341 from_str_radix_int_impl! { isize i8 i16 i32 i64 usize u8 u16 u32 u64 }
1342
1343 #[doc(hidden)]
1344 trait FromStrRadixHelper: PartialOrd + Copy {
1345     fn min_value() -> Self;
1346     fn from_u32(u: u32) -> Self;
1347     fn checked_mul(&self, other: u32) -> Option<Self>;
1348     fn checked_sub(&self, other: u32) -> Option<Self>;
1349     fn checked_add(&self, other: u32) -> Option<Self>;
1350 }
1351
1352 macro_rules! doit {
1353     ($($t:ty)*) => ($(impl FromStrRadixHelper for $t {
1354         fn min_value() -> Self { Self::min_value() }
1355         fn from_u32(u: u32) -> Self { u as Self }
1356         fn checked_mul(&self, other: u32) -> Option<Self> {
1357             Self::checked_mul(*self, other as Self)
1358         }
1359         fn checked_sub(&self, other: u32) -> Option<Self> {
1360             Self::checked_sub(*self, other as Self)
1361         }
1362         fn checked_add(&self, other: u32) -> Option<Self> {
1363             Self::checked_add(*self, other as Self)
1364         }
1365     })*)
1366 }
1367 doit! { i8 i16 i32 i64 isize u8 u16 u32 u64 usize }
1368
1369 fn from_str_radix<T: FromStrRadixHelper>(src: &str, radix: u32)
1370                                          -> Result<T, ParseIntError> {
1371     use self::IntErrorKind::*;
1372     use self::ParseIntError as PIE;
1373
1374     assert!(radix >= 2 && radix <= 36,
1375            "from_str_radix_int: must lie in the range `[2, 36]` - found {}",
1376            radix);
1377
1378     if src.is_empty() {
1379         return Err(PIE { kind: Empty });
1380     }
1381
1382     let is_signed_ty = T::from_u32(0) > T::min_value();
1383
1384     // all valid digits are ascii, so we will just iterate over the utf8 bytes
1385     // and cast them to chars. .to_digit() will safely return None for anything
1386     // other than a valid ascii digit for a the given radix, including the first-byte
1387     // of multi-byte sequences
1388     let src = src.as_bytes();
1389
1390     let (is_positive, digits) = match src[0] {
1391         b'+' => (true, &src[1..]),
1392         b'-' if is_signed_ty => (false, &src[1..]),
1393         _ => (true, src)
1394     };
1395
1396     if digits.is_empty() {
1397         return Err(PIE { kind: Empty });
1398     }
1399
1400     let mut result = T::from_u32(0);
1401     if is_positive {
1402         // The number is positive
1403         for &c in digits {
1404             let x = match (c as char).to_digit(radix) {
1405                 Some(x) => x,
1406                 None => return Err(PIE { kind: InvalidDigit }),
1407             };
1408             result = match result.checked_mul(radix) {
1409                 Some(result) => result,
1410                 None => return Err(PIE { kind: Overflow }),
1411             };
1412             result = match result.checked_add(x) {
1413                 Some(result) => result,
1414                 None => return Err(PIE { kind: Overflow }),
1415             };
1416         }
1417     } else {
1418         // The number is negative
1419         for &c in digits {
1420             let x = match (c as char).to_digit(radix) {
1421                 Some(x) => x,
1422                 None => return Err(PIE { kind: InvalidDigit }),
1423             };
1424             result = match result.checked_mul(radix) {
1425                 Some(result) => result,
1426                 None => return Err(PIE { kind: Underflow }),
1427             };
1428             result = match result.checked_sub(x) {
1429                 Some(result) => result,
1430                 None => return Err(PIE { kind: Underflow }),
1431             };
1432         }
1433     }
1434     Ok(result)
1435 }
1436
1437 /// An error which can be returned when parsing an integer.
1438 #[derive(Debug, Clone, PartialEq)]
1439 #[stable(feature = "rust1", since = "1.0.0")]
1440 pub struct ParseIntError { kind: IntErrorKind }
1441
1442 #[derive(Debug, Clone, PartialEq)]
1443 enum IntErrorKind {
1444     Empty,
1445     InvalidDigit,
1446     Overflow,
1447     Underflow,
1448 }
1449
1450 impl ParseIntError {
1451     #[unstable(feature = "int_error_internals",
1452                reason = "available through Error trait and this method should \
1453                          not be exposed publicly",
1454                issue = "0")]
1455     #[doc(hidden)]
1456     pub fn __description(&self) -> &str {
1457         match self.kind {
1458             IntErrorKind::Empty => "cannot parse integer from empty string",
1459             IntErrorKind::InvalidDigit => "invalid digit found in string",
1460             IntErrorKind::Overflow => "number too large to fit in target type",
1461             IntErrorKind::Underflow => "number too small to fit in target type",
1462         }
1463     }
1464 }
1465
1466 #[stable(feature = "rust1", since = "1.0.0")]
1467 impl fmt::Display for ParseIntError {
1468     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1469         self.__description().fmt(f)
1470     }
1471 }
1472
1473 pub use num::dec2flt::ParseFloatError;