library/core/src/num/mod.rs

   1 //! Numeric traits and functions for the built-in numeric types.
   2
   3 #![stable(feature = "rust1", since = "1.0.0")]
   4
   5 use crate::ascii;
   6 use crate::intrinsics;
   7 use crate::mem;
   8 use crate::ops::{Add, Mul, Sub};
   9 use crate::str::FromStr;
  10
  11 // Used because the `?` operator is not allowed in a const context.
  12 macro_rules! try_opt {
  13     ($e:expr) => {
  14         match $e {
  15             Some(x) => x,
  16             None => return None,
  17         }
  18     };
  19 }
  20
  21 #[allow_internal_unstable(const_likely)]
  22 macro_rules! unlikely {
  23     ($e: expr) => {
  24         intrinsics::unlikely($e)
  25     };
  26 }
  27
  28 // All these modules are technically private and only exposed for coretests:
  29 #[cfg(not(no_fp_fmt_parse))]
  30 pub mod bignum;
  31 #[cfg(not(no_fp_fmt_parse))]
  32 pub mod dec2flt;
  33 #[cfg(not(no_fp_fmt_parse))]
  34 pub mod diy_float;
  35 #[cfg(not(no_fp_fmt_parse))]
  36 pub mod flt2dec;
  37 pub mod fmt;
  38
  39 #[macro_use]
  40 mod int_macros; // import int_impl!
  41 #[macro_use]
  42 mod uint_macros; // import uint_impl!
  43
  44 mod error;
  45 mod int_log10;
  46 mod nonzero;
  47 #[unstable(feature = "saturating_int_impl", issue = "87920")]
  48 mod saturating;
  49 mod wrapping;
  50
  51 #[unstable(feature = "saturating_int_impl", issue = "87920")]
  52 pub use saturating::Saturating;
  53 #[stable(feature = "rust1", since = "1.0.0")]
  54 pub use wrapping::Wrapping;
  55
  56 #[stable(feature = "rust1", since = "1.0.0")]
  57 #[cfg(not(no_fp_fmt_parse))]
  58 pub use dec2flt::ParseFloatError;
  59
  60 #[stable(feature = "rust1", since = "1.0.0")]
  61 pub use error::ParseIntError;
  62
  63 #[stable(feature = "nonzero", since = "1.28.0")]
  64 pub use nonzero::{NonZeroU128, NonZeroU16, NonZeroU32, NonZeroU64, NonZeroU8, NonZeroUsize};
  65
  66 #[stable(feature = "signed_nonzero", since = "1.34.0")]
  67 pub use nonzero::{NonZeroI128, NonZeroI16, NonZeroI32, NonZeroI64, NonZeroI8, NonZeroIsize};
  68
  69 #[stable(feature = "try_from", since = "1.34.0")]
  70 pub use error::TryFromIntError;
  71
  72 #[stable(feature = "int_error_matching", since = "1.55.0")]
  73 pub use error::IntErrorKind;
  74
  75 macro_rules! usize_isize_to_xe_bytes_doc {
  76     () => {
  77         "
  78
  79 **Note**: This function returns an array of length 2, 4 or 8 bytes
  80 depending on the target pointer size.
  81
  82 "
  83     };
  84 }
  85
  86 macro_rules! usize_isize_from_xe_bytes_doc {
  87     () => {
  88         "
  89
  90 **Note**: This function takes an array of length 2, 4 or 8 bytes
  91 depending on the target pointer size.
  92
  93 "
  94     };
  95 }
  96
  97 macro_rules! widening_impl {
  98     ($SelfT:ty, $WideT:ty, $BITS:literal, unsigned) => {
  99         /// Calculates the complete product `self * rhs` without the possibility to overflow.
 100         ///
 101         /// This returns the low-order (wrapping) bits and the high-order (overflow) bits
 102         /// of the result as two separate values, in that order.
 103         ///
 104         /// # Examples
 105         ///
 106         /// Basic usage:
 107         ///
 108         /// Please note that this example is shared between integer types.
 109         /// Which explains why `u32` is used here.
 110         ///
 111         /// ```
 112         /// #![feature(bigint_helper_methods)]
 113         /// assert_eq!(5u32.widening_mul(2), (10, 0));
 114         /// assert_eq!(1_000_000_000u32.widening_mul(10), (1410065408, 2));
 115         /// ```
 116         #[unstable(feature = "bigint_helper_methods", issue = "85532")]
 117         #[rustc_const_unstable(feature = "const_bigint_helper_methods", issue = "85532")]
 118         #[must_use = "this returns the result of the operation, \
 119                       without modifying the original"]
 120         #[inline]
 121         pub const fn widening_mul(self, rhs: Self) -> (Self, Self) {
 122             // note: longer-term this should be done via an intrinsic,
 123             //   but for now we can deal without an impl for u128/i128
 124             // SAFETY: overflow will be contained within the wider types
 125             let wide = unsafe { (self as $WideT).unchecked_mul(rhs as $WideT) };
 126             (wide as $SelfT, (wide >> $BITS) as $SelfT)
 127         }
 128
 129         /// Calculates the "full multiplication" `self * rhs + carry`
 130         /// without the possibility to overflow.
 131         ///
 132         /// This returns the low-order (wrapping) bits and the high-order (overflow) bits
 133         /// of the result as two separate values, in that order.
 134         ///
 135         /// Performs "long multiplication" which takes in an extra amount to add, and may return an
 136         /// additional amount of overflow. This allows for chaining together multiple
 137         /// multiplications to create "big integers" which represent larger values.
 138         ///
 139         /// # Examples
 140         ///
 141         /// Basic usage:
 142         ///
 143         /// Please note that this example is shared between integer types.
 144         /// Which explains why `u32` is used here.
 145         ///
 146         /// ```
 147         /// #![feature(bigint_helper_methods)]
 148         /// assert_eq!(5u32.carrying_mul(2, 0), (10, 0));
 149         /// assert_eq!(5u32.carrying_mul(2, 10), (20, 0));
 150         /// assert_eq!(1_000_000_000u32.carrying_mul(10, 0), (1410065408, 2));
 151         /// assert_eq!(1_000_000_000u32.carrying_mul(10, 10), (1410065418, 2));
 152         #[doc = concat!("assert_eq!(",
 153             stringify!($SelfT), "::MAX.carrying_mul(", stringify!($SelfT), "::MAX, ", stringify!($SelfT), "::MAX), ",
 154             "(0, ", stringify!($SelfT), "::MAX));"
 155         )]
 156         /// ```
 157         ///
 158         /// If `carry` is zero, this is similar to [`overflowing_mul`](Self::overflowing_mul),
 159         /// except that it gives the value of the overflow instead of just whether one happened:
 160         ///
 161         /// ```
 162         /// #![feature(bigint_helper_methods)]
 163         /// let r = u8::carrying_mul(7, 13, 0);
 164         /// assert_eq!((r.0, r.1 != 0), u8::overflowing_mul(7, 13));
 165         /// let r = u8::carrying_mul(13, 42, 0);
 166         /// assert_eq!((r.0, r.1 != 0), u8::overflowing_mul(13, 42));
 167         /// ```
 168         ///
 169         /// The value of the first field in the returned tuple matches what you'd get
 170         /// by combining the [`wrapping_mul`](Self::wrapping_mul) and
 171         /// [`wrapping_add`](Self::wrapping_add) methods:
 172         ///
 173         /// ```
 174         /// #![feature(bigint_helper_methods)]
 175         /// assert_eq!(
 176         ///     789_u16.carrying_mul(456, 123).0,
 177         ///     789_u16.wrapping_mul(456).wrapping_add(123),
 178         /// );
 179         /// ```
 180         #[unstable(feature = "bigint_helper_methods", issue = "85532")]
 181         #[rustc_const_unstable(feature = "bigint_helper_methods", issue = "85532")]
 182         #[must_use = "this returns the result of the operation, \
 183                       without modifying the original"]
 184         #[inline]
 185         pub const fn carrying_mul(self, rhs: Self, carry: Self) -> (Self, Self) {
 186             // note: longer-term this should be done via an intrinsic,
 187             //   but for now we can deal without an impl for u128/i128
 188             // SAFETY: overflow will be contained within the wider types
 189             let wide = unsafe {
 190                 (self as $WideT).unchecked_mul(rhs as $WideT).unchecked_add(carry as $WideT)
 191             };
 192             (wide as $SelfT, (wide >> $BITS) as $SelfT)
 193         }
 194     };
 195 }
 196
 197 impl i8 {
 198     int_impl! { i8, i8, u8, 8, 7, -128, 127, 2, "-0x7e", "0xa", "0x12", "0x12", "0x48",
 199     "[0x12]", "[0x12]", "", "", "" }
 200 }
 201
 202 impl i16 {
 203     int_impl! { i16, i16, u16, 16, 15, -32768, 32767, 4, "-0x5ffd", "0x3a", "0x1234", "0x3412",
 204     "0x2c48", "[0x34, 0x12]", "[0x12, 0x34]", "", "", "" }
 205 }
 206
 207 impl i32 {
 208     int_impl! { i32, i32, u32, 32, 31, -2147483648, 2147483647, 8, "0x10000b3", "0xb301",
 209     "0x12345678", "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]",
 210     "[0x12, 0x34, 0x56, 0x78]", "", "", "" }
 211 }
 212
 213 impl i64 {
 214     int_impl! { i64, i64, u64, 64, 63, -9223372036854775808, 9223372036854775807, 12,
 215     "0xaa00000000006e1", "0x6e10aa", "0x1234567890123456", "0x5634129078563412",
 216     "0x6a2c48091e6a2c48", "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
 217     "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]", "", "", "" }
 218 }
 219
 220 impl i128 {
 221     int_impl! { i128, i128, u128, 128, 127, -170141183460469231731687303715884105728,
 222     170141183460469231731687303715884105727, 16,
 223     "0x13f40000000000000000000000004f76", "0x4f7613f4", "0x12345678901234567890123456789012",
 224     "0x12907856341290785634129078563412", "0x48091e6a2c48091e6a2c48091e6a2c48",
 225     "[0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, \
 226       0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
 227     "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56, \
 228       0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12]", "", "", "" }
 229 }
 230
 231 #[cfg(target_pointer_width = "16")]
 232 impl isize {
 233     int_impl! { isize, i16, usize, 16, 15, -32768, 32767, 4, "-0x5ffd", "0x3a", "0x1234",
 234     "0x3412", "0x2c48", "[0x34, 0x12]", "[0x12, 0x34]",
 235     usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!(),
 236     " on 16-bit targets" }
 237 }
 238
 239 #[cfg(target_pointer_width = "32")]
 240 impl isize {
 241     int_impl! { isize, i32, usize, 32, 31, -2147483648, 2147483647, 8, "0x10000b3", "0xb301",
 242     "0x12345678", "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]",
 243     "[0x12, 0x34, 0x56, 0x78]",
 244     usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!(),
 245     " on 32-bit targets" }
 246 }
 247
 248 #[cfg(target_pointer_width = "64")]
 249 impl isize {
 250     int_impl! { isize, i64, usize, 64, 63, -9223372036854775808, 9223372036854775807,
 251     12, "0xaa00000000006e1", "0x6e10aa",  "0x1234567890123456", "0x5634129078563412",
 252     "0x6a2c48091e6a2c48", "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
 253     "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
 254     usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!(),
 255     " on 64-bit targets" }
 256 }
 257
 258 /// If 6th bit set ascii is upper case.
 259 const ASCII_CASE_MASK: u8 = 0b0010_0000;
 260
 261 impl u8 {
 262     uint_impl! { u8, u8, i8, NonZeroU8, 8, 255, 2, "0x82", "0xa", "0x12", "0x12", "0x48", "[0x12]",
 263     "[0x12]", "", "", "" }
 264     widening_impl! { u8, u16, 8, unsigned }
 265
 266     /// Checks if the value is within the ASCII range.
 267     ///
 268     /// # Examples
 269     ///
 270     /// ```
 271     /// let ascii = 97u8;
 272     /// let non_ascii = 150u8;
 273     ///
 274     /// assert!(ascii.is_ascii());
 275     /// assert!(!non_ascii.is_ascii());
 276     /// ```
 277     #[must_use]
 278     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
 279     #[rustc_const_stable(feature = "const_u8_is_ascii", since = "1.43.0")]
 280     #[inline]
 281     pub const fn is_ascii(&self) -> bool {
 282         *self & 128 == 0
 283     }
 284
 285     /// Makes a copy of the value in its ASCII upper case equivalent.
 286     ///
 287     /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
 288     /// but non-ASCII letters are unchanged.
 289     ///
 290     /// To uppercase the value in-place, use [`make_ascii_uppercase`].
 291     ///
 292     /// # Examples
 293     ///
 294     /// ```
 295     /// let lowercase_a = 97u8;
 296     ///
 297     /// assert_eq!(65, lowercase_a.to_ascii_uppercase());
 298     /// ```
 299     ///
 300     /// [`make_ascii_uppercase`]: Self::make_ascii_uppercase
 301     #[must_use = "to uppercase the value in-place, use `make_ascii_uppercase()`"]
 302     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
 303     #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")]
 304     #[inline]
 305     pub const fn to_ascii_uppercase(&self) -> u8 {
 306         // Toggle the fifth bit if this is a lowercase letter
 307         *self ^ ((self.is_ascii_lowercase() as u8) * ASCII_CASE_MASK)
 308     }
 309
 310     /// Makes a copy of the value in its ASCII lower case equivalent.
 311     ///
 312     /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
 313     /// but non-ASCII letters are unchanged.
 314     ///
 315     /// To lowercase the value in-place, use [`make_ascii_lowercase`].
 316     ///
 317     /// # Examples
 318     ///
 319     /// ```
 320     /// let uppercase_a = 65u8;
 321     ///
 322     /// assert_eq!(97, uppercase_a.to_ascii_lowercase());
 323     /// ```
 324     ///
 325     /// [`make_ascii_lowercase`]: Self::make_ascii_lowercase
 326     #[must_use = "to lowercase the value in-place, use `make_ascii_lowercase()`"]
 327     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
 328     #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")]
 329     #[inline]
 330     pub const fn to_ascii_lowercase(&self) -> u8 {
 331         // Set the fifth bit if this is an uppercase letter
 332         *self | (self.is_ascii_uppercase() as u8 * ASCII_CASE_MASK)
 333     }
 334
 335     /// Assumes self is ascii
 336     #[inline]
 337     pub(crate) const fn ascii_change_case_unchecked(&self) -> u8 {
 338         *self ^ ASCII_CASE_MASK
 339     }
 340
 341     /// Checks that two values are an ASCII case-insensitive match.
 342     ///
 343     /// This is equivalent to `to_ascii_lowercase(a) == to_ascii_lowercase(b)`.
 344     ///
 345     /// # Examples
 346     ///
 347     /// ```
 348     /// let lowercase_a = 97u8;
 349     /// let uppercase_a = 65u8;
 350     ///
 351     /// assert!(lowercase_a.eq_ignore_ascii_case(&uppercase_a));
 352     /// ```
 353     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
 354     #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")]
 355     #[inline]
 356     pub const fn eq_ignore_ascii_case(&self, other: &u8) -> bool {
 357         self.to_ascii_lowercase() == other.to_ascii_lowercase()
 358     }
 359
 360     /// Converts this value to its ASCII upper case equivalent in-place.
 361     ///
 362     /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
 363     /// but non-ASCII letters are unchanged.
 364     ///
 365     /// To return a new uppercased value without modifying the existing one, use
 366     /// [`to_ascii_uppercase`].
 367     ///
 368     /// # Examples
 369     ///
 370     /// ```
 371     /// let mut byte = b'a';
 372     ///
 373     /// byte.make_ascii_uppercase();
 374     ///
 375     /// assert_eq!(b'A', byte);
 376     /// ```
 377     ///
 378     /// [`to_ascii_uppercase`]: Self::to_ascii_uppercase
 379     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
 380     #[inline]
 381     pub fn make_ascii_uppercase(&mut self) {
 382         *self = self.to_ascii_uppercase();
 383     }
 384
 385     /// Converts this value to its ASCII lower case equivalent in-place.
 386     ///
 387     /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
 388     /// but non-ASCII letters are unchanged.
 389     ///
 390     /// To return a new lowercased value without modifying the existing one, use
 391     /// [`to_ascii_lowercase`].
 392     ///
 393     /// # Examples
 394     ///
 395     /// ```
 396     /// let mut byte = b'A';
 397     ///
 398     /// byte.make_ascii_lowercase();
 399     ///
 400     /// assert_eq!(b'a', byte);
 401     /// ```
 402     ///
 403     /// [`to_ascii_lowercase`]: Self::to_ascii_lowercase
 404     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
 405     #[inline]
 406     pub fn make_ascii_lowercase(&mut self) {
 407         *self = self.to_ascii_lowercase();
 408     }
 409
 410     /// Checks if the value is an ASCII alphabetic character:
 411     ///
 412     /// - U+0041 'A' ..= U+005A 'Z', or
 413     /// - U+0061 'a' ..= U+007A 'z'.
 414     ///
 415     /// # Examples
 416     ///
 417     /// ```
 418     /// let uppercase_a = b'A';
 419     /// let uppercase_g = b'G';
 420     /// let a = b'a';
 421     /// let g = b'g';
 422     /// let zero = b'0';
 423     /// let percent = b'%';
 424     /// let space = b' ';
 425     /// let lf = b'\n';
 426     /// let esc = b'\x1b';
 427     ///
 428     /// assert!(uppercase_a.is_ascii_alphabetic());
 429     /// assert!(uppercase_g.is_ascii_alphabetic());
 430     /// assert!(a.is_ascii_alphabetic());
 431     /// assert!(g.is_ascii_alphabetic());
 432     /// assert!(!zero.is_ascii_alphabetic());
 433     /// assert!(!percent.is_ascii_alphabetic());
 434     /// assert!(!space.is_ascii_alphabetic());
 435     /// assert!(!lf.is_ascii_alphabetic());
 436     /// assert!(!esc.is_ascii_alphabetic());
 437     /// ```
 438     #[must_use]
 439     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
 440     #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
 441     #[inline]
 442     pub const fn is_ascii_alphabetic(&self) -> bool {
 443         matches!(*self, b'A'..=b'Z' | b'a'..=b'z')
 444     }
 445
 446     /// Checks if the value is an ASCII uppercase character:
 447     /// U+0041 'A' ..= U+005A 'Z'.
 448     ///
 449     /// # Examples
 450     ///
 451     /// ```
 452     /// let uppercase_a = b'A';
 453     /// let uppercase_g = b'G';
 454     /// let a = b'a';
 455     /// let g = b'g';
 456     /// let zero = b'0';
 457     /// let percent = b'%';
 458     /// let space = b' ';
 459     /// let lf = b'\n';
 460     /// let esc = b'\x1b';
 461     ///
 462     /// assert!(uppercase_a.is_ascii_uppercase());
 463     /// assert!(uppercase_g.is_ascii_uppercase());
 464     /// assert!(!a.is_ascii_uppercase());
 465     /// assert!(!g.is_ascii_uppercase());
 466     /// assert!(!zero.is_ascii_uppercase());
 467     /// assert!(!percent.is_ascii_uppercase());
 468     /// assert!(!space.is_ascii_uppercase());
 469     /// assert!(!lf.is_ascii_uppercase());
 470     /// assert!(!esc.is_ascii_uppercase());
 471     /// ```
 472     #[must_use]
 473     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
 474     #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
 475     #[inline]
 476     pub const fn is_ascii_uppercase(&self) -> bool {
 477         matches!(*self, b'A'..=b'Z')
 478     }
 479
 480     /// Checks if the value is an ASCII lowercase character:
 481     /// U+0061 'a' ..= U+007A 'z'.
 482     ///
 483     /// # Examples
 484     ///
 485     /// ```
 486     /// let uppercase_a = b'A';
 487     /// let uppercase_g = b'G';
 488     /// let a = b'a';
 489     /// let g = b'g';
 490     /// let zero = b'0';
 491     /// let percent = b'%';
 492     /// let space = b' ';
 493     /// let lf = b'\n';
 494     /// let esc = b'\x1b';
 495     ///
 496     /// assert!(!uppercase_a.is_ascii_lowercase());
 497     /// assert!(!uppercase_g.is_ascii_lowercase());
 498     /// assert!(a.is_ascii_lowercase());
 499     /// assert!(g.is_ascii_lowercase());
 500     /// assert!(!zero.is_ascii_lowercase());
 501     /// assert!(!percent.is_ascii_lowercase());
 502     /// assert!(!space.is_ascii_lowercase());
 503     /// assert!(!lf.is_ascii_lowercase());
 504     /// assert!(!esc.is_ascii_lowercase());
 505     /// ```
 506     #[must_use]
 507     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
 508     #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
 509     #[inline]
 510     pub const fn is_ascii_lowercase(&self) -> bool {
 511         matches!(*self, b'a'..=b'z')
 512     }
 513
 514     /// Checks if the value is an ASCII alphanumeric character:
 515     ///
 516     /// - U+0041 'A' ..= U+005A 'Z', or
 517     /// - U+0061 'a' ..= U+007A 'z', or
 518     /// - U+0030 '0' ..= U+0039 '9'.
 519     ///
 520     /// # Examples
 521     ///
 522     /// ```
 523     /// let uppercase_a = b'A';
 524     /// let uppercase_g = b'G';
 525     /// let a = b'a';
 526     /// let g = b'g';
 527     /// let zero = b'0';
 528     /// let percent = b'%';
 529     /// let space = b' ';
 530     /// let lf = b'\n';
 531     /// let esc = b'\x1b';
 532     ///
 533     /// assert!(uppercase_a.is_ascii_alphanumeric());
 534     /// assert!(uppercase_g.is_ascii_alphanumeric());
 535     /// assert!(a.is_ascii_alphanumeric());
 536     /// assert!(g.is_ascii_alphanumeric());
 537     /// assert!(zero.is_ascii_alphanumeric());
 538     /// assert!(!percent.is_ascii_alphanumeric());
 539     /// assert!(!space.is_ascii_alphanumeric());
 540     /// assert!(!lf.is_ascii_alphanumeric());
 541     /// assert!(!esc.is_ascii_alphanumeric());
 542     /// ```
 543     #[must_use]
 544     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
 545     #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
 546     #[inline]
 547     pub const fn is_ascii_alphanumeric(&self) -> bool {
 548         matches!(*self, b'0'..=b'9' | b'A'..=b'Z' | b'a'..=b'z')
 549     }
 550
 551     /// Checks if the value is an ASCII decimal digit:
 552     /// U+0030 '0' ..= U+0039 '9'.
 553     ///
 554     /// # Examples
 555     ///
 556     /// ```
 557     /// let uppercase_a = b'A';
 558     /// let uppercase_g = b'G';
 559     /// let a = b'a';
 560     /// let g = b'g';
 561     /// let zero = b'0';
 562     /// let percent = b'%';
 563     /// let space = b' ';
 564     /// let lf = b'\n';
 565     /// let esc = b'\x1b';
 566     ///
 567     /// assert!(!uppercase_a.is_ascii_digit());
 568     /// assert!(!uppercase_g.is_ascii_digit());
 569     /// assert!(!a.is_ascii_digit());
 570     /// assert!(!g.is_ascii_digit());
 571     /// assert!(zero.is_ascii_digit());
 572     /// assert!(!percent.is_ascii_digit());
 573     /// assert!(!space.is_ascii_digit());
 574     /// assert!(!lf.is_ascii_digit());
 575     /// assert!(!esc.is_ascii_digit());
 576     /// ```
 577     #[must_use]
 578     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
 579     #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
 580     #[inline]
 581     pub const fn is_ascii_digit(&self) -> bool {
 582         matches!(*self, b'0'..=b'9')
 583     }
 584
 585     /// Checks if the value is an ASCII hexadecimal digit:
 586     ///
 587     /// - U+0030 '0' ..= U+0039 '9', or
 588     /// - U+0041 'A' ..= U+0046 'F', or
 589     /// - U+0061 'a' ..= U+0066 'f'.
 590     ///
 591     /// # Examples
 592     ///
 593     /// ```
 594     /// let uppercase_a = b'A';
 595     /// let uppercase_g = b'G';
 596     /// let a = b'a';
 597     /// let g = b'g';
 598     /// let zero = b'0';
 599     /// let percent = b'%';
 600     /// let space = b' ';
 601     /// let lf = b'\n';
 602     /// let esc = b'\x1b';
 603     ///
 604     /// assert!(uppercase_a.is_ascii_hexdigit());
 605     /// assert!(!uppercase_g.is_ascii_hexdigit());
 606     /// assert!(a.is_ascii_hexdigit());
 607     /// assert!(!g.is_ascii_hexdigit());
 608     /// assert!(zero.is_ascii_hexdigit());
 609     /// assert!(!percent.is_ascii_hexdigit());
 610     /// assert!(!space.is_ascii_hexdigit());
 611     /// assert!(!lf.is_ascii_hexdigit());
 612     /// assert!(!esc.is_ascii_hexdigit());
 613     /// ```
 614     #[must_use]
 615     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
 616     #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
 617     #[inline]
 618     pub const fn is_ascii_hexdigit(&self) -> bool {
 619         matches!(*self, b'0'..=b'9' | b'A'..=b'F' | b'a'..=b'f')
 620     }
 621
 622     /// Checks if the value is an ASCII punctuation character:
 623     ///
 624     /// - U+0021 ..= U+002F `! " # $ % & ' ( ) * + , - . /`, or
 625     /// - U+003A ..= U+0040 `: ; < = > ? @`, or
 626     /// - U+005B ..= U+0060 ``[ \ ] ^ _ ` ``, or
 627     /// - U+007B ..= U+007E `{ | } ~`
 628     ///
 629     /// # Examples
 630     ///
 631     /// ```
 632     /// let uppercase_a = b'A';
 633     /// let uppercase_g = b'G';
 634     /// let a = b'a';
 635     /// let g = b'g';
 636     /// let zero = b'0';
 637     /// let percent = b'%';
 638     /// let space = b' ';
 639     /// let lf = b'\n';
 640     /// let esc = b'\x1b';
 641     ///
 642     /// assert!(!uppercase_a.is_ascii_punctuation());
 643     /// assert!(!uppercase_g.is_ascii_punctuation());
 644     /// assert!(!a.is_ascii_punctuation());
 645     /// assert!(!g.is_ascii_punctuation());
 646     /// assert!(!zero.is_ascii_punctuation());
 647     /// assert!(percent.is_ascii_punctuation());
 648     /// assert!(!space.is_ascii_punctuation());
 649     /// assert!(!lf.is_ascii_punctuation());
 650     /// assert!(!esc.is_ascii_punctuation());
 651     /// ```
 652     #[must_use]
 653     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
 654     #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
 655     #[inline]
 656     pub const fn is_ascii_punctuation(&self) -> bool {
 657         matches!(*self, b'!'..=b'/' | b':'..=b'@' | b'['..=b'`' | b'{'..=b'~')
 658     }
 659
 660     /// Checks if the value is an ASCII graphic character:
 661     /// U+0021 '!' ..= U+007E '~'.
 662     ///
 663     /// # Examples
 664     ///
 665     /// ```
 666     /// let uppercase_a = b'A';
 667     /// let uppercase_g = b'G';
 668     /// let a = b'a';
 669     /// let g = b'g';
 670     /// let zero = b'0';
 671     /// let percent = b'%';
 672     /// let space = b' ';
 673     /// let lf = b'\n';
 674     /// let esc = b'\x1b';
 675     ///
 676     /// assert!(uppercase_a.is_ascii_graphic());
 677     /// assert!(uppercase_g.is_ascii_graphic());
 678     /// assert!(a.is_ascii_graphic());
 679     /// assert!(g.is_ascii_graphic());
 680     /// assert!(zero.is_ascii_graphic());
 681     /// assert!(percent.is_ascii_graphic());
 682     /// assert!(!space.is_ascii_graphic());
 683     /// assert!(!lf.is_ascii_graphic());
 684     /// assert!(!esc.is_ascii_graphic());
 685     /// ```
 686     #[must_use]
 687     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
 688     #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
 689     #[inline]
 690     pub const fn is_ascii_graphic(&self) -> bool {
 691         matches!(*self, b'!'..=b'~')
 692     }
 693
 694     /// Checks if the value is an ASCII whitespace character:
 695     /// U+0020 SPACE, U+0009 HORIZONTAL TAB, U+000A LINE FEED,
 696     /// U+000C FORM FEED, or U+000D CARRIAGE RETURN.
 697     ///
 698     /// Rust uses the WhatWG Infra Standard's [definition of ASCII
 699     /// whitespace][infra-aw]. There are several other definitions in
 700     /// wide use. For instance, [the POSIX locale][pct] includes
 701     /// U+000B VERTICAL TAB as well as all the above characters,
 702     /// but—from the very same specification—[the default rule for
 703     /// "field splitting" in the Bourne shell][bfs] considers *only*
 704     /// SPACE, HORIZONTAL TAB, and LINE FEED as whitespace.
 705     ///
 706     /// If you are writing a program that will process an existing
 707     /// file format, check what that format's definition of whitespace is
 708     /// before using this function.
 709     ///
 710     /// [infra-aw]: https://infra.spec.whatwg.org/#ascii-whitespace
 711     /// [pct]: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html#tag_07_03_01
 712     /// [bfs]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_05
 713     ///
 714     /// # Examples
 715     ///
 716     /// ```
 717     /// let uppercase_a = b'A';
 718     /// let uppercase_g = b'G';
 719     /// let a = b'a';
 720     /// let g = b'g';
 721     /// let zero = b'0';
 722     /// let percent = b'%';
 723     /// let space = b' ';
 724     /// let lf = b'\n';
 725     /// let esc = b'\x1b';
 726     ///
 727     /// assert!(!uppercase_a.is_ascii_whitespace());
 728     /// assert!(!uppercase_g.is_ascii_whitespace());
 729     /// assert!(!a.is_ascii_whitespace());
 730     /// assert!(!g.is_ascii_whitespace());
 731     /// assert!(!zero.is_ascii_whitespace());
 732     /// assert!(!percent.is_ascii_whitespace());
 733     /// assert!(space.is_ascii_whitespace());
 734     /// assert!(lf.is_ascii_whitespace());
 735     /// assert!(!esc.is_ascii_whitespace());
 736     /// ```
 737     #[must_use]
 738     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
 739     #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
 740     #[inline]
 741     pub const fn is_ascii_whitespace(&self) -> bool {
 742         matches!(*self, b'\t' | b'\n' | b'\x0C' | b'\r' | b' ')
 743     }
 744
 745     /// Checks if the value is an ASCII control character:
 746     /// U+0000 NUL ..= U+001F UNIT SEPARATOR, or U+007F DELETE.
 747     /// Note that most ASCII whitespace characters are control
 748     /// characters, but SPACE is not.
 749     ///
 750     /// # Examples
 751     ///
 752     /// ```
 753     /// let uppercase_a = b'A';
 754     /// let uppercase_g = b'G';
 755     /// let a = b'a';
 756     /// let g = b'g';
 757     /// let zero = b'0';
 758     /// let percent = b'%';
 759     /// let space = b' ';
 760     /// let lf = b'\n';
 761     /// let esc = b'\x1b';
 762     ///
 763     /// assert!(!uppercase_a.is_ascii_control());
 764     /// assert!(!uppercase_g.is_ascii_control());
 765     /// assert!(!a.is_ascii_control());
 766     /// assert!(!g.is_ascii_control());
 767     /// assert!(!zero.is_ascii_control());
 768     /// assert!(!percent.is_ascii_control());
 769     /// assert!(!space.is_ascii_control());
 770     /// assert!(lf.is_ascii_control());
 771     /// assert!(esc.is_ascii_control());
 772     /// ```
 773     #[must_use]
 774     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
 775     #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
 776     #[inline]
 777     pub const fn is_ascii_control(&self) -> bool {
 778         matches!(*self, b'\0'..=b'\x1F' | b'\x7F')
 779     }
 780
 781     /// Returns an iterator that produces an escaped version of a `u8`,
 782     /// treating it as an ASCII character.
 783     ///
 784     /// The behavior is identical to [`ascii::escape_default`].
 785     ///
 786     /// # Examples
 787     ///
 788     /// ```
 789     ///
 790     /// assert_eq!("0", b'0'.escape_ascii().to_string());
 791     /// assert_eq!("\\t", b'\t'.escape_ascii().to_string());
 792     /// assert_eq!("\\r", b'\r'.escape_ascii().to_string());
 793     /// assert_eq!("\\n", b'\n'.escape_ascii().to_string());
 794     /// assert_eq!("\\'", b'\''.escape_ascii().to_string());
 795     /// assert_eq!("\\\"", b'"'.escape_ascii().to_string());
 796     /// assert_eq!("\\\\", b'\\'.escape_ascii().to_string());
 797     /// assert_eq!("\\x9d", b'\x9d'.escape_ascii().to_string());
 798     /// ```
 799     #[must_use = "this returns the escaped byte as an iterator, \
 800                   without modifying the original"]
 801     #[stable(feature = "inherent_ascii_escape", since = "1.60.0")]
 802     #[inline]
 803     pub fn escape_ascii(self) -> ascii::EscapeDefault {
 804         ascii::escape_default(self)
 805     }
 806
 807     #[inline]
 808     pub(crate) const fn is_utf8_char_boundary(self) -> bool {
 809         // This is bit magic equivalent to: b < 128 || b >= 192
 810         (self as i8) >= -0x40
 811     }
 812 }
 813
 814 impl u16 {
 815     uint_impl! { u16, u16, i16, NonZeroU16, 16, 65535, 4, "0xa003", "0x3a", "0x1234", "0x3412", "0x2c48",
 816     "[0x34, 0x12]", "[0x12, 0x34]", "", "", "" }
 817     widening_impl! { u16, u32, 16, unsigned }
 818
 819     /// Checks if the value is a Unicode surrogate code point, which are disallowed values for [`char`].
 820     ///
 821     /// # Examples
 822     ///
 823     /// ```
 824     /// #![feature(utf16_extra)]
 825     ///
 826     /// let low_non_surrogate = 0xA000u16;
 827     /// let low_surrogate = 0xD800u16;
 828     /// let high_surrogate = 0xDC00u16;
 829     /// let high_non_surrogate = 0xE000u16;
 830     ///
 831     /// assert!(!low_non_surrogate.is_utf16_surrogate());
 832     /// assert!(low_surrogate.is_utf16_surrogate());
 833     /// assert!(high_surrogate.is_utf16_surrogate());
 834     /// assert!(!high_non_surrogate.is_utf16_surrogate());
 835     /// ```
 836     #[must_use]
 837     #[unstable(feature = "utf16_extra", issue = "94919")]
 838     #[rustc_const_unstable(feature = "utf16_extra_const", issue = "94919")]
 839     #[inline]
 840     pub const fn is_utf16_surrogate(self) -> bool {
 841         matches!(self, 0xD800..=0xDFFF)
 842     }
 843 }
 844
 845 impl u32 {
 846     uint_impl! { u32, u32, i32, NonZeroU32, 32, 4294967295, 8, "0x10000b3", "0xb301", "0x12345678",
 847     "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]", "[0x12, 0x34, 0x56, 0x78]", "", "", "" }
 848     widening_impl! { u32, u64, 32, unsigned }
 849 }
 850
 851 impl u64 {
 852     uint_impl! { u64, u64, i64, NonZeroU64, 64, 18446744073709551615, 12, "0xaa00000000006e1", "0x6e10aa",
 853     "0x1234567890123456", "0x5634129078563412", "0x6a2c48091e6a2c48",
 854     "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
 855     "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
 856     "", "", ""}
 857     widening_impl! { u64, u128, 64, unsigned }
 858 }
 859
 860 impl u128 {
 861     uint_impl! { u128, u128, i128, NonZeroU128, 128, 340282366920938463463374607431768211455, 16,
 862     "0x13f40000000000000000000000004f76", "0x4f7613f4", "0x12345678901234567890123456789012",
 863     "0x12907856341290785634129078563412", "0x48091e6a2c48091e6a2c48091e6a2c48",
 864     "[0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, \
 865       0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
 866     "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56, \
 867       0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12]",
 868      "", "", ""}
 869 }
 870
 871 #[cfg(target_pointer_width = "16")]
 872 impl usize {
 873     uint_impl! { usize, u16, isize, NonZeroUsize, 16, 65535, 4, "0xa003", "0x3a", "0x1234", "0x3412", "0x2c48",
 874     "[0x34, 0x12]", "[0x12, 0x34]",
 875     usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!(),
 876     " on 16-bit targets" }
 877     widening_impl! { usize, u32, 16, unsigned }
 878 }
 879 #[cfg(target_pointer_width = "32")]
 880 impl usize {
 881     uint_impl! { usize, u32, isize, NonZeroUsize, 32, 4294967295, 8, "0x10000b3", "0xb301", "0x12345678",
 882     "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]", "[0x12, 0x34, 0x56, 0x78]",
 883     usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!(),
 884     " on 32-bit targets" }
 885     widening_impl! { usize, u64, 32, unsigned }
 886 }
 887
 888 #[cfg(target_pointer_width = "64")]
 889 impl usize {
 890     uint_impl! { usize, u64, isize, NonZeroUsize, 64, 18446744073709551615, 12, "0xaa00000000006e1", "0x6e10aa",
 891     "0x1234567890123456", "0x5634129078563412", "0x6a2c48091e6a2c48",
 892     "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
 893     "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
 894     usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!(),
 895     " on 64-bit targets" }
 896     widening_impl! { usize, u128, 64, unsigned }
 897 }
 898
 899 impl usize {
 900     /// Returns an `usize` where every byte is equal to `x`.
 901     #[inline]
 902     pub(crate) const fn repeat_u8(x: u8) -> usize {
 903         usize::from_ne_bytes([x; mem::size_of::<usize>()])
 904     }
 905
 906     /// Returns an `usize` where every byte pair is equal to `x`.
 907     #[inline]
 908     pub(crate) const fn repeat_u16(x: u16) -> usize {
 909         let mut r = 0usize;
 910         let mut i = 0;
 911         while i < mem::size_of::<usize>() {
 912             // Use `wrapping_shl` to make it work on targets with 16-bit `usize`
 913             r = r.wrapping_shl(16) | (x as usize);
 914             i += 2;
 915         }
 916         r
 917     }
 918 }
 919
 920 /// A classification of floating point numbers.
 921 ///
 922 /// This `enum` is used as the return type for [`f32::classify`] and [`f64::classify`]. See
 923 /// their documentation for more.
 924 ///
 925 /// # Examples
 926 ///
 927 /// ```
 928 /// use std::num::FpCategory;
 929 ///
 930 /// let num = 12.4_f32;
 931 /// let inf = f32::INFINITY;
 932 /// let zero = 0f32;
 933 /// let sub: f32 = 1.1754942e-38;
 934 /// let nan = f32::NAN;
 935 ///
 936 /// assert_eq!(num.classify(), FpCategory::Normal);
 937 /// assert_eq!(inf.classify(), FpCategory::Infinite);
 938 /// assert_eq!(zero.classify(), FpCategory::Zero);
 939 /// assert_eq!(sub.classify(), FpCategory::Subnormal);
 940 /// assert_eq!(nan.classify(), FpCategory::Nan);
 941 /// ```
 942 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
 943 #[stable(feature = "rust1", since = "1.0.0")]
 944 pub enum FpCategory {
 945     /// NaN (not a number): this value results from calculations like `(-1.0).sqrt()`.
 946     ///
 947     /// See [the documentation for `f32`](f32) for more information on the unusual properties
 948     /// of NaN.
 949     #[stable(feature = "rust1", since = "1.0.0")]
 950     Nan,
 951
 952     /// Positive or negative infinity, which often results from dividing a nonzero number
 953     /// by zero.
 954     #[stable(feature = "rust1", since = "1.0.0")]
 955     Infinite,
 956
 957     /// Positive or negative zero.
 958     ///
 959     /// See [the documentation for `f32`](f32) for more information on the signedness of zeroes.
 960     #[stable(feature = "rust1", since = "1.0.0")]
 961     Zero,
 962
 963     /// “Subnormal” or “denormal” floating point representation (less precise, relative to
 964     /// their magnitude, than [`Normal`]).
 965     ///
 966     /// Subnormal numbers are larger in magnitude than [`Zero`] but smaller in magnitude than all
 967     /// [`Normal`] numbers.
 968     ///
 969     /// [`Normal`]: Self::Normal
 970     /// [`Zero`]: Self::Zero
 971     #[stable(feature = "rust1", since = "1.0.0")]
 972     Subnormal,
 973
 974     /// A regular floating point number, not any of the exceptional categories.
 975     ///
 976     /// The smallest positive normal numbers are [`f32::MIN_POSITIVE`] and [`f64::MIN_POSITIVE`],
 977     /// and the largest positive normal numbers are [`f32::MAX`] and [`f64::MAX`]. (Unlike signed
 978     /// integers, floating point numbers are symmetric in their range, so negating any of these
 979     /// constants will produce their negative counterpart.)
 980     #[stable(feature = "rust1", since = "1.0.0")]
 981     Normal,
 982 }
 983
 984 #[doc(hidden)]
 985 trait FromStrRadixHelper:
 986     PartialOrd + Copy + Add<Output = Self> + Sub<Output = Self> + Mul<Output = Self>
 987 {
 988     const MIN: Self;
 989     fn from_u32(u: u32) -> Self;
 990     fn checked_mul(&self, other: u32) -> Option<Self>;
 991     fn checked_sub(&self, other: u32) -> Option<Self>;
 992     fn checked_add(&self, other: u32) -> Option<Self>;
 993 }
 994
 995 macro_rules! from_str_radix_int_impl {
 996     ($($t:ty)*) => {$(
 997         #[stable(feature = "rust1", since = "1.0.0")]
 998         impl FromStr for $t {
 999             type Err = ParseIntError;
1000             fn from_str(src: &str) -> Result<Self, ParseIntError> {
1001                 from_str_radix(src, 10)
1002             }
1003         }
1004     )*}
1005 }
1006 from_str_radix_int_impl! { isize i8 i16 i32 i64 i128 usize u8 u16 u32 u64 u128 }
1007
1008 macro_rules! impl_helper_for {
1009     ($($t:ty)*) => ($(impl FromStrRadixHelper for $t {
1010         const MIN: Self = Self::MIN;
1011         #[inline]
1012         fn from_u32(u: u32) -> Self { u as Self }
1013         #[inline]
1014         fn checked_mul(&self, other: u32) -> Option<Self> {
1015             Self::checked_mul(*self, other as Self)
1016         }
1017         #[inline]
1018         fn checked_sub(&self, other: u32) -> Option<Self> {
1019             Self::checked_sub(*self, other as Self)
1020         }
1021         #[inline]
1022         fn checked_add(&self, other: u32) -> Option<Self> {
1023             Self::checked_add(*self, other as Self)
1024         }
1025     })*)
1026 }
1027 impl_helper_for! { i8 i16 i32 i64 i128 isize u8 u16 u32 u64 u128 usize }
1028
1029 /// Determines if a string of text of that length of that radix could be guaranteed to be
1030 /// stored in the given type T.
1031 /// Note that if the radix is known to the compiler, it is just the check of digits.len that
1032 /// is done at runtime.
1033 #[doc(hidden)]
1034 #[inline(always)]
1035 #[unstable(issue = "none", feature = "std_internals")]
1036 pub fn can_not_overflow<T>(radix: u32, is_signed_ty: bool, digits: &[u8]) -> bool {
1037     radix <= 16 && digits.len() <= mem::size_of::<T>() * 2 - is_signed_ty as usize
1038 }
1039
1040 fn from_str_radix<T: FromStrRadixHelper>(src: &str, radix: u32) -> Result<T, ParseIntError> {
1041     use self::IntErrorKind::*;
1042     use self::ParseIntError as PIE;
1043
1044     assert!(
1045         (2..=36).contains(&radix),
1046         "from_str_radix_int: must lie in the range `[2, 36]` - found {}",
1047         radix
1048     );
1049
1050     if src.is_empty() {
1051         return Err(PIE { kind: Empty });
1052     }
1053
1054     let is_signed_ty = T::from_u32(0) > T::MIN;
1055
1056     // all valid digits are ascii, so we will just iterate over the utf8 bytes
1057     // and cast them to chars. .to_digit() will safely return None for anything
1058     // other than a valid ascii digit for the given radix, including the first-byte
1059     // of multi-byte sequences
1060     let src = src.as_bytes();
1061
1062     let (is_positive, digits) = match src[0] {
1063         b'+' | b'-' if src[1..].is_empty() => {
1064             return Err(PIE { kind: InvalidDigit });
1065         }
1066         b'+' => (true, &src[1..]),
1067         b'-' if is_signed_ty => (false, &src[1..]),
1068         _ => (true, src),
1069     };
1070
1071     let mut result = T::from_u32(0);
1072
1073     if can_not_overflow::<T>(radix, is_signed_ty, digits) {
1074         // If the len of the str is short compared to the range of the type
1075         // we are parsing into, then we can be certain that an overflow will not occur.
1076         // This bound is when `radix.pow(digits.len()) - 1 <= T::MAX` but the condition
1077         // above is a faster (conservative) approximation of this.
1078         //
1079         // Consider radix 16 as it has the highest information density per digit and will thus overflow the earliest:
1080         // `u8::MAX` is `ff` - any str of len 2 is guaranteed to not overflow.
1081         // `i8::MAX` is `7f` - only a str of len 1 is guaranteed to not overflow.
1082         macro_rules! run_unchecked_loop {
1083             ($unchecked_additive_op:expr) => {
1084                 for &c in digits {
1085                     result = result * T::from_u32(radix);
1086                     let x = (c as char).to_digit(radix).ok_or(PIE { kind: InvalidDigit })?;
1087                     result = $unchecked_additive_op(result, T::from_u32(x));
1088                 }
1089             };
1090         }
1091         if is_positive {
1092             run_unchecked_loop!(<T as core::ops::Add>::add)
1093         } else {
1094             run_unchecked_loop!(<T as core::ops::Sub>::sub)
1095         };
1096     } else {
1097         macro_rules! run_checked_loop {
1098             ($checked_additive_op:ident, $overflow_err:expr) => {
1099                 for &c in digits {
1100                     // When `radix` is passed in as a literal, rather than doing a slow `imul`
1101                     // the compiler can use shifts if `radix` can be expressed as a
1102                     // sum of powers of 2 (x*10 can be written as x*8 + x*2).
1103                     // When the compiler can't use these optimisations,
1104                     // the latency of the multiplication can be hidden by issuing it
1105                     // before the result is needed to improve performance on
1106                     // modern out-of-order CPU as multiplication here is slower
1107                     // than the other instructions, we can get the end result faster
1108                     // doing multiplication first and let the CPU spends other cycles
1109                     // doing other computation and get multiplication result later.
1110                     let mul = result.checked_mul(radix);
1111                     let x = (c as char).to_digit(radix).ok_or(PIE { kind: InvalidDigit })?;
1112                     result = mul.ok_or_else($overflow_err)?;
1113                     result = T::$checked_additive_op(&result, x).ok_or_else($overflow_err)?;
1114                 }
1115             };
1116         }
1117         if is_positive {
1118             run_checked_loop!(checked_add, || PIE { kind: PosOverflow })
1119         } else {
1120             run_checked_loop!(checked_sub, || PIE { kind: NegOverflow })
1121         };
1122     }
1123     Ok(result)
1124 }