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