1 //! Numeric traits and functions for the built-in numeric types.
3 #![stable(feature = "rust1", since = "1.0.0")]
6 use crate::error::Error;
9 use crate::ops::{Add, Mul, Sub};
10 use crate::str::FromStr;
12 // Used because the `?` operator is not allowed in a const context.
13 macro_rules! try_opt {
22 #[allow_internal_unstable(const_likely)]
23 macro_rules! unlikely {
25 intrinsics::unlikely($e)
29 // All these modules are technically private and only exposed for coretests:
30 #[cfg(not(no_fp_fmt_parse))]
32 #[cfg(not(no_fp_fmt_parse))]
34 #[cfg(not(no_fp_fmt_parse))]
36 #[cfg(not(no_fp_fmt_parse))]
41 mod int_macros; // import int_impl!
43 mod uint_macros; // import uint_impl!
48 #[unstable(feature = "saturating_int_impl", issue = "87920")]
52 #[unstable(feature = "saturating_int_impl", issue = "87920")]
53 pub use saturating::Saturating;
54 #[stable(feature = "rust1", since = "1.0.0")]
55 pub use wrapping::Wrapping;
57 #[stable(feature = "rust1", since = "1.0.0")]
58 #[cfg(not(no_fp_fmt_parse))]
59 pub use dec2flt::ParseFloatError;
61 #[cfg(not(no_fp_fmt_parse))]
62 #[stable(feature = "rust1", since = "1.0.0")]
63 impl Error for ParseFloatError {
65 fn description(&self) -> &str {
70 #[stable(feature = "rust1", since = "1.0.0")]
71 pub use error::ParseIntError;
73 #[stable(feature = "nonzero", since = "1.28.0")]
74 pub use nonzero::{NonZeroU128, NonZeroU16, NonZeroU32, NonZeroU64, NonZeroU8, NonZeroUsize};
76 #[stable(feature = "signed_nonzero", since = "1.34.0")]
77 pub use nonzero::{NonZeroI128, NonZeroI16, NonZeroI32, NonZeroI64, NonZeroI8, NonZeroIsize};
79 #[stable(feature = "try_from", since = "1.34.0")]
80 pub use error::TryFromIntError;
82 #[stable(feature = "int_error_matching", since = "1.55.0")]
83 pub use error::IntErrorKind;
85 macro_rules! usize_isize_to_xe_bytes_doc {
89 **Note**: This function returns an array of length 2, 4 or 8 bytes
90 depending on the target pointer size.
96 macro_rules! usize_isize_from_xe_bytes_doc {
100 **Note**: This function takes an array of length 2, 4 or 8 bytes
101 depending on the target pointer size.
107 macro_rules! widening_impl {
108 ($SelfT:ty, $WideT:ty, $BITS:literal, unsigned) => {
109 /// Calculates the complete product `self * rhs` without the possibility to overflow.
111 /// This returns the low-order (wrapping) bits and the high-order (overflow) bits
112 /// of the result as two separate values, in that order.
114 /// If you also need to add a carry to the wide result, then you want
115 /// [`Self::carrying_mul`] instead.
121 /// Please note that this example is shared between integer types.
122 /// Which explains why `u32` is used here.
125 /// #![feature(bigint_helper_methods)]
126 /// assert_eq!(5u32.widening_mul(2), (10, 0));
127 /// assert_eq!(1_000_000_000u32.widening_mul(10), (1410065408, 2));
129 #[unstable(feature = "bigint_helper_methods", issue = "85532")]
130 #[rustc_const_unstable(feature = "const_bigint_helper_methods", issue = "85532")]
131 #[must_use = "this returns the result of the operation, \
132 without modifying the original"]
134 pub const fn widening_mul(self, rhs: Self) -> (Self, Self) {
135 // note: longer-term this should be done via an intrinsic,
136 // but for now we can deal without an impl for u128/i128
137 // SAFETY: overflow will be contained within the wider types
138 let wide = unsafe { (self as $WideT).unchecked_mul(rhs as $WideT) };
139 (wide as $SelfT, (wide >> $BITS) as $SelfT)
142 /// Calculates the "full multiplication" `self * rhs + carry`
143 /// without the possibility to overflow.
145 /// This returns the low-order (wrapping) bits and the high-order (overflow) bits
146 /// of the result as two separate values, in that order.
148 /// Performs "long multiplication" which takes in an extra amount to add, and may return an
149 /// additional amount of overflow. This allows for chaining together multiple
150 /// multiplications to create "big integers" which represent larger values.
152 /// If you don't need the `carry`, then you can use [`Self::widening_mul`] instead.
158 /// Please note that this example is shared between integer types.
159 /// Which explains why `u32` is used here.
162 /// #![feature(bigint_helper_methods)]
163 /// assert_eq!(5u32.carrying_mul(2, 0), (10, 0));
164 /// assert_eq!(5u32.carrying_mul(2, 10), (20, 0));
165 /// assert_eq!(1_000_000_000u32.carrying_mul(10, 0), (1410065408, 2));
166 /// assert_eq!(1_000_000_000u32.carrying_mul(10, 10), (1410065418, 2));
167 #[doc = concat!("assert_eq!(",
168 stringify!($SelfT), "::MAX.carrying_mul(", stringify!($SelfT), "::MAX, ", stringify!($SelfT), "::MAX), ",
169 "(0, ", stringify!($SelfT), "::MAX));"
173 /// This is the core operation needed for scalar multiplication when
174 /// implementing it for wider-than-native types.
177 /// #![feature(bigint_helper_methods)]
178 /// fn scalar_mul_eq(little_endian_digits: &mut Vec<u16>, multiplicand: u16) {
179 /// let mut carry = 0;
180 /// for d in little_endian_digits.iter_mut() {
181 /// (*d, carry) = d.carrying_mul(multiplicand, carry);
184 /// little_endian_digits.push(carry);
188 /// let mut v = vec![10, 20];
189 /// scalar_mul_eq(&mut v, 3);
190 /// assert_eq!(v, [30, 60]);
192 /// assert_eq!(0x87654321_u64 * 0xFEED, 0x86D3D159E38D);
193 /// let mut v = vec![0x4321, 0x8765];
194 /// scalar_mul_eq(&mut v, 0xFEED);
195 /// assert_eq!(v, [0xE38D, 0xD159, 0x86D3]);
198 /// If `carry` is zero, this is similar to [`overflowing_mul`](Self::overflowing_mul),
199 /// except that it gives the value of the overflow instead of just whether one happened:
202 /// #![feature(bigint_helper_methods)]
203 /// let r = u8::carrying_mul(7, 13, 0);
204 /// assert_eq!((r.0, r.1 != 0), u8::overflowing_mul(7, 13));
205 /// let r = u8::carrying_mul(13, 42, 0);
206 /// assert_eq!((r.0, r.1 != 0), u8::overflowing_mul(13, 42));
209 /// The value of the first field in the returned tuple matches what you'd get
210 /// by combining the [`wrapping_mul`](Self::wrapping_mul) and
211 /// [`wrapping_add`](Self::wrapping_add) methods:
214 /// #![feature(bigint_helper_methods)]
216 /// 789_u16.carrying_mul(456, 123).0,
217 /// 789_u16.wrapping_mul(456).wrapping_add(123),
220 #[unstable(feature = "bigint_helper_methods", issue = "85532")]
221 #[rustc_const_unstable(feature = "bigint_helper_methods", issue = "85532")]
222 #[must_use = "this returns the result of the operation, \
223 without modifying the original"]
225 pub const fn carrying_mul(self, rhs: Self, carry: Self) -> (Self, Self) {
226 // note: longer-term this should be done via an intrinsic,
227 // but for now we can deal without an impl for u128/i128
228 // SAFETY: overflow will be contained within the wider types
230 (self as $WideT).unchecked_mul(rhs as $WideT).unchecked_add(carry as $WideT)
232 (wide as $SelfT, (wide >> $BITS) as $SelfT)
238 int_impl! { i8, i8, u8, 8, 7, -128, 127, 2, "-0x7e", "0xa", "0x12", "0x12", "0x48",
239 "[0x12]", "[0x12]", "", "", "" }
243 int_impl! { i16, i16, u16, 16, 15, -32768, 32767, 4, "-0x5ffd", "0x3a", "0x1234", "0x3412",
244 "0x2c48", "[0x34, 0x12]", "[0x12, 0x34]", "", "", "" }
248 int_impl! { i32, i32, u32, 32, 31, -2147483648, 2147483647, 8, "0x10000b3", "0xb301",
249 "0x12345678", "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]",
250 "[0x12, 0x34, 0x56, 0x78]", "", "", "" }
254 int_impl! { i64, i64, u64, 64, 63, -9223372036854775808, 9223372036854775807, 12,
255 "0xaa00000000006e1", "0x6e10aa", "0x1234567890123456", "0x5634129078563412",
256 "0x6a2c48091e6a2c48", "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
257 "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]", "", "", "" }
261 int_impl! { i128, i128, u128, 128, 127, -170141183460469231731687303715884105728,
262 170141183460469231731687303715884105727, 16,
263 "0x13f40000000000000000000000004f76", "0x4f7613f4", "0x12345678901234567890123456789012",
264 "0x12907856341290785634129078563412", "0x48091e6a2c48091e6a2c48091e6a2c48",
265 "[0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, \
266 0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
267 "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56, \
268 0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12]", "", "", "" }
271 #[cfg(target_pointer_width = "16")]
273 int_impl! { isize, i16, usize, 16, 15, -32768, 32767, 4, "-0x5ffd", "0x3a", "0x1234",
274 "0x3412", "0x2c48", "[0x34, 0x12]", "[0x12, 0x34]",
275 usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!(),
276 " on 16-bit targets" }
279 #[cfg(target_pointer_width = "32")]
281 int_impl! { isize, i32, usize, 32, 31, -2147483648, 2147483647, 8, "0x10000b3", "0xb301",
282 "0x12345678", "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]",
283 "[0x12, 0x34, 0x56, 0x78]",
284 usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!(),
285 " on 32-bit targets" }
288 #[cfg(target_pointer_width = "64")]
290 int_impl! { isize, i64, usize, 64, 63, -9223372036854775808, 9223372036854775807,
291 12, "0xaa00000000006e1", "0x6e10aa", "0x1234567890123456", "0x5634129078563412",
292 "0x6a2c48091e6a2c48", "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
293 "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
294 usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!(),
295 " on 64-bit targets" }
298 /// If 6th bit set ascii is upper case.
299 const ASCII_CASE_MASK: u8 = 0b0010_0000;
302 uint_impl! { u8, u8, i8, NonZeroU8, 8, 255, 2, "0x82", "0xa", "0x12", "0x12", "0x48", "[0x12]",
303 "[0x12]", "", "", "" }
304 widening_impl! { u8, u16, 8, unsigned }
306 /// Checks if the value is within the ASCII range.
311 /// let ascii = 97u8;
312 /// let non_ascii = 150u8;
314 /// assert!(ascii.is_ascii());
315 /// assert!(!non_ascii.is_ascii());
318 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
319 #[rustc_const_stable(feature = "const_u8_is_ascii", since = "1.43.0")]
321 pub const fn is_ascii(&self) -> bool {
325 /// Makes a copy of the value in its ASCII upper case equivalent.
327 /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
328 /// but non-ASCII letters are unchanged.
330 /// To uppercase the value in-place, use [`make_ascii_uppercase`].
335 /// let lowercase_a = 97u8;
337 /// assert_eq!(65, lowercase_a.to_ascii_uppercase());
340 /// [`make_ascii_uppercase`]: Self::make_ascii_uppercase
341 #[must_use = "to uppercase the value in-place, use `make_ascii_uppercase()`"]
342 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
343 #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")]
345 pub const fn to_ascii_uppercase(&self) -> u8 {
346 // Toggle the fifth bit if this is a lowercase letter
347 *self ^ ((self.is_ascii_lowercase() as u8) * ASCII_CASE_MASK)
350 /// Makes a copy of the value in its ASCII lower case equivalent.
352 /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
353 /// but non-ASCII letters are unchanged.
355 /// To lowercase the value in-place, use [`make_ascii_lowercase`].
360 /// let uppercase_a = 65u8;
362 /// assert_eq!(97, uppercase_a.to_ascii_lowercase());
365 /// [`make_ascii_lowercase`]: Self::make_ascii_lowercase
366 #[must_use = "to lowercase the value in-place, use `make_ascii_lowercase()`"]
367 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
368 #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")]
370 pub const fn to_ascii_lowercase(&self) -> u8 {
371 // Set the fifth bit if this is an uppercase letter
372 *self | (self.is_ascii_uppercase() as u8 * ASCII_CASE_MASK)
375 /// Assumes self is ascii
377 pub(crate) const fn ascii_change_case_unchecked(&self) -> u8 {
378 *self ^ ASCII_CASE_MASK
381 /// Checks that two values are an ASCII case-insensitive match.
383 /// This is equivalent to `to_ascii_lowercase(a) == to_ascii_lowercase(b)`.
388 /// let lowercase_a = 97u8;
389 /// let uppercase_a = 65u8;
391 /// assert!(lowercase_a.eq_ignore_ascii_case(&uppercase_a));
393 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
394 #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")]
396 pub const fn eq_ignore_ascii_case(&self, other: &u8) -> bool {
397 self.to_ascii_lowercase() == other.to_ascii_lowercase()
400 /// Converts this value to its ASCII upper case equivalent in-place.
402 /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
403 /// but non-ASCII letters are unchanged.
405 /// To return a new uppercased value without modifying the existing one, use
406 /// [`to_ascii_uppercase`].
411 /// let mut byte = b'a';
413 /// byte.make_ascii_uppercase();
415 /// assert_eq!(b'A', byte);
418 /// [`to_ascii_uppercase`]: Self::to_ascii_uppercase
419 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
421 pub fn make_ascii_uppercase(&mut self) {
422 *self = self.to_ascii_uppercase();
425 /// Converts this value to its ASCII lower case equivalent in-place.
427 /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
428 /// but non-ASCII letters are unchanged.
430 /// To return a new lowercased value without modifying the existing one, use
431 /// [`to_ascii_lowercase`].
436 /// let mut byte = b'A';
438 /// byte.make_ascii_lowercase();
440 /// assert_eq!(b'a', byte);
443 /// [`to_ascii_lowercase`]: Self::to_ascii_lowercase
444 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
446 pub fn make_ascii_lowercase(&mut self) {
447 *self = self.to_ascii_lowercase();
450 /// Checks if the value is an ASCII alphabetic character:
452 /// - U+0041 'A' ..= U+005A 'Z', or
453 /// - U+0061 'a' ..= U+007A 'z'.
458 /// let uppercase_a = b'A';
459 /// let uppercase_g = b'G';
463 /// let percent = b'%';
464 /// let space = b' ';
466 /// let esc = b'\x1b';
468 /// assert!(uppercase_a.is_ascii_alphabetic());
469 /// assert!(uppercase_g.is_ascii_alphabetic());
470 /// assert!(a.is_ascii_alphabetic());
471 /// assert!(g.is_ascii_alphabetic());
472 /// assert!(!zero.is_ascii_alphabetic());
473 /// assert!(!percent.is_ascii_alphabetic());
474 /// assert!(!space.is_ascii_alphabetic());
475 /// assert!(!lf.is_ascii_alphabetic());
476 /// assert!(!esc.is_ascii_alphabetic());
479 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
480 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
482 pub const fn is_ascii_alphabetic(&self) -> bool {
483 matches!(*self, b'A'..=b'Z' | b'a'..=b'z')
486 /// Checks if the value is an ASCII uppercase character:
487 /// U+0041 'A' ..= U+005A 'Z'.
492 /// let uppercase_a = b'A';
493 /// let uppercase_g = b'G';
497 /// let percent = b'%';
498 /// let space = b' ';
500 /// let esc = b'\x1b';
502 /// assert!(uppercase_a.is_ascii_uppercase());
503 /// assert!(uppercase_g.is_ascii_uppercase());
504 /// assert!(!a.is_ascii_uppercase());
505 /// assert!(!g.is_ascii_uppercase());
506 /// assert!(!zero.is_ascii_uppercase());
507 /// assert!(!percent.is_ascii_uppercase());
508 /// assert!(!space.is_ascii_uppercase());
509 /// assert!(!lf.is_ascii_uppercase());
510 /// assert!(!esc.is_ascii_uppercase());
513 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
514 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
516 pub const fn is_ascii_uppercase(&self) -> bool {
517 matches!(*self, b'A'..=b'Z')
520 /// Checks if the value is an ASCII lowercase character:
521 /// U+0061 'a' ..= U+007A 'z'.
526 /// let uppercase_a = b'A';
527 /// let uppercase_g = b'G';
531 /// let percent = b'%';
532 /// let space = b' ';
534 /// let esc = b'\x1b';
536 /// assert!(!uppercase_a.is_ascii_lowercase());
537 /// assert!(!uppercase_g.is_ascii_lowercase());
538 /// assert!(a.is_ascii_lowercase());
539 /// assert!(g.is_ascii_lowercase());
540 /// assert!(!zero.is_ascii_lowercase());
541 /// assert!(!percent.is_ascii_lowercase());
542 /// assert!(!space.is_ascii_lowercase());
543 /// assert!(!lf.is_ascii_lowercase());
544 /// assert!(!esc.is_ascii_lowercase());
547 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
548 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
550 pub const fn is_ascii_lowercase(&self) -> bool {
551 matches!(*self, b'a'..=b'z')
554 /// Checks if the value is an ASCII alphanumeric character:
556 /// - U+0041 'A' ..= U+005A 'Z', or
557 /// - U+0061 'a' ..= U+007A 'z', or
558 /// - U+0030 '0' ..= U+0039 '9'.
563 /// let uppercase_a = b'A';
564 /// let uppercase_g = b'G';
568 /// let percent = b'%';
569 /// let space = b' ';
571 /// let esc = b'\x1b';
573 /// assert!(uppercase_a.is_ascii_alphanumeric());
574 /// assert!(uppercase_g.is_ascii_alphanumeric());
575 /// assert!(a.is_ascii_alphanumeric());
576 /// assert!(g.is_ascii_alphanumeric());
577 /// assert!(zero.is_ascii_alphanumeric());
578 /// assert!(!percent.is_ascii_alphanumeric());
579 /// assert!(!space.is_ascii_alphanumeric());
580 /// assert!(!lf.is_ascii_alphanumeric());
581 /// assert!(!esc.is_ascii_alphanumeric());
584 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
585 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
587 pub const fn is_ascii_alphanumeric(&self) -> bool {
588 matches!(*self, b'0'..=b'9' | b'A'..=b'Z' | b'a'..=b'z')
591 /// Checks if the value is an ASCII decimal digit:
592 /// U+0030 '0' ..= U+0039 '9'.
597 /// let uppercase_a = b'A';
598 /// let uppercase_g = b'G';
602 /// let percent = b'%';
603 /// let space = b' ';
605 /// let esc = b'\x1b';
607 /// assert!(!uppercase_a.is_ascii_digit());
608 /// assert!(!uppercase_g.is_ascii_digit());
609 /// assert!(!a.is_ascii_digit());
610 /// assert!(!g.is_ascii_digit());
611 /// assert!(zero.is_ascii_digit());
612 /// assert!(!percent.is_ascii_digit());
613 /// assert!(!space.is_ascii_digit());
614 /// assert!(!lf.is_ascii_digit());
615 /// assert!(!esc.is_ascii_digit());
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")]
621 pub const fn is_ascii_digit(&self) -> bool {
622 matches!(*self, b'0'..=b'9')
625 /// Checks if the value is an ASCII octal digit:
626 /// U+0030 '0' ..= U+0037 '7'.
631 /// #![feature(is_ascii_octdigit)]
633 /// let uppercase_a = b'A';
636 /// let seven = b'7';
638 /// let percent = b'%';
641 /// assert!(!uppercase_a.is_ascii_octdigit());
642 /// assert!(!a.is_ascii_octdigit());
643 /// assert!(zero.is_ascii_octdigit());
644 /// assert!(seven.is_ascii_octdigit());
645 /// assert!(!nine.is_ascii_octdigit());
646 /// assert!(!percent.is_ascii_octdigit());
647 /// assert!(!lf.is_ascii_octdigit());
650 #[unstable(feature = "is_ascii_octdigit", issue = "101288")]
651 #[rustc_const_unstable(feature = "is_ascii_octdigit", issue = "101288")]
653 pub const fn is_ascii_octdigit(&self) -> bool {
654 matches!(*self, b'0'..=b'7')
657 /// Checks if the value is an ASCII hexadecimal digit:
659 /// - U+0030 '0' ..= U+0039 '9', or
660 /// - U+0041 'A' ..= U+0046 'F', or
661 /// - U+0061 'a' ..= U+0066 'f'.
666 /// let uppercase_a = b'A';
667 /// let uppercase_g = b'G';
671 /// let percent = b'%';
672 /// let space = b' ';
674 /// let esc = b'\x1b';
676 /// assert!(uppercase_a.is_ascii_hexdigit());
677 /// assert!(!uppercase_g.is_ascii_hexdigit());
678 /// assert!(a.is_ascii_hexdigit());
679 /// assert!(!g.is_ascii_hexdigit());
680 /// assert!(zero.is_ascii_hexdigit());
681 /// assert!(!percent.is_ascii_hexdigit());
682 /// assert!(!space.is_ascii_hexdigit());
683 /// assert!(!lf.is_ascii_hexdigit());
684 /// assert!(!esc.is_ascii_hexdigit());
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")]
690 pub const fn is_ascii_hexdigit(&self) -> bool {
691 matches!(*self, b'0'..=b'9' | b'A'..=b'F' | b'a'..=b'f')
694 /// Checks if the value is an ASCII punctuation character:
696 /// - U+0021 ..= U+002F `! " # $ % & ' ( ) * + , - . /`, or
697 /// - U+003A ..= U+0040 `: ; < = > ? @`, or
698 /// - U+005B ..= U+0060 `` [ \ ] ^ _ ` ``, or
699 /// - U+007B ..= U+007E `{ | } ~`
704 /// let uppercase_a = b'A';
705 /// let uppercase_g = b'G';
709 /// let percent = b'%';
710 /// let space = b' ';
712 /// let esc = b'\x1b';
714 /// assert!(!uppercase_a.is_ascii_punctuation());
715 /// assert!(!uppercase_g.is_ascii_punctuation());
716 /// assert!(!a.is_ascii_punctuation());
717 /// assert!(!g.is_ascii_punctuation());
718 /// assert!(!zero.is_ascii_punctuation());
719 /// assert!(percent.is_ascii_punctuation());
720 /// assert!(!space.is_ascii_punctuation());
721 /// assert!(!lf.is_ascii_punctuation());
722 /// assert!(!esc.is_ascii_punctuation());
725 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
726 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
728 pub const fn is_ascii_punctuation(&self) -> bool {
729 matches!(*self, b'!'..=b'/' | b':'..=b'@' | b'['..=b'`' | b'{'..=b'~')
732 /// Checks if the value is an ASCII graphic character:
733 /// U+0021 '!' ..= U+007E '~'.
738 /// let uppercase_a = b'A';
739 /// let uppercase_g = b'G';
743 /// let percent = b'%';
744 /// let space = b' ';
746 /// let esc = b'\x1b';
748 /// assert!(uppercase_a.is_ascii_graphic());
749 /// assert!(uppercase_g.is_ascii_graphic());
750 /// assert!(a.is_ascii_graphic());
751 /// assert!(g.is_ascii_graphic());
752 /// assert!(zero.is_ascii_graphic());
753 /// assert!(percent.is_ascii_graphic());
754 /// assert!(!space.is_ascii_graphic());
755 /// assert!(!lf.is_ascii_graphic());
756 /// assert!(!esc.is_ascii_graphic());
759 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
760 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
762 pub const fn is_ascii_graphic(&self) -> bool {
763 matches!(*self, b'!'..=b'~')
766 /// Checks if the value is an ASCII whitespace character:
767 /// U+0020 SPACE, U+0009 HORIZONTAL TAB, U+000A LINE FEED,
768 /// U+000C FORM FEED, or U+000D CARRIAGE RETURN.
770 /// Rust uses the WhatWG Infra Standard's [definition of ASCII
771 /// whitespace][infra-aw]. There are several other definitions in
772 /// wide use. For instance, [the POSIX locale][pct] includes
773 /// U+000B VERTICAL TAB as well as all the above characters,
774 /// but—from the very same specification—[the default rule for
775 /// "field splitting" in the Bourne shell][bfs] considers *only*
776 /// SPACE, HORIZONTAL TAB, and LINE FEED as whitespace.
778 /// If you are writing a program that will process an existing
779 /// file format, check what that format's definition of whitespace is
780 /// before using this function.
782 /// [infra-aw]: https://infra.spec.whatwg.org/#ascii-whitespace
783 /// [pct]: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html#tag_07_03_01
784 /// [bfs]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_05
789 /// let uppercase_a = b'A';
790 /// let uppercase_g = b'G';
794 /// let percent = b'%';
795 /// let space = b' ';
797 /// let esc = b'\x1b';
799 /// assert!(!uppercase_a.is_ascii_whitespace());
800 /// assert!(!uppercase_g.is_ascii_whitespace());
801 /// assert!(!a.is_ascii_whitespace());
802 /// assert!(!g.is_ascii_whitespace());
803 /// assert!(!zero.is_ascii_whitespace());
804 /// assert!(!percent.is_ascii_whitespace());
805 /// assert!(space.is_ascii_whitespace());
806 /// assert!(lf.is_ascii_whitespace());
807 /// assert!(!esc.is_ascii_whitespace());
810 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
811 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
813 pub const fn is_ascii_whitespace(&self) -> bool {
814 matches!(*self, b'\t' | b'\n' | b'\x0C' | b'\r' | b' ')
817 /// Checks if the value is an ASCII control character:
818 /// U+0000 NUL ..= U+001F UNIT SEPARATOR, or U+007F DELETE.
819 /// Note that most ASCII whitespace characters are control
820 /// characters, but SPACE is not.
825 /// let uppercase_a = b'A';
826 /// let uppercase_g = b'G';
830 /// let percent = b'%';
831 /// let space = b' ';
833 /// let esc = b'\x1b';
835 /// assert!(!uppercase_a.is_ascii_control());
836 /// assert!(!uppercase_g.is_ascii_control());
837 /// assert!(!a.is_ascii_control());
838 /// assert!(!g.is_ascii_control());
839 /// assert!(!zero.is_ascii_control());
840 /// assert!(!percent.is_ascii_control());
841 /// assert!(!space.is_ascii_control());
842 /// assert!(lf.is_ascii_control());
843 /// assert!(esc.is_ascii_control());
846 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
847 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
849 pub const fn is_ascii_control(&self) -> bool {
850 matches!(*self, b'\0'..=b'\x1F' | b'\x7F')
853 /// Returns an iterator that produces an escaped version of a `u8`,
854 /// treating it as an ASCII character.
856 /// The behavior is identical to [`ascii::escape_default`].
862 /// assert_eq!("0", b'0'.escape_ascii().to_string());
863 /// assert_eq!("\\t", b'\t'.escape_ascii().to_string());
864 /// assert_eq!("\\r", b'\r'.escape_ascii().to_string());
865 /// assert_eq!("\\n", b'\n'.escape_ascii().to_string());
866 /// assert_eq!("\\'", b'\''.escape_ascii().to_string());
867 /// assert_eq!("\\\"", b'"'.escape_ascii().to_string());
868 /// assert_eq!("\\\\", b'\\'.escape_ascii().to_string());
869 /// assert_eq!("\\x9d", b'\x9d'.escape_ascii().to_string());
871 #[must_use = "this returns the escaped byte as an iterator, \
872 without modifying the original"]
873 #[stable(feature = "inherent_ascii_escape", since = "1.60.0")]
875 pub fn escape_ascii(self) -> ascii::EscapeDefault {
876 ascii::escape_default(self)
880 pub(crate) const fn is_utf8_char_boundary(self) -> bool {
881 // This is bit magic equivalent to: b < 128 || b >= 192
882 (self as i8) >= -0x40
887 uint_impl! { u16, u16, i16, NonZeroU16, 16, 65535, 4, "0xa003", "0x3a", "0x1234", "0x3412", "0x2c48",
888 "[0x34, 0x12]", "[0x12, 0x34]", "", "", "" }
889 widening_impl! { u16, u32, 16, unsigned }
891 /// Checks if the value is a Unicode surrogate code point, which are disallowed values for [`char`].
896 /// #![feature(utf16_extra)]
898 /// let low_non_surrogate = 0xA000u16;
899 /// let low_surrogate = 0xD800u16;
900 /// let high_surrogate = 0xDC00u16;
901 /// let high_non_surrogate = 0xE000u16;
903 /// assert!(!low_non_surrogate.is_utf16_surrogate());
904 /// assert!(low_surrogate.is_utf16_surrogate());
905 /// assert!(high_surrogate.is_utf16_surrogate());
906 /// assert!(!high_non_surrogate.is_utf16_surrogate());
909 #[unstable(feature = "utf16_extra", issue = "94919")]
910 #[rustc_const_unstable(feature = "utf16_extra_const", issue = "94919")]
912 pub const fn is_utf16_surrogate(self) -> bool {
913 matches!(self, 0xD800..=0xDFFF)
918 uint_impl! { u32, u32, i32, NonZeroU32, 32, 4294967295, 8, "0x10000b3", "0xb301", "0x12345678",
919 "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]", "[0x12, 0x34, 0x56, 0x78]", "", "", "" }
920 widening_impl! { u32, u64, 32, unsigned }
924 uint_impl! { u64, u64, i64, NonZeroU64, 64, 18446744073709551615, 12, "0xaa00000000006e1", "0x6e10aa",
925 "0x1234567890123456", "0x5634129078563412", "0x6a2c48091e6a2c48",
926 "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
927 "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
929 widening_impl! { u64, u128, 64, unsigned }
933 uint_impl! { u128, u128, i128, NonZeroU128, 128, 340282366920938463463374607431768211455, 16,
934 "0x13f40000000000000000000000004f76", "0x4f7613f4", "0x12345678901234567890123456789012",
935 "0x12907856341290785634129078563412", "0x48091e6a2c48091e6a2c48091e6a2c48",
936 "[0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, \
937 0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
938 "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56, \
939 0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12]",
943 #[cfg(target_pointer_width = "16")]
945 uint_impl! { usize, u16, isize, NonZeroUsize, 16, 65535, 4, "0xa003", "0x3a", "0x1234", "0x3412", "0x2c48",
946 "[0x34, 0x12]", "[0x12, 0x34]",
947 usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!(),
948 " on 16-bit targets" }
949 widening_impl! { usize, u32, 16, unsigned }
951 #[cfg(target_pointer_width = "32")]
953 uint_impl! { usize, u32, isize, NonZeroUsize, 32, 4294967295, 8, "0x10000b3", "0xb301", "0x12345678",
954 "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]", "[0x12, 0x34, 0x56, 0x78]",
955 usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!(),
956 " on 32-bit targets" }
957 widening_impl! { usize, u64, 32, unsigned }
960 #[cfg(target_pointer_width = "64")]
962 uint_impl! { usize, u64, isize, NonZeroUsize, 64, 18446744073709551615, 12, "0xaa00000000006e1", "0x6e10aa",
963 "0x1234567890123456", "0x5634129078563412", "0x6a2c48091e6a2c48",
964 "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
965 "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
966 usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!(),
967 " on 64-bit targets" }
968 widening_impl! { usize, u128, 64, unsigned }
972 /// Returns an `usize` where every byte is equal to `x`.
974 pub(crate) const fn repeat_u8(x: u8) -> usize {
975 usize::from_ne_bytes([x; mem::size_of::<usize>()])
978 /// Returns an `usize` where every byte pair is equal to `x`.
980 pub(crate) const fn repeat_u16(x: u16) -> usize {
983 while i < mem::size_of::<usize>() {
984 // Use `wrapping_shl` to make it work on targets with 16-bit `usize`
985 r = r.wrapping_shl(16) | (x as usize);
992 /// A classification of floating point numbers.
994 /// This `enum` is used as the return type for [`f32::classify`] and [`f64::classify`]. See
995 /// their documentation for more.
1000 /// use std::num::FpCategory;
1002 /// let num = 12.4_f32;
1003 /// let inf = f32::INFINITY;
1004 /// let zero = 0f32;
1005 /// let sub: f32 = 1.1754942e-38;
1006 /// let nan = f32::NAN;
1008 /// assert_eq!(num.classify(), FpCategory::Normal);
1009 /// assert_eq!(inf.classify(), FpCategory::Infinite);
1010 /// assert_eq!(zero.classify(), FpCategory::Zero);
1011 /// assert_eq!(sub.classify(), FpCategory::Subnormal);
1012 /// assert_eq!(nan.classify(), FpCategory::Nan);
1014 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
1015 #[stable(feature = "rust1", since = "1.0.0")]
1016 pub enum FpCategory {
1017 /// NaN (not a number): this value results from calculations like `(-1.0).sqrt()`.
1019 /// See [the documentation for `f32`](f32) for more information on the unusual properties
1021 #[stable(feature = "rust1", since = "1.0.0")]
1024 /// Positive or negative infinity, which often results from dividing a nonzero number
1026 #[stable(feature = "rust1", since = "1.0.0")]
1029 /// Positive or negative zero.
1031 /// See [the documentation for `f32`](f32) for more information on the signedness of zeroes.
1032 #[stable(feature = "rust1", since = "1.0.0")]
1035 /// “Subnormal” or “denormal” floating point representation (less precise, relative to
1036 /// their magnitude, than [`Normal`]).
1038 /// Subnormal numbers are larger in magnitude than [`Zero`] but smaller in magnitude than all
1039 /// [`Normal`] numbers.
1041 /// [`Normal`]: Self::Normal
1042 /// [`Zero`]: Self::Zero
1043 #[stable(feature = "rust1", since = "1.0.0")]
1046 /// A regular floating point number, not any of the exceptional categories.
1048 /// The smallest positive normal numbers are [`f32::MIN_POSITIVE`] and [`f64::MIN_POSITIVE`],
1049 /// and the largest positive normal numbers are [`f32::MAX`] and [`f64::MAX`]. (Unlike signed
1050 /// integers, floating point numbers are symmetric in their range, so negating any of these
1051 /// constants will produce their negative counterpart.)
1052 #[stable(feature = "rust1", since = "1.0.0")]
1057 trait FromStrRadixHelper:
1058 PartialOrd + Copy + Add<Output = Self> + Sub<Output = Self> + Mul<Output = Self>
1061 fn from_u32(u: u32) -> Self;
1062 fn checked_mul(&self, other: u32) -> Option<Self>;
1063 fn checked_sub(&self, other: u32) -> Option<Self>;
1064 fn checked_add(&self, other: u32) -> Option<Self>;
1067 macro_rules! from_str_radix_int_impl {
1069 #[stable(feature = "rust1", since = "1.0.0")]
1070 impl FromStr for $t {
1071 type Err = ParseIntError;
1072 fn from_str(src: &str) -> Result<Self, ParseIntError> {
1073 from_str_radix(src, 10)
1078 from_str_radix_int_impl! { isize i8 i16 i32 i64 i128 usize u8 u16 u32 u64 u128 }
1080 macro_rules! impl_helper_for {
1081 ($($t:ty)*) => ($(impl FromStrRadixHelper for $t {
1082 const MIN: Self = Self::MIN;
1084 fn from_u32(u: u32) -> Self { u as Self }
1086 fn checked_mul(&self, other: u32) -> Option<Self> {
1087 Self::checked_mul(*self, other as Self)
1090 fn checked_sub(&self, other: u32) -> Option<Self> {
1091 Self::checked_sub(*self, other as Self)
1094 fn checked_add(&self, other: u32) -> Option<Self> {
1095 Self::checked_add(*self, other as Self)
1099 impl_helper_for! { i8 i16 i32 i64 i128 isize u8 u16 u32 u64 u128 usize }
1101 /// Determines if a string of text of that length of that radix could be guaranteed to be
1102 /// stored in the given type T.
1103 /// Note that if the radix is known to the compiler, it is just the check of digits.len that
1104 /// is done at runtime.
1107 #[unstable(issue = "none", feature = "std_internals")]
1108 pub fn can_not_overflow<T>(radix: u32, is_signed_ty: bool, digits: &[u8]) -> bool {
1109 radix <= 16 && digits.len() <= mem::size_of::<T>() * 2 - is_signed_ty as usize
1112 fn from_str_radix<T: FromStrRadixHelper>(src: &str, radix: u32) -> Result<T, ParseIntError> {
1113 use self::IntErrorKind::*;
1114 use self::ParseIntError as PIE;
1117 (2..=36).contains(&radix),
1118 "from_str_radix_int: must lie in the range `[2, 36]` - found {}",
1123 return Err(PIE { kind: Empty });
1126 let is_signed_ty = T::from_u32(0) > T::MIN;
1128 // all valid digits are ascii, so we will just iterate over the utf8 bytes
1129 // and cast them to chars. .to_digit() will safely return None for anything
1130 // other than a valid ascii digit for the given radix, including the first-byte
1131 // of multi-byte sequences
1132 let src = src.as_bytes();
1134 let (is_positive, digits) = match src[0] {
1135 b'+' | b'-' if src[1..].is_empty() => {
1136 return Err(PIE { kind: InvalidDigit });
1138 b'+' => (true, &src[1..]),
1139 b'-' if is_signed_ty => (false, &src[1..]),
1143 let mut result = T::from_u32(0);
1145 if can_not_overflow::<T>(radix, is_signed_ty, digits) {
1146 // If the len of the str is short compared to the range of the type
1147 // we are parsing into, then we can be certain that an overflow will not occur.
1148 // This bound is when `radix.pow(digits.len()) - 1 <= T::MAX` but the condition
1149 // above is a faster (conservative) approximation of this.
1151 // Consider radix 16 as it has the highest information density per digit and will thus overflow the earliest:
1152 // `u8::MAX` is `ff` - any str of len 2 is guaranteed to not overflow.
1153 // `i8::MAX` is `7f` - only a str of len 1 is guaranteed to not overflow.
1154 macro_rules! run_unchecked_loop {
1155 ($unchecked_additive_op:expr) => {
1157 result = result * T::from_u32(radix);
1158 let x = (c as char).to_digit(radix).ok_or(PIE { kind: InvalidDigit })?;
1159 result = $unchecked_additive_op(result, T::from_u32(x));
1164 run_unchecked_loop!(<T as core::ops::Add>::add)
1166 run_unchecked_loop!(<T as core::ops::Sub>::sub)
1169 macro_rules! run_checked_loop {
1170 ($checked_additive_op:ident, $overflow_err:expr) => {
1172 // When `radix` is passed in as a literal, rather than doing a slow `imul`
1173 // the compiler can use shifts if `radix` can be expressed as a
1174 // sum of powers of 2 (x*10 can be written as x*8 + x*2).
1175 // When the compiler can't use these optimisations,
1176 // the latency of the multiplication can be hidden by issuing it
1177 // before the result is needed to improve performance on
1178 // modern out-of-order CPU as multiplication here is slower
1179 // than the other instructions, we can get the end result faster
1180 // doing multiplication first and let the CPU spends other cycles
1181 // doing other computation and get multiplication result later.
1182 let mul = result.checked_mul(radix);
1183 let x = (c as char).to_digit(radix).ok_or(PIE { kind: InvalidDigit })?;
1184 result = mul.ok_or_else($overflow_err)?;
1185 result = T::$checked_additive_op(&result, x).ok_or_else($overflow_err)?;
1190 run_checked_loop!(checked_add, || PIE { kind: PosOverflow })
1192 run_checked_loop!(checked_sub, || PIE { kind: NegOverflow })