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::str::FromStr;
   9
  10 // Used because the `?` operator is not allowed in a const context.
  11 macro_rules! try_opt {
  12     ($e:expr) => {
  13         match $e {
  14             Some(x) => x,
  15             None => return None,
  16         }
  17     };
  18 }
  19
  20 #[allow_internal_unstable(const_likely)]
  21 macro_rules! unlikely {
  22     ($e: expr) => {
  23         intrinsics::unlikely($e)
  24     };
  25 }
  26
  27 // All these modules are technically private and only exposed for coretests:
  28 pub mod bignum;
  29 pub mod dec2flt;
  30 pub mod diy_float;
  31 pub mod flt2dec;
  32
  33 #[macro_use]
  34 mod int_macros; // import int_impl!
  35 #[macro_use]
  36 mod uint_macros; // import uint_impl!
  37
  38 mod error;
  39 mod nonzero;
  40 mod wrapping;
  41
  42 #[stable(feature = "rust1", since = "1.0.0")]
  43 pub use wrapping::Wrapping;
  44
  45 #[stable(feature = "rust1", since = "1.0.0")]
  46 pub use dec2flt::ParseFloatError;
  47
  48 #[stable(feature = "rust1", since = "1.0.0")]
  49 pub use error::ParseIntError;
  50
  51 #[stable(feature = "nonzero", since = "1.28.0")]
  52 pub use nonzero::{NonZeroU128, NonZeroU16, NonZeroU32, NonZeroU64, NonZeroU8, NonZeroUsize};
  53
  54 #[stable(feature = "signed_nonzero", since = "1.34.0")]
  55 pub use nonzero::{NonZeroI128, NonZeroI16, NonZeroI32, NonZeroI64, NonZeroI8, NonZeroIsize};
  56
  57 #[stable(feature = "try_from", since = "1.34.0")]
  58 pub use error::TryFromIntError;
  59
  60 #[unstable(
  61     feature = "int_error_matching",
  62     reason = "it can be useful to match errors when making error messages \
  63               for integer parsing",
  64     issue = "22639"
  65 )]
  66 pub use error::IntErrorKind;
  67
  68 macro_rules! usize_isize_to_xe_bytes_doc {
  69     () => {
  70         "
  71
  72 **Note**: This function returns an array of length 2, 4 or 8 bytes
  73 depending on the target pointer size.
  74
  75 "
  76     };
  77 }
  78
  79 macro_rules! usize_isize_from_xe_bytes_doc {
  80     () => {
  81         "
  82
  83 **Note**: This function takes an array of length 2, 4 or 8 bytes
  84 depending on the target pointer size.
  85
  86 "
  87     };
  88 }
  89
  90 #[lang = "i8"]
  91 impl i8 {
  92     int_impl! { i8, i8, u8, 8, -128, 127, 2, "-0x7e", "0xa", "0x12", "0x12", "0x48",
  93     "[0x12]", "[0x12]", "", "" }
  94 }
  95
  96 #[lang = "i16"]
  97 impl i16 {
  98     int_impl! { i16, i16, u16, 16, -32768, 32767, 4, "-0x5ffd", "0x3a", "0x1234", "0x3412",
  99     "0x2c48", "[0x34, 0x12]", "[0x12, 0x34]", "", "" }
 100 }
 101
 102 #[lang = "i32"]
 103 impl i32 {
 104     int_impl! { i32, i32, u32, 32, -2147483648, 2147483647, 8, "0x10000b3", "0xb301",
 105     "0x12345678", "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]",
 106     "[0x12, 0x34, 0x56, 0x78]", "", "" }
 107 }
 108
 109 #[lang = "i64"]
 110 impl i64 {
 111     int_impl! { i64, i64, u64, 64, -9223372036854775808, 9223372036854775807, 12,
 112     "0xaa00000000006e1", "0x6e10aa", "0x1234567890123456", "0x5634129078563412",
 113     "0x6a2c48091e6a2c48", "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
 114     "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]", "", "" }
 115 }
 116
 117 #[lang = "i128"]
 118 impl i128 {
 119     int_impl! { i128, i128, u128, 128, -170141183460469231731687303715884105728,
 120     170141183460469231731687303715884105727, 16,
 121     "0x13f40000000000000000000000004f76", "0x4f7613f4", "0x12345678901234567890123456789012",
 122     "0x12907856341290785634129078563412", "0x48091e6a2c48091e6a2c48091e6a2c48",
 123     "[0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, \
 124       0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
 125     "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56, \
 126       0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12]", "", "" }
 127 }
 128
 129 #[cfg(target_pointer_width = "16")]
 130 #[lang = "isize"]
 131 impl isize {
 132     int_impl! { isize, i16, usize, 16, -32768, 32767, 4, "-0x5ffd", "0x3a", "0x1234",
 133     "0x3412", "0x2c48", "[0x34, 0x12]", "[0x12, 0x34]",
 134     usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
 135 }
 136
 137 #[cfg(target_pointer_width = "32")]
 138 #[lang = "isize"]
 139 impl isize {
 140     int_impl! { isize, i32, usize, 32, -2147483648, 2147483647, 8, "0x10000b3", "0xb301",
 141     "0x12345678", "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]",
 142     "[0x12, 0x34, 0x56, 0x78]",
 143     usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
 144 }
 145
 146 #[cfg(target_pointer_width = "64")]
 147 #[lang = "isize"]
 148 impl isize {
 149     int_impl! { isize, i64, usize, 64, -9223372036854775808, 9223372036854775807,
 150     12, "0xaa00000000006e1", "0x6e10aa",  "0x1234567890123456", "0x5634129078563412",
 151      "0x6a2c48091e6a2c48", "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
 152      "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
 153      usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
 154 }
 155
 156 /// If 6th bit set ascii is upper case.
 157 const ASCII_CASE_MASK: u8 = 0b0010_0000;
 158
 159 #[lang = "u8"]
 160 impl u8 {
 161     uint_impl! { u8, u8, 8, 255, 2, "0x82", "0xa", "0x12", "0x12", "0x48", "[0x12]",
 162     "[0x12]", "", "" }
 163
 164     /// Checks if the value is within the ASCII range.
 165     ///
 166     /// # Examples
 167     ///
 168     /// ```
 169     /// let ascii = 97u8;
 170     /// let non_ascii = 150u8;
 171     ///
 172     /// assert!(ascii.is_ascii());
 173     /// assert!(!non_ascii.is_ascii());
 174     /// ```
 175     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
 176     #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.43.0")]
 177     #[inline]
 178     pub const fn is_ascii(&self) -> bool {
 179         *self & 128 == 0
 180     }
 181
 182     /// Makes a copy of the value in its ASCII upper case equivalent.
 183     ///
 184     /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
 185     /// but non-ASCII letters are unchanged.
 186     ///
 187     /// To uppercase the value in-place, use [`make_ascii_uppercase`].
 188     ///
 189     /// # Examples
 190     ///
 191     /// ```
 192     /// let lowercase_a = 97u8;
 193     ///
 194     /// assert_eq!(65, lowercase_a.to_ascii_uppercase());
 195     /// ```
 196     ///
 197     /// [`make_ascii_uppercase`]: Self::make_ascii_uppercase
 198     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
 199     #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")]
 200     #[inline]
 201     pub const fn to_ascii_uppercase(&self) -> u8 {
 202         // Unset the fifth bit if this is a lowercase letter
 203         *self & !((self.is_ascii_lowercase() as u8) * ASCII_CASE_MASK)
 204     }
 205
 206     /// Makes a copy of the value in its ASCII lower case equivalent.
 207     ///
 208     /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
 209     /// but non-ASCII letters are unchanged.
 210     ///
 211     /// To lowercase the value in-place, use [`make_ascii_lowercase`].
 212     ///
 213     /// # Examples
 214     ///
 215     /// ```
 216     /// let uppercase_a = 65u8;
 217     ///
 218     /// assert_eq!(97, uppercase_a.to_ascii_lowercase());
 219     /// ```
 220     ///
 221     /// [`make_ascii_lowercase`]: Self::make_ascii_lowercase
 222     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
 223     #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")]
 224     #[inline]
 225     pub const fn to_ascii_lowercase(&self) -> u8 {
 226         // Set the fifth bit if this is an uppercase letter
 227         *self | (self.is_ascii_uppercase() as u8 * ASCII_CASE_MASK)
 228     }
 229
 230     /// Assumes self is ascii
 231     #[inline]
 232     pub(crate) const fn ascii_change_case_unchecked(&self) -> u8 {
 233         *self ^ ASCII_CASE_MASK
 234     }
 235
 236     /// Checks that two values are an ASCII case-insensitive match.
 237     ///
 238     /// This is equivalent to `to_ascii_lowercase(a) == to_ascii_lowercase(b)`.
 239     ///
 240     /// # Examples
 241     ///
 242     /// ```
 243     /// let lowercase_a = 97u8;
 244     /// let uppercase_a = 65u8;
 245     ///
 246     /// assert!(lowercase_a.eq_ignore_ascii_case(&uppercase_a));
 247     /// ```
 248     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
 249     #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")]
 250     #[inline]
 251     pub const fn eq_ignore_ascii_case(&self, other: &u8) -> bool {
 252         self.to_ascii_lowercase() == other.to_ascii_lowercase()
 253     }
 254
 255     /// Converts this value to its ASCII upper case equivalent in-place.
 256     ///
 257     /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
 258     /// but non-ASCII letters are unchanged.
 259     ///
 260     /// To return a new uppercased value without modifying the existing one, use
 261     /// [`to_ascii_uppercase`].
 262     ///
 263     /// # Examples
 264     ///
 265     /// ```
 266     /// let mut byte = b'a';
 267     ///
 268     /// byte.make_ascii_uppercase();
 269     ///
 270     /// assert_eq!(b'A', byte);
 271     /// ```
 272     ///
 273     /// [`to_ascii_uppercase`]: Self::to_ascii_uppercase
 274     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
 275     #[inline]
 276     pub fn make_ascii_uppercase(&mut self) {
 277         *self = self.to_ascii_uppercase();
 278     }
 279
 280     /// Converts this value to its ASCII lower case equivalent in-place.
 281     ///
 282     /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
 283     /// but non-ASCII letters are unchanged.
 284     ///
 285     /// To return a new lowercased value without modifying the existing one, use
 286     /// [`to_ascii_lowercase`].
 287     ///
 288     /// # Examples
 289     ///
 290     /// ```
 291     /// let mut byte = b'A';
 292     ///
 293     /// byte.make_ascii_lowercase();
 294     ///
 295     /// assert_eq!(b'a', byte);
 296     /// ```
 297     ///
 298     /// [`to_ascii_lowercase`]: Self::to_ascii_lowercase
 299     #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
 300     #[inline]
 301     pub fn make_ascii_lowercase(&mut self) {
 302         *self = self.to_ascii_lowercase();
 303     }
 304
 305     /// Checks if the value is an ASCII alphabetic character:
 306     ///
 307     /// - U+0041 'A' ..= U+005A 'Z', or
 308     /// - U+0061 'a' ..= U+007A 'z'.
 309     ///
 310     /// # Examples
 311     ///
 312     /// ```
 313     /// let uppercase_a = b'A';
 314     /// let uppercase_g = b'G';
 315     /// let a = b'a';
 316     /// let g = b'g';
 317     /// let zero = b'0';
 318     /// let percent = b'%';
 319     /// let space = b' ';
 320     /// let lf = b'\n';
 321     /// let esc = 0x1b_u8;
 322     ///
 323     /// assert!(uppercase_a.is_ascii_alphabetic());
 324     /// assert!(uppercase_g.is_ascii_alphabetic());
 325     /// assert!(a.is_ascii_alphabetic());
 326     /// assert!(g.is_ascii_alphabetic());
 327     /// assert!(!zero.is_ascii_alphabetic());
 328     /// assert!(!percent.is_ascii_alphabetic());
 329     /// assert!(!space.is_ascii_alphabetic());
 330     /// assert!(!lf.is_ascii_alphabetic());
 331     /// assert!(!esc.is_ascii_alphabetic());
 332     /// ```
 333     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
 334     #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
 335     #[inline]
 336     pub const fn is_ascii_alphabetic(&self) -> bool {
 337         matches!(*self, b'A'..=b'Z' | b'a'..=b'z')
 338     }
 339
 340     /// Checks if the value is an ASCII uppercase character:
 341     /// U+0041 'A' ..= U+005A 'Z'.
 342     ///
 343     /// # Examples
 344     ///
 345     /// ```
 346     /// let uppercase_a = b'A';
 347     /// let uppercase_g = b'G';
 348     /// let a = b'a';
 349     /// let g = b'g';
 350     /// let zero = b'0';
 351     /// let percent = b'%';
 352     /// let space = b' ';
 353     /// let lf = b'\n';
 354     /// let esc = 0x1b_u8;
 355     ///
 356     /// assert!(uppercase_a.is_ascii_uppercase());
 357     /// assert!(uppercase_g.is_ascii_uppercase());
 358     /// assert!(!a.is_ascii_uppercase());
 359     /// assert!(!g.is_ascii_uppercase());
 360     /// assert!(!zero.is_ascii_uppercase());
 361     /// assert!(!percent.is_ascii_uppercase());
 362     /// assert!(!space.is_ascii_uppercase());
 363     /// assert!(!lf.is_ascii_uppercase());
 364     /// assert!(!esc.is_ascii_uppercase());
 365     /// ```
 366     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
 367     #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
 368     #[inline]
 369     pub const fn is_ascii_uppercase(&self) -> bool {
 370         matches!(*self, b'A'..=b'Z')
 371     }
 372
 373     /// Checks if the value is an ASCII lowercase character:
 374     /// U+0061 'a' ..= U+007A 'z'.
 375     ///
 376     /// # Examples
 377     ///
 378     /// ```
 379     /// let uppercase_a = b'A';
 380     /// let uppercase_g = b'G';
 381     /// let a = b'a';
 382     /// let g = b'g';
 383     /// let zero = b'0';
 384     /// let percent = b'%';
 385     /// let space = b' ';
 386     /// let lf = b'\n';
 387     /// let esc = 0x1b_u8;
 388     ///
 389     /// assert!(!uppercase_a.is_ascii_lowercase());
 390     /// assert!(!uppercase_g.is_ascii_lowercase());
 391     /// assert!(a.is_ascii_lowercase());
 392     /// assert!(g.is_ascii_lowercase());
 393     /// assert!(!zero.is_ascii_lowercase());
 394     /// assert!(!percent.is_ascii_lowercase());
 395     /// assert!(!space.is_ascii_lowercase());
 396     /// assert!(!lf.is_ascii_lowercase());
 397     /// assert!(!esc.is_ascii_lowercase());
 398     /// ```
 399     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
 400     #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
 401     #[inline]
 402     pub const fn is_ascii_lowercase(&self) -> bool {
 403         matches!(*self, b'a'..=b'z')
 404     }
 405
 406     /// Checks if the value is an ASCII alphanumeric character:
 407     ///
 408     /// - U+0041 'A' ..= U+005A 'Z', or
 409     /// - U+0061 'a' ..= U+007A 'z', or
 410     /// - U+0030 '0' ..= U+0039 '9'.
 411     ///
 412     /// # Examples
 413     ///
 414     /// ```
 415     /// let uppercase_a = b'A';
 416     /// let uppercase_g = b'G';
 417     /// let a = b'a';
 418     /// let g = b'g';
 419     /// let zero = b'0';
 420     /// let percent = b'%';
 421     /// let space = b' ';
 422     /// let lf = b'\n';
 423     /// let esc = 0x1b_u8;
 424     ///
 425     /// assert!(uppercase_a.is_ascii_alphanumeric());
 426     /// assert!(uppercase_g.is_ascii_alphanumeric());
 427     /// assert!(a.is_ascii_alphanumeric());
 428     /// assert!(g.is_ascii_alphanumeric());
 429     /// assert!(zero.is_ascii_alphanumeric());
 430     /// assert!(!percent.is_ascii_alphanumeric());
 431     /// assert!(!space.is_ascii_alphanumeric());
 432     /// assert!(!lf.is_ascii_alphanumeric());
 433     /// assert!(!esc.is_ascii_alphanumeric());
 434     /// ```
 435     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
 436     #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
 437     #[inline]
 438     pub const fn is_ascii_alphanumeric(&self) -> bool {
 439         matches!(*self, b'0'..=b'9' | b'A'..=b'Z' | b'a'..=b'z')
 440     }
 441
 442     /// Checks if the value is an ASCII decimal digit:
 443     /// U+0030 '0' ..= U+0039 '9'.
 444     ///
 445     /// # Examples
 446     ///
 447     /// ```
 448     /// let uppercase_a = b'A';
 449     /// let uppercase_g = b'G';
 450     /// let a = b'a';
 451     /// let g = b'g';
 452     /// let zero = b'0';
 453     /// let percent = b'%';
 454     /// let space = b' ';
 455     /// let lf = b'\n';
 456     /// let esc = 0x1b_u8;
 457     ///
 458     /// assert!(!uppercase_a.is_ascii_digit());
 459     /// assert!(!uppercase_g.is_ascii_digit());
 460     /// assert!(!a.is_ascii_digit());
 461     /// assert!(!g.is_ascii_digit());
 462     /// assert!(zero.is_ascii_digit());
 463     /// assert!(!percent.is_ascii_digit());
 464     /// assert!(!space.is_ascii_digit());
 465     /// assert!(!lf.is_ascii_digit());
 466     /// assert!(!esc.is_ascii_digit());
 467     /// ```
 468     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
 469     #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
 470     #[inline]
 471     pub const fn is_ascii_digit(&self) -> bool {
 472         matches!(*self, b'0'..=b'9')
 473     }
 474
 475     /// Checks if the value is an ASCII hexadecimal digit:
 476     ///
 477     /// - U+0030 '0' ..= U+0039 '9', or
 478     /// - U+0041 'A' ..= U+0046 'F', or
 479     /// - U+0061 'a' ..= U+0066 'f'.
 480     ///
 481     /// # Examples
 482     ///
 483     /// ```
 484     /// let uppercase_a = b'A';
 485     /// let uppercase_g = b'G';
 486     /// let a = b'a';
 487     /// let g = b'g';
 488     /// let zero = b'0';
 489     /// let percent = b'%';
 490     /// let space = b' ';
 491     /// let lf = b'\n';
 492     /// let esc = 0x1b_u8;
 493     ///
 494     /// assert!(uppercase_a.is_ascii_hexdigit());
 495     /// assert!(!uppercase_g.is_ascii_hexdigit());
 496     /// assert!(a.is_ascii_hexdigit());
 497     /// assert!(!g.is_ascii_hexdigit());
 498     /// assert!(zero.is_ascii_hexdigit());
 499     /// assert!(!percent.is_ascii_hexdigit());
 500     /// assert!(!space.is_ascii_hexdigit());
 501     /// assert!(!lf.is_ascii_hexdigit());
 502     /// assert!(!esc.is_ascii_hexdigit());
 503     /// ```
 504     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
 505     #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
 506     #[inline]
 507     pub const fn is_ascii_hexdigit(&self) -> bool {
 508         matches!(*self, b'0'..=b'9' | b'A'..=b'F' | b'a'..=b'f')
 509     }
 510
 511     /// Checks if the value is an ASCII punctuation character:
 512     ///
 513     /// - U+0021 ..= U+002F `! " # $ % & ' ( ) * + , - . /`, or
 514     /// - U+003A ..= U+0040 `: ; < = > ? @`, or
 515     /// - U+005B ..= U+0060 ``[ \ ] ^ _ ` ``, or
 516     /// - U+007B ..= U+007E `{ | } ~`
 517     ///
 518     /// # Examples
 519     ///
 520     /// ```
 521     /// let uppercase_a = b'A';
 522     /// let uppercase_g = b'G';
 523     /// let a = b'a';
 524     /// let g = b'g';
 525     /// let zero = b'0';
 526     /// let percent = b'%';
 527     /// let space = b' ';
 528     /// let lf = b'\n';
 529     /// let esc = 0x1b_u8;
 530     ///
 531     /// assert!(!uppercase_a.is_ascii_punctuation());
 532     /// assert!(!uppercase_g.is_ascii_punctuation());
 533     /// assert!(!a.is_ascii_punctuation());
 534     /// assert!(!g.is_ascii_punctuation());
 535     /// assert!(!zero.is_ascii_punctuation());
 536     /// assert!(percent.is_ascii_punctuation());
 537     /// assert!(!space.is_ascii_punctuation());
 538     /// assert!(!lf.is_ascii_punctuation());
 539     /// assert!(!esc.is_ascii_punctuation());
 540     /// ```
 541     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
 542     #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
 543     #[inline]
 544     pub const fn is_ascii_punctuation(&self) -> bool {
 545         matches!(*self, b'!'..=b'/' | b':'..=b'@' | b'['..=b'`' | b'{'..=b'~')
 546     }
 547
 548     /// Checks if the value is an ASCII graphic character:
 549     /// U+0021 '!' ..= U+007E '~'.
 550     ///
 551     /// # Examples
 552     ///
 553     /// ```
 554     /// let uppercase_a = b'A';
 555     /// let uppercase_g = b'G';
 556     /// let a = b'a';
 557     /// let g = b'g';
 558     /// let zero = b'0';
 559     /// let percent = b'%';
 560     /// let space = b' ';
 561     /// let lf = b'\n';
 562     /// let esc = 0x1b_u8;
 563     ///
 564     /// assert!(uppercase_a.is_ascii_graphic());
 565     /// assert!(uppercase_g.is_ascii_graphic());
 566     /// assert!(a.is_ascii_graphic());
 567     /// assert!(g.is_ascii_graphic());
 568     /// assert!(zero.is_ascii_graphic());
 569     /// assert!(percent.is_ascii_graphic());
 570     /// assert!(!space.is_ascii_graphic());
 571     /// assert!(!lf.is_ascii_graphic());
 572     /// assert!(!esc.is_ascii_graphic());
 573     /// ```
 574     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
 575     #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
 576     #[inline]
 577     pub const fn is_ascii_graphic(&self) -> bool {
 578         matches!(*self, b'!'..=b'~')
 579     }
 580
 581     /// Checks if the value is an ASCII whitespace character:
 582     /// U+0020 SPACE, U+0009 HORIZONTAL TAB, U+000A LINE FEED,
 583     /// U+000C FORM FEED, or U+000D CARRIAGE RETURN.
 584     ///
 585     /// Rust uses the WhatWG Infra Standard's [definition of ASCII
 586     /// whitespace][infra-aw]. There are several other definitions in
 587     /// wide use. For instance, [the POSIX locale][pct] includes
 588     /// U+000B VERTICAL TAB as well as all the above characters,
 589     /// but—from the very same specification—[the default rule for
 590     /// "field splitting" in the Bourne shell][bfs] considers *only*
 591     /// SPACE, HORIZONTAL TAB, and LINE FEED as whitespace.
 592     ///
 593     /// If you are writing a program that will process an existing
 594     /// file format, check what that format's definition of whitespace is
 595     /// before using this function.
 596     ///
 597     /// [infra-aw]: https://infra.spec.whatwg.org/#ascii-whitespace
 598     /// [pct]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html#tag_07_03_01
 599     /// [bfs]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_05
 600     ///
 601     /// # Examples
 602     ///
 603     /// ```
 604     /// let uppercase_a = b'A';
 605     /// let uppercase_g = b'G';
 606     /// let a = b'a';
 607     /// let g = b'g';
 608     /// let zero = b'0';
 609     /// let percent = b'%';
 610     /// let space = b' ';
 611     /// let lf = b'\n';
 612     /// let esc = 0x1b_u8;
 613     ///
 614     /// assert!(!uppercase_a.is_ascii_whitespace());
 615     /// assert!(!uppercase_g.is_ascii_whitespace());
 616     /// assert!(!a.is_ascii_whitespace());
 617     /// assert!(!g.is_ascii_whitespace());
 618     /// assert!(!zero.is_ascii_whitespace());
 619     /// assert!(!percent.is_ascii_whitespace());
 620     /// assert!(space.is_ascii_whitespace());
 621     /// assert!(lf.is_ascii_whitespace());
 622     /// assert!(!esc.is_ascii_whitespace());
 623     /// ```
 624     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
 625     #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
 626     #[inline]
 627     pub const fn is_ascii_whitespace(&self) -> bool {
 628         matches!(*self, b'\t' | b'\n' | b'\x0C' | b'\r' | b' ')
 629     }
 630
 631     /// Checks if the value is an ASCII control character:
 632     /// U+0000 NUL ..= U+001F UNIT SEPARATOR, or U+007F DELETE.
 633     /// Note that most ASCII whitespace characters are control
 634     /// characters, but SPACE is not.
 635     ///
 636     /// # Examples
 637     ///
 638     /// ```
 639     /// let uppercase_a = b'A';
 640     /// let uppercase_g = b'G';
 641     /// let a = b'a';
 642     /// let g = b'g';
 643     /// let zero = b'0';
 644     /// let percent = b'%';
 645     /// let space = b' ';
 646     /// let lf = b'\n';
 647     /// let esc = 0x1b_u8;
 648     ///
 649     /// assert!(!uppercase_a.is_ascii_control());
 650     /// assert!(!uppercase_g.is_ascii_control());
 651     /// assert!(!a.is_ascii_control());
 652     /// assert!(!g.is_ascii_control());
 653     /// assert!(!zero.is_ascii_control());
 654     /// assert!(!percent.is_ascii_control());
 655     /// assert!(!space.is_ascii_control());
 656     /// assert!(lf.is_ascii_control());
 657     /// assert!(esc.is_ascii_control());
 658     /// ```
 659     #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
 660     #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
 661     #[inline]
 662     pub const fn is_ascii_control(&self) -> bool {
 663         matches!(*self, b'\0'..=b'\x1F' | b'\x7F')
 664     }
 665
 666     /// Returns an iterator that produces an escaped version of a `u8`,
 667     /// treating it as an ASCII character.
 668     ///
 669     /// The behavior is identical to [`ascii::escape_default`].
 670     ///
 671     /// # Examples
 672     ///
 673     /// ```
 674     /// #![feature(inherent_ascii_escape)]
 675     ///
 676     /// assert_eq!("0", b'0'.escape_ascii().to_string());
 677     /// assert_eq!("\\t", b'\t'.escape_ascii().to_string());
 678     /// assert_eq!("\\r", b'\r'.escape_ascii().to_string());
 679     /// assert_eq!("\\n", b'\n'.escape_ascii().to_string());
 680     /// assert_eq!("\\'", b'\''.escape_ascii().to_string());
 681     /// assert_eq!("\\\"", b'"'.escape_ascii().to_string());
 682     /// assert_eq!("\\\\", b'\\'.escape_ascii().to_string());
 683     /// assert_eq!("\\x9d", b'\x9d'.escape_ascii().to_string());
 684     /// ```
 685     #[unstable(feature = "inherent_ascii_escape", issue = "77174")]
 686     #[inline]
 687     pub fn escape_ascii(&self) -> ascii::EscapeDefault {
 688         ascii::escape_default(*self)
 689     }
 690 }
 691
 692 #[lang = "u16"]
 693 impl u16 {
 694     uint_impl! { u16, u16, 16, 65535, 4, "0xa003", "0x3a", "0x1234", "0x3412", "0x2c48",
 695     "[0x34, 0x12]", "[0x12, 0x34]", "", "" }
 696 }
 697
 698 #[lang = "u32"]
 699 impl u32 {
 700     uint_impl! { u32, u32, 32, 4294967295, 8, "0x10000b3", "0xb301", "0x12345678",
 701     "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]", "[0x12, 0x34, 0x56, 0x78]", "", "" }
 702 }
 703
 704 #[lang = "u64"]
 705 impl u64 {
 706     uint_impl! { u64, u64, 64, 18446744073709551615, 12, "0xaa00000000006e1", "0x6e10aa",
 707     "0x1234567890123456", "0x5634129078563412", "0x6a2c48091e6a2c48",
 708     "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
 709     "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
 710     "", ""}
 711 }
 712
 713 #[lang = "u128"]
 714 impl u128 {
 715     uint_impl! { u128, u128, 128, 340282366920938463463374607431768211455, 16,
 716     "0x13f40000000000000000000000004f76", "0x4f7613f4", "0x12345678901234567890123456789012",
 717     "0x12907856341290785634129078563412", "0x48091e6a2c48091e6a2c48091e6a2c48",
 718     "[0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, \
 719       0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
 720     "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56, \
 721       0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12]",
 722      "", ""}
 723 }
 724
 725 #[cfg(target_pointer_width = "16")]
 726 #[lang = "usize"]
 727 impl usize {
 728     uint_impl! { usize, u16, 16, 65535, 4, "0xa003", "0x3a", "0x1234", "0x3412", "0x2c48",
 729     "[0x34, 0x12]", "[0x12, 0x34]",
 730     usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
 731 }
 732 #[cfg(target_pointer_width = "32")]
 733 #[lang = "usize"]
 734 impl usize {
 735     uint_impl! { usize, u32, 32, 4294967295, 8, "0x10000b3", "0xb301", "0x12345678",
 736     "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]", "[0x12, 0x34, 0x56, 0x78]",
 737     usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
 738 }
 739
 740 #[cfg(target_pointer_width = "64")]
 741 #[lang = "usize"]
 742 impl usize {
 743     uint_impl! { usize, u64, 64, 18446744073709551615, 12, "0xaa00000000006e1", "0x6e10aa",
 744     "0x1234567890123456", "0x5634129078563412", "0x6a2c48091e6a2c48",
 745     "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
 746      "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
 747     usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
 748 }
 749
 750 /// A classification of floating point numbers.
 751 ///
 752 /// This `enum` is used as the return type for [`f32::classify`] and [`f64::classify`]. See
 753 /// their documentation for more.
 754 ///
 755 /// # Examples
 756 ///
 757 /// ```
 758 /// use std::num::FpCategory;
 759 ///
 760 /// let num = 12.4_f32;
 761 /// let inf = f32::INFINITY;
 762 /// let zero = 0f32;
 763 /// let sub: f32 = 1.1754942e-38;
 764 /// let nan = f32::NAN;
 765 ///
 766 /// assert_eq!(num.classify(), FpCategory::Normal);
 767 /// assert_eq!(inf.classify(), FpCategory::Infinite);
 768 /// assert_eq!(zero.classify(), FpCategory::Zero);
 769 /// assert_eq!(nan.classify(), FpCategory::Nan);
 770 /// assert_eq!(sub.classify(), FpCategory::Subnormal);
 771 /// ```
 772 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
 773 #[stable(feature = "rust1", since = "1.0.0")]
 774 pub enum FpCategory {
 775     /// "Not a Number", often obtained by dividing by zero.
 776     #[stable(feature = "rust1", since = "1.0.0")]
 777     Nan,
 778
 779     /// Positive or negative infinity.
 780     #[stable(feature = "rust1", since = "1.0.0")]
 781     Infinite,
 782
 783     /// Positive or negative zero.
 784     #[stable(feature = "rust1", since = "1.0.0")]
 785     Zero,
 786
 787     /// De-normalized floating point representation (less precise than `Normal`).
 788     #[stable(feature = "rust1", since = "1.0.0")]
 789     Subnormal,
 790
 791     /// A regular floating point number.
 792     #[stable(feature = "rust1", since = "1.0.0")]
 793     Normal,
 794 }
 795
 796 #[doc(hidden)]
 797 trait FromStrRadixHelper: PartialOrd + Copy {
 798     fn min_value() -> Self;
 799     fn max_value() -> Self;
 800     fn from_u32(u: u32) -> Self;
 801     fn checked_mul(&self, other: u32) -> Option<Self>;
 802     fn checked_sub(&self, other: u32) -> Option<Self>;
 803     fn checked_add(&self, other: u32) -> Option<Self>;
 804 }
 805
 806 macro_rules! from_str_radix_int_impl {
 807     ($($t:ty)*) => {$(
 808         #[stable(feature = "rust1", since = "1.0.0")]
 809         impl FromStr for $t {
 810             type Err = ParseIntError;
 811             fn from_str(src: &str) -> Result<Self, ParseIntError> {
 812                 from_str_radix(src, 10)
 813             }
 814         }
 815     )*}
 816 }
 817 from_str_radix_int_impl! { isize i8 i16 i32 i64 i128 usize u8 u16 u32 u64 u128 }
 818
 819 macro_rules! doit {
 820     ($($t:ty)*) => ($(impl FromStrRadixHelper for $t {
 821         #[inline]
 822         fn min_value() -> Self { Self::MIN }
 823         #[inline]
 824         fn max_value() -> Self { Self::MAX }
 825         #[inline]
 826         fn from_u32(u: u32) -> Self { u as Self }
 827         #[inline]
 828         fn checked_mul(&self, other: u32) -> Option<Self> {
 829             Self::checked_mul(*self, other as Self)
 830         }
 831         #[inline]
 832         fn checked_sub(&self, other: u32) -> Option<Self> {
 833             Self::checked_sub(*self, other as Self)
 834         }
 835         #[inline]
 836         fn checked_add(&self, other: u32) -> Option<Self> {
 837             Self::checked_add(*self, other as Self)
 838         }
 839     })*)
 840 }
 841 doit! { i8 i16 i32 i64 i128 isize u8 u16 u32 u64 u128 usize }
 842
 843 fn from_str_radix<T: FromStrRadixHelper>(src: &str, radix: u32) -> Result<T, ParseIntError> {
 844     use self::IntErrorKind::*;
 845     use self::ParseIntError as PIE;
 846
 847     assert!(
 848         radix >= 2 && radix <= 36,
 849         "from_str_radix_int: must lie in the range `[2, 36]` - found {}",
 850         radix
 851     );
 852
 853     if src.is_empty() {
 854         return Err(PIE { kind: Empty });
 855     }
 856
 857     let is_signed_ty = T::from_u32(0) > T::min_value();
 858
 859     // all valid digits are ascii, so we will just iterate over the utf8 bytes
 860     // and cast them to chars. .to_digit() will safely return None for anything
 861     // other than a valid ascii digit for the given radix, including the first-byte
 862     // of multi-byte sequences
 863     let src = src.as_bytes();
 864
 865     let (is_positive, digits) = match src[0] {
 866         b'+' | b'-' if src[1..].is_empty() => {
 867             return Err(PIE { kind: InvalidDigit });
 868         }
 869         b'+' => (true, &src[1..]),
 870         b'-' if is_signed_ty => (false, &src[1..]),
 871         _ => (true, src),
 872     };
 873
 874     let mut result = T::from_u32(0);
 875     if is_positive {
 876         // The number is positive
 877         for &c in digits {
 878             let x = match (c as char).to_digit(radix) {
 879                 Some(x) => x,
 880                 None => return Err(PIE { kind: InvalidDigit }),
 881             };
 882             result = match result.checked_mul(radix) {
 883                 Some(result) => result,
 884                 None => return Err(PIE { kind: PosOverflow }),
 885             };
 886             result = match result.checked_add(x) {
 887                 Some(result) => result,
 888                 None => return Err(PIE { kind: PosOverflow }),
 889             };
 890         }
 891     } else {
 892         // The number is negative
 893         for &c in digits {
 894             let x = match (c as char).to_digit(radix) {
 895                 Some(x) => x,
 896                 None => return Err(PIE { kind: InvalidDigit }),
 897             };
 898             result = match result.checked_mul(radix) {
 899                 Some(result) => result,
 900                 None => return Err(PIE { kind: NegOverflow }),
 901             };
 902             result = match result.checked_sub(x) {
 903                 Some(result) => result,
 904                 None => return Err(PIE { kind: NegOverflow }),
 905             };
 906         }
 907     }
 908     Ok(result)
 909 }