1//! Numeric traits and functions for the built-in numeric types.
2
3#![stable(feature = "rust1", since = "1.0.0")]
4
5use crate::panic::const_panic;
6use crate::str::FromStr;
7use crate::ub_checks::assert_unsafe_precondition;
8use crate::{ascii, intrinsics, mem};
9
10// FIXME(const-hack): Used because the `?` operator is not allowed in a const context.
11macro_rules! try_opt {
12 ($e:expr) => {
13 match $e {
14 Some(x) => x,
15 None => return None,
16 }
17 };
18}
19
20// Use this when the generated code should differ between signed and unsigned types.
21macro_rules! sign_dependent_expr {
22 (signed ? if signed { $signed_case:expr } if unsigned { $unsigned_case:expr } ) => {
23 $signed_case
24 };
25 (unsigned ? if signed { $signed_case:expr } if unsigned { $unsigned_case:expr } ) => {
26 $unsigned_case
27 };
28}
29
30// All these modules are technically private and only exposed for coretests:
31#[cfg(not(no_fp_fmt_parse))]
32pub mod bignum;
33#[cfg(not(no_fp_fmt_parse))]
34pub mod dec2flt;
35#[cfg(not(no_fp_fmt_parse))]
36pub mod diy_float;
37#[cfg(not(no_fp_fmt_parse))]
38pub mod flt2dec;
39pub mod fmt;
40
41#[macro_use]
42mod int_macros; // import int_impl!
43#[macro_use]
44mod uint_macros; // import uint_impl!
45
46mod error;
47mod int_log10;
48mod int_sqrt;
49mod nonzero;
50mod overflow_panic;
51mod saturating;
52mod wrapping;
53
54/// 100% perma-unstable
55#[doc(hidden)]
56pub mod niche_types;
57
58#[stable(feature = "rust1", since = "1.0.0")]
59#[cfg(not(no_fp_fmt_parse))]
60pub use dec2flt::ParseFloatError;
61#[stable(feature = "int_error_matching", since = "1.55.0")]
62pub use error::IntErrorKind;
63#[stable(feature = "rust1", since = "1.0.0")]
64pub use error::ParseIntError;
65#[stable(feature = "try_from", since = "1.34.0")]
66pub use error::TryFromIntError;
67#[stable(feature = "generic_nonzero", since = "1.79.0")]
68pub use nonzero::NonZero;
69#[unstable(
70 feature = "nonzero_internals",
71 reason = "implementation detail which may disappear or be replaced at any time",
72 issue = "none"
73)]
74pub use nonzero::ZeroablePrimitive;
75#[stable(feature = "signed_nonzero", since = "1.34.0")]
76pub use nonzero::{NonZeroI8, NonZeroI16, NonZeroI32, NonZeroI64, NonZeroI128, NonZeroIsize};
77#[stable(feature = "nonzero", since = "1.28.0")]
78pub use nonzero::{NonZeroU8, NonZeroU16, NonZeroU32, NonZeroU64, NonZeroU128, NonZeroUsize};
79#[stable(feature = "saturating_int_impl", since = "1.74.0")]
80pub use saturating::Saturating;
81#[stable(feature = "rust1", since = "1.0.0")]
82pub use wrapping::Wrapping;
83
84macro_rules! u8_xe_bytes_doc {
85 () => {
86 "
87
88**Note**: This function is meaningless on `u8`. Byte order does not exist as a
89concept for byte-sized integers. This function is only provided in symmetry
90with larger integer types.
91
92"
93 };
94}
95
96macro_rules! i8_xe_bytes_doc {
97 () => {
98 "
99
100**Note**: This function is meaningless on `i8`. Byte order does not exist as a
101concept for byte-sized integers. This function is only provided in symmetry
102with larger integer types. You can cast from and to `u8` using `as i8` and `as
103u8`.
104
105"
106 };
107}
108
109macro_rules! usize_isize_to_xe_bytes_doc {
110 () => {
111 "
112
113**Note**: This function returns an array of length 2, 4 or 8 bytes
114depending on the target pointer size.
115
116"
117 };
118}
119
120macro_rules! usize_isize_from_xe_bytes_doc {
121 () => {
122 "
123
124**Note**: This function takes an array of length 2, 4 or 8 bytes
125depending on the target pointer size.
126
127"
128 };
129}
130
131macro_rules! midpoint_impl {
132 ($SelfT:ty, unsigned) => {
133 /// Calculates the middle point of `self` and `rhs`.
134 ///
135 /// `midpoint(a, b)` is `(a + b) / 2` as if it were performed in a
136 /// sufficiently-large unsigned integral type. This implies that the result is
137 /// always rounded towards zero and that no overflow will ever occur.
138 ///
139 /// # Examples
140 ///
141 /// ```
142 #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".midpoint(4), 2);")]
143 #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".midpoint(4), 2);")]
144 /// ```
145 #[stable(feature = "num_midpoint", since = "1.85.0")]
146 #[rustc_const_stable(feature = "num_midpoint", since = "1.85.0")]
147 #[must_use = "this returns the result of the operation, \
148 without modifying the original"]
149 #[inline]
150 pub const fn midpoint(self, rhs: $SelfT) -> $SelfT {
151 // Use the well known branchless algorithm from Hacker's Delight to compute
152 // `(a + b) / 2` without overflowing: `((a ^ b) >> 1) + (a & b)`.
153 ((self ^ rhs) >> 1) + (self & rhs)
154 }
155 };
156 ($SelfT:ty, signed) => {
157 /// Calculates the middle point of `self` and `rhs`.
158 ///
159 /// `midpoint(a, b)` is `(a + b) / 2` as if it were performed in a
160 /// sufficiently-large signed integral type. This implies that the result is
161 /// always rounded towards zero and that no overflow will ever occur.
162 ///
163 /// # Examples
164 ///
165 /// ```
166 #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".midpoint(4), 2);")]
167 #[doc = concat!("assert_eq!((-1", stringify!($SelfT), ").midpoint(2), 0);")]
168 #[doc = concat!("assert_eq!((-7", stringify!($SelfT), ").midpoint(0), -3);")]
169 #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".midpoint(-7), -3);")]
170 #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".midpoint(7), 3);")]
171 /// ```
172 #[stable(feature = "num_midpoint_signed", since = "1.87.0")]
173 #[rustc_const_stable(feature = "num_midpoint_signed", since = "1.87.0")]
174 #[must_use = "this returns the result of the operation, \
175 without modifying the original"]
176 #[inline]
177 pub const fn midpoint(self, rhs: Self) -> Self {
178 // Use the well known branchless algorithm from Hacker's Delight to compute
179 // `(a + b) / 2` without overflowing: `((a ^ b) >> 1) + (a & b)`.
180 let t = ((self ^ rhs) >> 1) + (self & rhs);
181 // Except that it fails for integers whose sum is an odd negative number as
182 // their floor is one less than their average. So we adjust the result.
183 t + (if t < 0 { 1 } else { 0 } & (self ^ rhs))
184 }
185 };
186 ($SelfT:ty, $WideT:ty, unsigned) => {
187 /// Calculates the middle point of `self` and `rhs`.
188 ///
189 /// `midpoint(a, b)` is `(a + b) / 2` as if it were performed in a
190 /// sufficiently-large unsigned integral type. This implies that the result is
191 /// always rounded towards zero and that no overflow will ever occur.
192 ///
193 /// # Examples
194 ///
195 /// ```
196 #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".midpoint(4), 2);")]
197 #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".midpoint(4), 2);")]
198 /// ```
199 #[stable(feature = "num_midpoint", since = "1.85.0")]
200 #[rustc_const_stable(feature = "num_midpoint", since = "1.85.0")]
201 #[must_use = "this returns the result of the operation, \
202 without modifying the original"]
203 #[inline]
204 pub const fn midpoint(self, rhs: $SelfT) -> $SelfT {
205 ((self as $WideT + rhs as $WideT) / 2) as $SelfT
206 }
207 };
208 ($SelfT:ty, $WideT:ty, signed) => {
209 /// Calculates the middle point of `self` and `rhs`.
210 ///
211 /// `midpoint(a, b)` is `(a + b) / 2` as if it were performed in a
212 /// sufficiently-large signed integral type. This implies that the result is
213 /// always rounded towards zero and that no overflow will ever occur.
214 ///
215 /// # Examples
216 ///
217 /// ```
218 #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".midpoint(4), 2);")]
219 #[doc = concat!("assert_eq!((-1", stringify!($SelfT), ").midpoint(2), 0);")]
220 #[doc = concat!("assert_eq!((-7", stringify!($SelfT), ").midpoint(0), -3);")]
221 #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".midpoint(-7), -3);")]
222 #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".midpoint(7), 3);")]
223 /// ```
224 #[stable(feature = "num_midpoint_signed", since = "1.87.0")]
225 #[rustc_const_stable(feature = "num_midpoint_signed", since = "1.87.0")]
226 #[must_use = "this returns the result of the operation, \
227 without modifying the original"]
228 #[inline]
229 pub const fn midpoint(self, rhs: $SelfT) -> $SelfT {
230 ((self as $WideT + rhs as $WideT) / 2) as $SelfT
231 }
232 };
233}
234
235impl i8 {
236 int_impl! {
237 Self = i8,
238 ActualT = i8,
239 UnsignedT = u8,
240 BITS = 8,
241 BITS_MINUS_ONE = 7,
242 Min = -128,
243 Max = 127,
244 rot = 2,
245 rot_op = "-0x7e",
246 rot_result = "0xa",
247 swap_op = "0x12",
248 swapped = "0x12",
249 reversed = "0x48",
250 le_bytes = "[0x12]",
251 be_bytes = "[0x12]",
252 to_xe_bytes_doc = i8_xe_bytes_doc!(),
253 from_xe_bytes_doc = i8_xe_bytes_doc!(),
254 bound_condition = "",
255 }
256 midpoint_impl! { i8, i16, signed }
257}
258
259impl i16 {
260 int_impl! {
261 Self = i16,
262 ActualT = i16,
263 UnsignedT = u16,
264 BITS = 16,
265 BITS_MINUS_ONE = 15,
266 Min = -32768,
267 Max = 32767,
268 rot = 4,
269 rot_op = "-0x5ffd",
270 rot_result = "0x3a",
271 swap_op = "0x1234",
272 swapped = "0x3412",
273 reversed = "0x2c48",
274 le_bytes = "[0x34, 0x12]",
275 be_bytes = "[0x12, 0x34]",
276 to_xe_bytes_doc = "",
277 from_xe_bytes_doc = "",
278 bound_condition = "",
279 }
280 midpoint_impl! { i16, i32, signed }
281}
282
283impl i32 {
284 int_impl! {
285 Self = i32,
286 ActualT = i32,
287 UnsignedT = u32,
288 BITS = 32,
289 BITS_MINUS_ONE = 31,
290 Min = -2147483648,
291 Max = 2147483647,
292 rot = 8,
293 rot_op = "0x10000b3",
294 rot_result = "0xb301",
295 swap_op = "0x12345678",
296 swapped = "0x78563412",
297 reversed = "0x1e6a2c48",
298 le_bytes = "[0x78, 0x56, 0x34, 0x12]",
299 be_bytes = "[0x12, 0x34, 0x56, 0x78]",
300 to_xe_bytes_doc = "",
301 from_xe_bytes_doc = "",
302 bound_condition = "",
303 }
304 midpoint_impl! { i32, i64, signed }
305}
306
307impl i64 {
308 int_impl! {
309 Self = i64,
310 ActualT = i64,
311 UnsignedT = u64,
312 BITS = 64,
313 BITS_MINUS_ONE = 63,
314 Min = -9223372036854775808,
315 Max = 9223372036854775807,
316 rot = 12,
317 rot_op = "0xaa00000000006e1",
318 rot_result = "0x6e10aa",
319 swap_op = "0x1234567890123456",
320 swapped = "0x5634129078563412",
321 reversed = "0x6a2c48091e6a2c48",
322 le_bytes = "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
323 be_bytes = "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
324 to_xe_bytes_doc = "",
325 from_xe_bytes_doc = "",
326 bound_condition = "",
327 }
328 midpoint_impl! { i64, signed }
329}
330
331impl i128 {
332 int_impl! {
333 Self = i128,
334 ActualT = i128,
335 UnsignedT = u128,
336 BITS = 128,
337 BITS_MINUS_ONE = 127,
338 Min = -170141183460469231731687303715884105728,
339 Max = 170141183460469231731687303715884105727,
340 rot = 16,
341 rot_op = "0x13f40000000000000000000000004f76",
342 rot_result = "0x4f7613f4",
343 swap_op = "0x12345678901234567890123456789012",
344 swapped = "0x12907856341290785634129078563412",
345 reversed = "0x48091e6a2c48091e6a2c48091e6a2c48",
346 le_bytes = "[0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, \
347 0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
348 be_bytes = "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56, \
349 0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12]",
350 to_xe_bytes_doc = "",
351 from_xe_bytes_doc = "",
352 bound_condition = "",
353 }
354 midpoint_impl! { i128, signed }
355}
356
357#[cfg(target_pointer_width = "16")]
358impl isize {
359 int_impl! {
360 Self = isize,
361 ActualT = i16,
362 UnsignedT = usize,
363 BITS = 16,
364 BITS_MINUS_ONE = 15,
365 Min = -32768,
366 Max = 32767,
367 rot = 4,
368 rot_op = "-0x5ffd",
369 rot_result = "0x3a",
370 swap_op = "0x1234",
371 swapped = "0x3412",
372 reversed = "0x2c48",
373 le_bytes = "[0x34, 0x12]",
374 be_bytes = "[0x12, 0x34]",
375 to_xe_bytes_doc = usize_isize_to_xe_bytes_doc!(),
376 from_xe_bytes_doc = usize_isize_from_xe_bytes_doc!(),
377 bound_condition = " on 16-bit targets",
378 }
379 midpoint_impl! { isize, i32, signed }
380}
381
382#[cfg(target_pointer_width = "32")]
383impl isize {
384 int_impl! {
385 Self = isize,
386 ActualT = i32,
387 UnsignedT = usize,
388 BITS = 32,
389 BITS_MINUS_ONE = 31,
390 Min = -2147483648,
391 Max = 2147483647,
392 rot = 8,
393 rot_op = "0x10000b3",
394 rot_result = "0xb301",
395 swap_op = "0x12345678",
396 swapped = "0x78563412",
397 reversed = "0x1e6a2c48",
398 le_bytes = "[0x78, 0x56, 0x34, 0x12]",
399 be_bytes = "[0x12, 0x34, 0x56, 0x78]",
400 to_xe_bytes_doc = usize_isize_to_xe_bytes_doc!(),
401 from_xe_bytes_doc = usize_isize_from_xe_bytes_doc!(),
402 bound_condition = " on 32-bit targets",
403 }
404 midpoint_impl! { isize, i64, signed }
405}
406
407#[cfg(target_pointer_width = "64")]
408impl isize {
409 int_impl! {
410 Self = isize,
411 ActualT = i64,
412 UnsignedT = usize,
413 BITS = 64,
414 BITS_MINUS_ONE = 63,
415 Min = -9223372036854775808,
416 Max = 9223372036854775807,
417 rot = 12,
418 rot_op = "0xaa00000000006e1",
419 rot_result = "0x6e10aa",
420 swap_op = "0x1234567890123456",
421 swapped = "0x5634129078563412",
422 reversed = "0x6a2c48091e6a2c48",
423 le_bytes = "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
424 be_bytes = "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
425 to_xe_bytes_doc = usize_isize_to_xe_bytes_doc!(),
426 from_xe_bytes_doc = usize_isize_from_xe_bytes_doc!(),
427 bound_condition = " on 64-bit targets",
428 }
429 midpoint_impl! { isize, signed }
430}
431
432/// If the bit selected by this mask is set, ascii is lower case.
433const ASCII_CASE_MASK: u8 = 0b0010_0000;
434
435impl u8 {
436 uint_impl! {
437 Self = u8,
438 ActualT = u8,
439 SignedT = i8,
440 BITS = 8,
441 BITS_MINUS_ONE = 7,
442 MAX = 255,
443 rot = 2,
444 rot_op = "0x82",
445 rot_result = "0xa",
446 swap_op = "0x12",
447 swapped = "0x12",
448 reversed = "0x48",
449 le_bytes = "[0x12]",
450 be_bytes = "[0x12]",
451 to_xe_bytes_doc = u8_xe_bytes_doc!(),
452 from_xe_bytes_doc = u8_xe_bytes_doc!(),
453 bound_condition = "",
454 }
455 midpoint_impl! { u8, u16, unsigned }
456
457 /// Checks if the value is within the ASCII range.
458 ///
459 /// # Examples
460 ///
461 /// ```
462 /// let ascii = 97u8;
463 /// let non_ascii = 150u8;
464 ///
465 /// assert!(ascii.is_ascii());
466 /// assert!(!non_ascii.is_ascii());
467 /// ```
468 #[must_use]
469 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
470 #[rustc_const_stable(feature = "const_u8_is_ascii", since = "1.43.0")]
471 #[inline]
472 pub const fn is_ascii(&self) -> bool {
473 *self <= 127
474 }
475
476 /// If the value of this byte is within the ASCII range, returns it as an
477 /// [ASCII character](ascii::Char). Otherwise, returns `None`.
478 #[must_use]
479 #[unstable(feature = "ascii_char", issue = "110998")]
480 #[inline]
481 pub const fn as_ascii(&self) -> Option<ascii::Char> {
482 ascii::Char::from_u8(*self)
483 }
484
485 /// Makes a copy of the value in its ASCII upper case equivalent.
486 ///
487 /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
488 /// but non-ASCII letters are unchanged.
489 ///
490 /// To uppercase the value in-place, use [`make_ascii_uppercase`].
491 ///
492 /// # Examples
493 ///
494 /// ```
495 /// let lowercase_a = 97u8;
496 ///
497 /// assert_eq!(65, lowercase_a.to_ascii_uppercase());
498 /// ```
499 ///
500 /// [`make_ascii_uppercase`]: Self::make_ascii_uppercase
501 #[must_use = "to uppercase the value in-place, use `make_ascii_uppercase()`"]
502 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
503 #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")]
504 #[inline]
505 pub const fn to_ascii_uppercase(&self) -> u8 {
506 // Toggle the 6th bit if this is a lowercase letter
507 *self ^ ((self.is_ascii_lowercase() as u8) * ASCII_CASE_MASK)
508 }
509
510 /// Makes a copy of the value in its ASCII lower case equivalent.
511 ///
512 /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
513 /// but non-ASCII letters are unchanged.
514 ///
515 /// To lowercase the value in-place, use [`make_ascii_lowercase`].
516 ///
517 /// # Examples
518 ///
519 /// ```
520 /// let uppercase_a = 65u8;
521 ///
522 /// assert_eq!(97, uppercase_a.to_ascii_lowercase());
523 /// ```
524 ///
525 /// [`make_ascii_lowercase`]: Self::make_ascii_lowercase
526 #[must_use = "to lowercase the value in-place, use `make_ascii_lowercase()`"]
527 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
528 #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")]
529 #[inline]
530 pub const fn to_ascii_lowercase(&self) -> u8 {
531 // Set the 6th bit if this is an uppercase letter
532 *self | (self.is_ascii_uppercase() as u8 * ASCII_CASE_MASK)
533 }
534
535 /// Assumes self is ascii
536 #[inline]
537 pub(crate) const fn ascii_change_case_unchecked(&self) -> u8 {
538 *self ^ ASCII_CASE_MASK
539 }
540
541 /// Checks that two values are an ASCII case-insensitive match.
542 ///
543 /// This is equivalent to `to_ascii_lowercase(a) == to_ascii_lowercase(b)`.
544 ///
545 /// # Examples
546 ///
547 /// ```
548 /// let lowercase_a = 97u8;
549 /// let uppercase_a = 65u8;
550 ///
551 /// assert!(lowercase_a.eq_ignore_ascii_case(&uppercase_a));
552 /// ```
553 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
554 #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")]
555 #[inline]
556 pub const fn eq_ignore_ascii_case(&self, other: &u8) -> bool {
557 self.to_ascii_lowercase() == other.to_ascii_lowercase()
558 }
559
560 /// Converts this value to its ASCII upper case equivalent in-place.
561 ///
562 /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
563 /// but non-ASCII letters are unchanged.
564 ///
565 /// To return a new uppercased value without modifying the existing one, use
566 /// [`to_ascii_uppercase`].
567 ///
568 /// # Examples
569 ///
570 /// ```
571 /// let mut byte = b'a';
572 ///
573 /// byte.make_ascii_uppercase();
574 ///
575 /// assert_eq!(b'A', byte);
576 /// ```
577 ///
578 /// [`to_ascii_uppercase`]: Self::to_ascii_uppercase
579 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
580 #[rustc_const_stable(feature = "const_make_ascii", since = "1.84.0")]
581 #[inline]
582 pub const fn make_ascii_uppercase(&mut self) {
583 *self = self.to_ascii_uppercase();
584 }
585
586 /// Converts this value to its ASCII lower case equivalent in-place.
587 ///
588 /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
589 /// but non-ASCII letters are unchanged.
590 ///
591 /// To return a new lowercased value without modifying the existing one, use
592 /// [`to_ascii_lowercase`].
593 ///
594 /// # Examples
595 ///
596 /// ```
597 /// let mut byte = b'A';
598 ///
599 /// byte.make_ascii_lowercase();
600 ///
601 /// assert_eq!(b'a', byte);
602 /// ```
603 ///
604 /// [`to_ascii_lowercase`]: Self::to_ascii_lowercase
605 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
606 #[rustc_const_stable(feature = "const_make_ascii", since = "1.84.0")]
607 #[inline]
608 pub const fn make_ascii_lowercase(&mut self) {
609 *self = self.to_ascii_lowercase();
610 }
611
612 /// Checks if the value is an ASCII alphabetic character:
613 ///
614 /// - U+0041 'A' ..= U+005A 'Z', or
615 /// - U+0061 'a' ..= U+007A 'z'.
616 ///
617 /// # Examples
618 ///
619 /// ```
620 /// let uppercase_a = b'A';
621 /// let uppercase_g = b'G';
622 /// let a = b'a';
623 /// let g = b'g';
624 /// let zero = b'0';
625 /// let percent = b'%';
626 /// let space = b' ';
627 /// let lf = b'\n';
628 /// let esc = b'\x1b';
629 ///
630 /// assert!(uppercase_a.is_ascii_alphabetic());
631 /// assert!(uppercase_g.is_ascii_alphabetic());
632 /// assert!(a.is_ascii_alphabetic());
633 /// assert!(g.is_ascii_alphabetic());
634 /// assert!(!zero.is_ascii_alphabetic());
635 /// assert!(!percent.is_ascii_alphabetic());
636 /// assert!(!space.is_ascii_alphabetic());
637 /// assert!(!lf.is_ascii_alphabetic());
638 /// assert!(!esc.is_ascii_alphabetic());
639 /// ```
640 #[must_use]
641 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
642 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
643 #[inline]
644 pub const fn is_ascii_alphabetic(&self) -> bool {
645 matches!(*self, b'A'..=b'Z' | b'a'..=b'z')
646 }
647
648 /// Checks if the value is an ASCII uppercase character:
649 /// U+0041 'A' ..= U+005A 'Z'.
650 ///
651 /// # Examples
652 ///
653 /// ```
654 /// let uppercase_a = b'A';
655 /// let uppercase_g = b'G';
656 /// let a = b'a';
657 /// let g = b'g';
658 /// let zero = b'0';
659 /// let percent = b'%';
660 /// let space = b' ';
661 /// let lf = b'\n';
662 /// let esc = b'\x1b';
663 ///
664 /// assert!(uppercase_a.is_ascii_uppercase());
665 /// assert!(uppercase_g.is_ascii_uppercase());
666 /// assert!(!a.is_ascii_uppercase());
667 /// assert!(!g.is_ascii_uppercase());
668 /// assert!(!zero.is_ascii_uppercase());
669 /// assert!(!percent.is_ascii_uppercase());
670 /// assert!(!space.is_ascii_uppercase());
671 /// assert!(!lf.is_ascii_uppercase());
672 /// assert!(!esc.is_ascii_uppercase());
673 /// ```
674 #[must_use]
675 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
676 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
677 #[inline]
678 pub const fn is_ascii_uppercase(&self) -> bool {
679 matches!(*self, b'A'..=b'Z')
680 }
681
682 /// Checks if the value is an ASCII lowercase character:
683 /// U+0061 'a' ..= U+007A 'z'.
684 ///
685 /// # Examples
686 ///
687 /// ```
688 /// let uppercase_a = b'A';
689 /// let uppercase_g = b'G';
690 /// let a = b'a';
691 /// let g = b'g';
692 /// let zero = b'0';
693 /// let percent = b'%';
694 /// let space = b' ';
695 /// let lf = b'\n';
696 /// let esc = b'\x1b';
697 ///
698 /// assert!(!uppercase_a.is_ascii_lowercase());
699 /// assert!(!uppercase_g.is_ascii_lowercase());
700 /// assert!(a.is_ascii_lowercase());
701 /// assert!(g.is_ascii_lowercase());
702 /// assert!(!zero.is_ascii_lowercase());
703 /// assert!(!percent.is_ascii_lowercase());
704 /// assert!(!space.is_ascii_lowercase());
705 /// assert!(!lf.is_ascii_lowercase());
706 /// assert!(!esc.is_ascii_lowercase());
707 /// ```
708 #[must_use]
709 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
710 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
711 #[inline]
712 pub const fn is_ascii_lowercase(&self) -> bool {
713 matches!(*self, b'a'..=b'z')
714 }
715
716 /// Checks if the value is an ASCII alphanumeric character:
717 ///
718 /// - U+0041 'A' ..= U+005A 'Z', or
719 /// - U+0061 'a' ..= U+007A 'z', or
720 /// - U+0030 '0' ..= U+0039 '9'.
721 ///
722 /// # Examples
723 ///
724 /// ```
725 /// let uppercase_a = b'A';
726 /// let uppercase_g = b'G';
727 /// let a = b'a';
728 /// let g = b'g';
729 /// let zero = b'0';
730 /// let percent = b'%';
731 /// let space = b' ';
732 /// let lf = b'\n';
733 /// let esc = b'\x1b';
734 ///
735 /// assert!(uppercase_a.is_ascii_alphanumeric());
736 /// assert!(uppercase_g.is_ascii_alphanumeric());
737 /// assert!(a.is_ascii_alphanumeric());
738 /// assert!(g.is_ascii_alphanumeric());
739 /// assert!(zero.is_ascii_alphanumeric());
740 /// assert!(!percent.is_ascii_alphanumeric());
741 /// assert!(!space.is_ascii_alphanumeric());
742 /// assert!(!lf.is_ascii_alphanumeric());
743 /// assert!(!esc.is_ascii_alphanumeric());
744 /// ```
745 #[must_use]
746 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
747 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
748 #[inline]
749 pub const fn is_ascii_alphanumeric(&self) -> bool {
750 matches!(*self, b'0'..=b'9') | matches!(*self, b'A'..=b'Z') | matches!(*self, b'a'..=b'z')
751 }
752
753 /// Checks if the value is an ASCII decimal digit:
754 /// U+0030 '0' ..= U+0039 '9'.
755 ///
756 /// # Examples
757 ///
758 /// ```
759 /// let uppercase_a = b'A';
760 /// let uppercase_g = b'G';
761 /// let a = b'a';
762 /// let g = b'g';
763 /// let zero = b'0';
764 /// let percent = b'%';
765 /// let space = b' ';
766 /// let lf = b'\n';
767 /// let esc = b'\x1b';
768 ///
769 /// assert!(!uppercase_a.is_ascii_digit());
770 /// assert!(!uppercase_g.is_ascii_digit());
771 /// assert!(!a.is_ascii_digit());
772 /// assert!(!g.is_ascii_digit());
773 /// assert!(zero.is_ascii_digit());
774 /// assert!(!percent.is_ascii_digit());
775 /// assert!(!space.is_ascii_digit());
776 /// assert!(!lf.is_ascii_digit());
777 /// assert!(!esc.is_ascii_digit());
778 /// ```
779 #[must_use]
780 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
781 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
782 #[inline]
783 pub const fn is_ascii_digit(&self) -> bool {
784 matches!(*self, b'0'..=b'9')
785 }
786
787 /// Checks if the value is an ASCII octal digit:
788 /// U+0030 '0' ..= U+0037 '7'.
789 ///
790 /// # Examples
791 ///
792 /// ```
793 /// #![feature(is_ascii_octdigit)]
794 ///
795 /// let uppercase_a = b'A';
796 /// let a = b'a';
797 /// let zero = b'0';
798 /// let seven = b'7';
799 /// let nine = b'9';
800 /// let percent = b'%';
801 /// let lf = b'\n';
802 ///
803 /// assert!(!uppercase_a.is_ascii_octdigit());
804 /// assert!(!a.is_ascii_octdigit());
805 /// assert!(zero.is_ascii_octdigit());
806 /// assert!(seven.is_ascii_octdigit());
807 /// assert!(!nine.is_ascii_octdigit());
808 /// assert!(!percent.is_ascii_octdigit());
809 /// assert!(!lf.is_ascii_octdigit());
810 /// ```
811 #[must_use]
812 #[unstable(feature = "is_ascii_octdigit", issue = "101288")]
813 #[inline]
814 pub const fn is_ascii_octdigit(&self) -> bool {
815 matches!(*self, b'0'..=b'7')
816 }
817
818 /// Checks if the value is an ASCII hexadecimal digit:
819 ///
820 /// - U+0030 '0' ..= U+0039 '9', or
821 /// - U+0041 'A' ..= U+0046 'F', or
822 /// - U+0061 'a' ..= U+0066 'f'.
823 ///
824 /// # Examples
825 ///
826 /// ```
827 /// let uppercase_a = b'A';
828 /// let uppercase_g = b'G';
829 /// let a = b'a';
830 /// let g = b'g';
831 /// let zero = b'0';
832 /// let percent = b'%';
833 /// let space = b' ';
834 /// let lf = b'\n';
835 /// let esc = b'\x1b';
836 ///
837 /// assert!(uppercase_a.is_ascii_hexdigit());
838 /// assert!(!uppercase_g.is_ascii_hexdigit());
839 /// assert!(a.is_ascii_hexdigit());
840 /// assert!(!g.is_ascii_hexdigit());
841 /// assert!(zero.is_ascii_hexdigit());
842 /// assert!(!percent.is_ascii_hexdigit());
843 /// assert!(!space.is_ascii_hexdigit());
844 /// assert!(!lf.is_ascii_hexdigit());
845 /// assert!(!esc.is_ascii_hexdigit());
846 /// ```
847 #[must_use]
848 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
849 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
850 #[inline]
851 pub const fn is_ascii_hexdigit(&self) -> bool {
852 matches!(*self, b'0'..=b'9') | matches!(*self, b'A'..=b'F') | matches!(*self, b'a'..=b'f')
853 }
854
855 /// Checks if the value is an ASCII punctuation character:
856 ///
857 /// - U+0021 ..= U+002F `! " # $ % & ' ( ) * + , - . /`, or
858 /// - U+003A ..= U+0040 `: ; < = > ? @`, or
859 /// - U+005B ..= U+0060 `` [ \ ] ^ _ ` ``, or
860 /// - U+007B ..= U+007E `{ | } ~`
861 ///
862 /// # Examples
863 ///
864 /// ```
865 /// let uppercase_a = b'A';
866 /// let uppercase_g = b'G';
867 /// let a = b'a';
868 /// let g = b'g';
869 /// let zero = b'0';
870 /// let percent = b'%';
871 /// let space = b' ';
872 /// let lf = b'\n';
873 /// let esc = b'\x1b';
874 ///
875 /// assert!(!uppercase_a.is_ascii_punctuation());
876 /// assert!(!uppercase_g.is_ascii_punctuation());
877 /// assert!(!a.is_ascii_punctuation());
878 /// assert!(!g.is_ascii_punctuation());
879 /// assert!(!zero.is_ascii_punctuation());
880 /// assert!(percent.is_ascii_punctuation());
881 /// assert!(!space.is_ascii_punctuation());
882 /// assert!(!lf.is_ascii_punctuation());
883 /// assert!(!esc.is_ascii_punctuation());
884 /// ```
885 #[must_use]
886 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
887 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
888 #[inline]
889 pub const fn is_ascii_punctuation(&self) -> bool {
890 matches!(*self, b'!'..=b'/')
891 | matches!(*self, b':'..=b'@')
892 | matches!(*self, b'['..=b'`')
893 | matches!(*self, b'{'..=b'~')
894 }
895
896 /// Checks if the value is an ASCII graphic character:
897 /// U+0021 '!' ..= U+007E '~'.
898 ///
899 /// # Examples
900 ///
901 /// ```
902 /// let uppercase_a = b'A';
903 /// let uppercase_g = b'G';
904 /// let a = b'a';
905 /// let g = b'g';
906 /// let zero = b'0';
907 /// let percent = b'%';
908 /// let space = b' ';
909 /// let lf = b'\n';
910 /// let esc = b'\x1b';
911 ///
912 /// assert!(uppercase_a.is_ascii_graphic());
913 /// assert!(uppercase_g.is_ascii_graphic());
914 /// assert!(a.is_ascii_graphic());
915 /// assert!(g.is_ascii_graphic());
916 /// assert!(zero.is_ascii_graphic());
917 /// assert!(percent.is_ascii_graphic());
918 /// assert!(!space.is_ascii_graphic());
919 /// assert!(!lf.is_ascii_graphic());
920 /// assert!(!esc.is_ascii_graphic());
921 /// ```
922 #[must_use]
923 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
924 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
925 #[inline]
926 pub const fn is_ascii_graphic(&self) -> bool {
927 matches!(*self, b'!'..=b'~')
928 }
929
930 /// Checks if the value is an ASCII whitespace character:
931 /// U+0020 SPACE, U+0009 HORIZONTAL TAB, U+000A LINE FEED,
932 /// U+000C FORM FEED, or U+000D CARRIAGE RETURN.
933 ///
934 /// Rust uses the WhatWG Infra Standard's [definition of ASCII
935 /// whitespace][infra-aw]. There are several other definitions in
936 /// wide use. For instance, [the POSIX locale][pct] includes
937 /// U+000B VERTICAL TAB as well as all the above characters,
938 /// but—from the very same specification—[the default rule for
939 /// "field splitting" in the Bourne shell][bfs] considers *only*
940 /// SPACE, HORIZONTAL TAB, and LINE FEED as whitespace.
941 ///
942 /// If you are writing a program that will process an existing
943 /// file format, check what that format's definition of whitespace is
944 /// before using this function.
945 ///
946 /// [infra-aw]: https://infra.spec.whatwg.org/#ascii-whitespace
947 /// [pct]: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html#tag_07_03_01
948 /// [bfs]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_05
949 ///
950 /// # Examples
951 ///
952 /// ```
953 /// let uppercase_a = b'A';
954 /// let uppercase_g = b'G';
955 /// let a = b'a';
956 /// let g = b'g';
957 /// let zero = b'0';
958 /// let percent = b'%';
959 /// let space = b' ';
960 /// let lf = b'\n';
961 /// let esc = b'\x1b';
962 ///
963 /// assert!(!uppercase_a.is_ascii_whitespace());
964 /// assert!(!uppercase_g.is_ascii_whitespace());
965 /// assert!(!a.is_ascii_whitespace());
966 /// assert!(!g.is_ascii_whitespace());
967 /// assert!(!zero.is_ascii_whitespace());
968 /// assert!(!percent.is_ascii_whitespace());
969 /// assert!(space.is_ascii_whitespace());
970 /// assert!(lf.is_ascii_whitespace());
971 /// assert!(!esc.is_ascii_whitespace());
972 /// ```
973 #[must_use]
974 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
975 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
976 #[inline]
977 pub const fn is_ascii_whitespace(&self) -> bool {
978 matches!(*self, b'\t' | b'\n' | b'\x0C' | b'\r' | b' ')
979 }
980
981 /// Checks if the value is an ASCII control character:
982 /// U+0000 NUL ..= U+001F UNIT SEPARATOR, or U+007F DELETE.
983 /// Note that most ASCII whitespace characters are control
984 /// characters, but SPACE is not.
985 ///
986 /// # Examples
987 ///
988 /// ```
989 /// let uppercase_a = b'A';
990 /// let uppercase_g = b'G';
991 /// let a = b'a';
992 /// let g = b'g';
993 /// let zero = b'0';
994 /// let percent = b'%';
995 /// let space = b' ';
996 /// let lf = b'\n';
997 /// let esc = b'\x1b';
998 ///
999 /// assert!(!uppercase_a.is_ascii_control());
1000 /// assert!(!uppercase_g.is_ascii_control());
1001 /// assert!(!a.is_ascii_control());
1002 /// assert!(!g.is_ascii_control());
1003 /// assert!(!zero.is_ascii_control());
1004 /// assert!(!percent.is_ascii_control());
1005 /// assert!(!space.is_ascii_control());
1006 /// assert!(lf.is_ascii_control());
1007 /// assert!(esc.is_ascii_control());
1008 /// ```
1009 #[must_use]
1010 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
1011 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
1012 #[inline]
1013 pub const fn is_ascii_control(&self) -> bool {
1014 matches!(*self, b'\0'..=b'\x1F' | b'\x7F')
1015 }
1016
1017 /// Returns an iterator that produces an escaped version of a `u8`,
1018 /// treating it as an ASCII character.
1019 ///
1020 /// The behavior is identical to [`ascii::escape_default`].
1021 ///
1022 /// # Examples
1023 ///
1024 /// ```
1025 ///
1026 /// assert_eq!("0", b'0'.escape_ascii().to_string());
1027 /// assert_eq!("\\t", b'\t'.escape_ascii().to_string());
1028 /// assert_eq!("\\r", b'\r'.escape_ascii().to_string());
1029 /// assert_eq!("\\n", b'\n'.escape_ascii().to_string());
1030 /// assert_eq!("\\'", b'\''.escape_ascii().to_string());
1031 /// assert_eq!("\\\"", b'"'.escape_ascii().to_string());
1032 /// assert_eq!("\\\\", b'\\'.escape_ascii().to_string());
1033 /// assert_eq!("\\x9d", b'\x9d'.escape_ascii().to_string());
1034 /// ```
1035 #[must_use = "this returns the escaped byte as an iterator, \
1036 without modifying the original"]
1037 #[stable(feature = "inherent_ascii_escape", since = "1.60.0")]
1038 #[inline]
1039 pub fn escape_ascii(self) -> ascii::EscapeDefault {
1040 ascii::escape_default(self)
1041 }
1042
1043 #[inline]
1044 pub(crate) const fn is_utf8_char_boundary(self) -> bool {
1045 // This is bit magic equivalent to: b < 128 || b >= 192
1046 (self as i8) >= -0x40
1047 }
1048}
1049
1050impl u16 {
1051 uint_impl! {
1052 Self = u16,
1053 ActualT = u16,
1054 SignedT = i16,
1055 BITS = 16,
1056 BITS_MINUS_ONE = 15,
1057 MAX = 65535,
1058 rot = 4,
1059 rot_op = "0xa003",
1060 rot_result = "0x3a",
1061 swap_op = "0x1234",
1062 swapped = "0x3412",
1063 reversed = "0x2c48",
1064 le_bytes = "[0x34, 0x12]",
1065 be_bytes = "[0x12, 0x34]",
1066 to_xe_bytes_doc = "",
1067 from_xe_bytes_doc = "",
1068 bound_condition = "",
1069 }
1070 midpoint_impl! { u16, u32, unsigned }
1071
1072 /// Checks if the value is a Unicode surrogate code point, which are disallowed values for [`char`].
1073 ///
1074 /// # Examples
1075 ///
1076 /// ```
1077 /// #![feature(utf16_extra)]
1078 ///
1079 /// let low_non_surrogate = 0xA000u16;
1080 /// let low_surrogate = 0xD800u16;
1081 /// let high_surrogate = 0xDC00u16;
1082 /// let high_non_surrogate = 0xE000u16;
1083 ///
1084 /// assert!(!low_non_surrogate.is_utf16_surrogate());
1085 /// assert!(low_surrogate.is_utf16_surrogate());
1086 /// assert!(high_surrogate.is_utf16_surrogate());
1087 /// assert!(!high_non_surrogate.is_utf16_surrogate());
1088 /// ```
1089 #[must_use]
1090 #[unstable(feature = "utf16_extra", issue = "94919")]
1091 #[inline]
1092 pub const fn is_utf16_surrogate(self) -> bool {
1093 matches!(self, 0xD800..=0xDFFF)
1094 }
1095}
1096
1097impl u32 {
1098 uint_impl! {
1099 Self = u32,
1100 ActualT = u32,
1101 SignedT = i32,
1102 BITS = 32,
1103 BITS_MINUS_ONE = 31,
1104 MAX = 4294967295,
1105 rot = 8,
1106 rot_op = "0x10000b3",
1107 rot_result = "0xb301",
1108 swap_op = "0x12345678",
1109 swapped = "0x78563412",
1110 reversed = "0x1e6a2c48",
1111 le_bytes = "[0x78, 0x56, 0x34, 0x12]",
1112 be_bytes = "[0x12, 0x34, 0x56, 0x78]",
1113 to_xe_bytes_doc = "",
1114 from_xe_bytes_doc = "",
1115 bound_condition = "",
1116 }
1117 midpoint_impl! { u32, u64, unsigned }
1118}
1119
1120impl u64 {
1121 uint_impl! {
1122 Self = u64,
1123 ActualT = u64,
1124 SignedT = i64,
1125 BITS = 64,
1126 BITS_MINUS_ONE = 63,
1127 MAX = 18446744073709551615,
1128 rot = 12,
1129 rot_op = "0xaa00000000006e1",
1130 rot_result = "0x6e10aa",
1131 swap_op = "0x1234567890123456",
1132 swapped = "0x5634129078563412",
1133 reversed = "0x6a2c48091e6a2c48",
1134 le_bytes = "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
1135 be_bytes = "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
1136 to_xe_bytes_doc = "",
1137 from_xe_bytes_doc = "",
1138 bound_condition = "",
1139 }
1140 midpoint_impl! { u64, u128, unsigned }
1141}
1142
1143impl u128 {
1144 uint_impl! {
1145 Self = u128,
1146 ActualT = u128,
1147 SignedT = i128,
1148 BITS = 128,
1149 BITS_MINUS_ONE = 127,
1150 MAX = 340282366920938463463374607431768211455,
1151 rot = 16,
1152 rot_op = "0x13f40000000000000000000000004f76",
1153 rot_result = "0x4f7613f4",
1154 swap_op = "0x12345678901234567890123456789012",
1155 swapped = "0x12907856341290785634129078563412",
1156 reversed = "0x48091e6a2c48091e6a2c48091e6a2c48",
1157 le_bytes = "[0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, \
1158 0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
1159 be_bytes = "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56, \
1160 0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12]",
1161 to_xe_bytes_doc = "",
1162 from_xe_bytes_doc = "",
1163 bound_condition = "",
1164 }
1165 midpoint_impl! { u128, unsigned }
1166}
1167
1168#[cfg(target_pointer_width = "16")]
1169impl usize {
1170 uint_impl! {
1171 Self = usize,
1172 ActualT = u16,
1173 SignedT = isize,
1174 BITS = 16,
1175 BITS_MINUS_ONE = 15,
1176 MAX = 65535,
1177 rot = 4,
1178 rot_op = "0xa003",
1179 rot_result = "0x3a",
1180 swap_op = "0x1234",
1181 swapped = "0x3412",
1182 reversed = "0x2c48",
1183 le_bytes = "[0x34, 0x12]",
1184 be_bytes = "[0x12, 0x34]",
1185 to_xe_bytes_doc = usize_isize_to_xe_bytes_doc!(),
1186 from_xe_bytes_doc = usize_isize_from_xe_bytes_doc!(),
1187 bound_condition = " on 16-bit targets",
1188 }
1189 midpoint_impl! { usize, u32, unsigned }
1190}
1191
1192#[cfg(target_pointer_width = "32")]
1193impl usize {
1194 uint_impl! {
1195 Self = usize,
1196 ActualT = u32,
1197 SignedT = isize,
1198 BITS = 32,
1199 BITS_MINUS_ONE = 31,
1200 MAX = 4294967295,
1201 rot = 8,
1202 rot_op = "0x10000b3",
1203 rot_result = "0xb301",
1204 swap_op = "0x12345678",
1205 swapped = "0x78563412",
1206 reversed = "0x1e6a2c48",
1207 le_bytes = "[0x78, 0x56, 0x34, 0x12]",
1208 be_bytes = "[0x12, 0x34, 0x56, 0x78]",
1209 to_xe_bytes_doc = usize_isize_to_xe_bytes_doc!(),
1210 from_xe_bytes_doc = usize_isize_from_xe_bytes_doc!(),
1211 bound_condition = " on 32-bit targets",
1212 }
1213 midpoint_impl! { usize, u64, unsigned }
1214}
1215
1216#[cfg(target_pointer_width = "64")]
1217impl usize {
1218 uint_impl! {
1219 Self = usize,
1220 ActualT = u64,
1221 SignedT = isize,
1222 BITS = 64,
1223 BITS_MINUS_ONE = 63,
1224 MAX = 18446744073709551615,
1225 rot = 12,
1226 rot_op = "0xaa00000000006e1",
1227 rot_result = "0x6e10aa",
1228 swap_op = "0x1234567890123456",
1229 swapped = "0x5634129078563412",
1230 reversed = "0x6a2c48091e6a2c48",
1231 le_bytes = "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
1232 be_bytes = "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
1233 to_xe_bytes_doc = usize_isize_to_xe_bytes_doc!(),
1234 from_xe_bytes_doc = usize_isize_from_xe_bytes_doc!(),
1235 bound_condition = " on 64-bit targets",
1236 }
1237 midpoint_impl! { usize, u128, unsigned }
1238}
1239
1240impl usize {
1241 /// Returns an `usize` where every byte is equal to `x`.
1242 #[inline]
1243 pub(crate) const fn repeat_u8(x: u8) -> usize {
1244 usize::from_ne_bytes([x; size_of::<usize>()])
1245 }
1246
1247 /// Returns an `usize` where every byte pair is equal to `x`.
1248 #[inline]
1249 pub(crate) const fn repeat_u16(x: u16) -> usize {
1250 let mut r: usize = 0usize;
1251 let mut i: usize = 0;
1252 while i < size_of::<usize>() {
1253 // Use `wrapping_shl` to make it work on targets with 16-bit `usize`
1254 r = r.wrapping_shl(16) | (x as usize);
1255 i += 2;
1256 }
1257 r
1258 }
1259}
1260
1261/// A classification of floating point numbers.
1262///
1263/// This `enum` is used as the return type for [`f32::classify`] and [`f64::classify`]. See
1264/// their documentation for more.
1265///
1266/// # Examples
1267///
1268/// ```
1269/// use std::num::FpCategory;
1270///
1271/// let num = 12.4_f32;
1272/// let inf = f32::INFINITY;
1273/// let zero = 0f32;
1274/// let sub: f32 = 1.1754942e-38;
1275/// let nan = f32::NAN;
1276///
1277/// assert_eq!(num.classify(), FpCategory::Normal);
1278/// assert_eq!(inf.classify(), FpCategory::Infinite);
1279/// assert_eq!(zero.classify(), FpCategory::Zero);
1280/// assert_eq!(sub.classify(), FpCategory::Subnormal);
1281/// assert_eq!(nan.classify(), FpCategory::Nan);
1282/// ```
1283#[derive(Copy, Clone, PartialEq, Eq, Debug)]
1284#[stable(feature = "rust1", since = "1.0.0")]
1285pub enum FpCategory {
1286 /// NaN (not a number): this value results from calculations like `(-1.0).sqrt()`.
1287 ///
1288 /// See [the documentation for `f32`](f32) for more information on the unusual properties
1289 /// of NaN.
1290 #[stable(feature = "rust1", since = "1.0.0")]
1291 Nan,
1292
1293 /// Positive or negative infinity, which often results from dividing a nonzero number
1294 /// by zero.
1295 #[stable(feature = "rust1", since = "1.0.0")]
1296 Infinite,
1297
1298 /// Positive or negative zero.
1299 ///
1300 /// See [the documentation for `f32`](f32) for more information on the signedness of zeroes.
1301 #[stable(feature = "rust1", since = "1.0.0")]
1302 Zero,
1303
1304 /// “Subnormal” or “denormal” floating point representation (less precise, relative to
1305 /// their magnitude, than [`Normal`]).
1306 ///
1307 /// Subnormal numbers are larger in magnitude than [`Zero`] but smaller in magnitude than all
1308 /// [`Normal`] numbers.
1309 ///
1310 /// [`Normal`]: Self::Normal
1311 /// [`Zero`]: Self::Zero
1312 #[stable(feature = "rust1", since = "1.0.0")]
1313 Subnormal,
1314
1315 /// A regular floating point number, not any of the exceptional categories.
1316 ///
1317 /// The smallest positive normal numbers are [`f32::MIN_POSITIVE`] and [`f64::MIN_POSITIVE`],
1318 /// and the largest positive normal numbers are [`f32::MAX`] and [`f64::MAX`]. (Unlike signed
1319 /// integers, floating point numbers are symmetric in their range, so negating any of these
1320 /// constants will produce their negative counterpart.)
1321 #[stable(feature = "rust1", since = "1.0.0")]
1322 Normal,
1323}
1324
1325/// Determines if a string of text of that length of that radix could be guaranteed to be
1326/// stored in the given type T.
1327/// Note that if the radix is known to the compiler, it is just the check of digits.len that
1328/// is done at runtime.
1329#[doc(hidden)]
1330#[inline(always)]
1331#[unstable(issue = "none", feature = "std_internals")]
1332pub const fn can_not_overflow<T>(radix: u32, is_signed_ty: bool, digits: &[u8]) -> bool {
1333 radix <= 16 && digits.len() <= size_of::<T>() * 2 - is_signed_ty as usize
1334}
1335
1336#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never))]
1337#[cfg_attr(feature = "panic_immediate_abort", inline)]
1338#[cold]
1339#[track_caller]
1340const fn from_ascii_radix_panic(radix: u32) -> ! {
1341 const_panic!(
1342 "from_ascii_radix: radix must lie in the range `[2, 36]`",
1343 "from_ascii_radix: radix must lie in the range `[2, 36]` - found {radix}",
1344 radix: u32 = radix,
1345 )
1346}
1347
1348macro_rules! from_str_int_impl {
1349 ($signedness:ident $($int_ty:ty)+) => {$(
1350 #[stable(feature = "rust1", since = "1.0.0")]
1351 impl FromStr for $int_ty {
1352 type Err = ParseIntError;
1353
1354 /// Parses an integer from a string slice with decimal digits.
1355 ///
1356 /// The characters are expected to be an optional
1357 #[doc = sign_dependent_expr!{
1358 $signedness ?
1359 if signed {
1360 " `+` or `-` "
1361 }
1362 if unsigned {
1363 " `+` "
1364 }
1365 }]
1366 /// sign followed by only digits. Leading and trailing non-digit characters (including
1367 /// whitespace) represent an error. Underscores (which are accepted in Rust literals)
1368 /// also represent an error.
1369 ///
1370 /// # Examples
1371 ///
1372 /// Basic usage:
1373 /// ```
1374 /// use std::str::FromStr;
1375 ///
1376 #[doc = concat!("assert_eq!(", stringify!($int_ty), "::from_str(\"+10\"), Ok(10));")]
1377 /// ```
1378 /// Trailing space returns error:
1379 /// ```
1380 /// # use std::str::FromStr;
1381 /// #
1382 #[doc = concat!("assert!(", stringify!($int_ty), "::from_str(\"1 \").is_err());")]
1383 /// ```
1384 #[inline]
1385 fn from_str(src: &str) -> Result<$int_ty, ParseIntError> {
1386 <$int_ty>::from_str_radix(src, 10)
1387 }
1388 }
1389
1390 impl $int_ty {
1391 /// Parses an integer from a string slice with digits in a given base.
1392 ///
1393 /// The string is expected to be an optional
1394 #[doc = sign_dependent_expr!{
1395 $signedness ?
1396 if signed {
1397 " `+` or `-` "
1398 }
1399 if unsigned {
1400 " `+` "
1401 }
1402 }]
1403 /// sign followed by only digits. Leading and trailing non-digit characters (including
1404 /// whitespace) represent an error. Underscores (which are accepted in Rust literals)
1405 /// also represent an error.
1406 ///
1407 /// Digits are a subset of these characters, depending on `radix`:
1408 /// * `0-9`
1409 /// * `a-z`
1410 /// * `A-Z`
1411 ///
1412 /// # Panics
1413 ///
1414 /// This function panics if `radix` is not in the range from 2 to 36.
1415 ///
1416 /// # Examples
1417 ///
1418 /// Basic usage:
1419 /// ```
1420 #[doc = concat!("assert_eq!(", stringify!($int_ty), "::from_str_radix(\"A\", 16), Ok(10));")]
1421 /// ```
1422 /// Trailing space returns error:
1423 /// ```
1424 #[doc = concat!("assert!(", stringify!($int_ty), "::from_str_radix(\"1 \", 10).is_err());")]
1425 /// ```
1426 #[stable(feature = "rust1", since = "1.0.0")]
1427 #[rustc_const_stable(feature = "const_int_from_str", since = "1.82.0")]
1428 #[inline]
1429 pub const fn from_str_radix(src: &str, radix: u32) -> Result<$int_ty, ParseIntError> {
1430 <$int_ty>::from_ascii_radix(src.as_bytes(), radix)
1431 }
1432
1433 /// Parses an integer from an ASCII-byte slice with decimal digits.
1434 ///
1435 /// The characters are expected to be an optional
1436 #[doc = sign_dependent_expr!{
1437 $signedness ?
1438 if signed {
1439 " `+` or `-` "
1440 }
1441 if unsigned {
1442 " `+` "
1443 }
1444 }]
1445 /// sign followed by only digits. Leading and trailing non-digit characters (including
1446 /// whitespace) represent an error. Underscores (which are accepted in Rust literals)
1447 /// also represent an error.
1448 ///
1449 /// # Examples
1450 ///
1451 /// Basic usage:
1452 /// ```
1453 /// #![feature(int_from_ascii)]
1454 ///
1455 #[doc = concat!("assert_eq!(", stringify!($int_ty), "::from_ascii(b\"+10\"), Ok(10));")]
1456 /// ```
1457 /// Trailing space returns error:
1458 /// ```
1459 /// # #![feature(int_from_ascii)]
1460 /// #
1461 #[doc = concat!("assert!(", stringify!($int_ty), "::from_ascii(b\"1 \").is_err());")]
1462 /// ```
1463 #[unstable(feature = "int_from_ascii", issue = "134821")]
1464 #[inline]
1465 pub const fn from_ascii(src: &[u8]) -> Result<$int_ty, ParseIntError> {
1466 <$int_ty>::from_ascii_radix(src, 10)
1467 }
1468
1469 /// Parses an integer from an ASCII-byte slice with digits in a given base.
1470 ///
1471 /// The characters are expected to be an optional
1472 #[doc = sign_dependent_expr!{
1473 $signedness ?
1474 if signed {
1475 " `+` or `-` "
1476 }
1477 if unsigned {
1478 " `+` "
1479 }
1480 }]
1481 /// sign followed by only digits. Leading and trailing non-digit characters (including
1482 /// whitespace) represent an error. Underscores (which are accepted in Rust literals)
1483 /// also represent an error.
1484 ///
1485 /// Digits are a subset of these characters, depending on `radix`:
1486 /// * `0-9`
1487 /// * `a-z`
1488 /// * `A-Z`
1489 ///
1490 /// # Panics
1491 ///
1492 /// This function panics if `radix` is not in the range from 2 to 36.
1493 ///
1494 /// # Examples
1495 ///
1496 /// Basic usage:
1497 /// ```
1498 /// #![feature(int_from_ascii)]
1499 ///
1500 #[doc = concat!("assert_eq!(", stringify!($int_ty), "::from_ascii_radix(b\"A\", 16), Ok(10));")]
1501 /// ```
1502 /// Trailing space returns error:
1503 /// ```
1504 /// # #![feature(int_from_ascii)]
1505 /// #
1506 #[doc = concat!("assert!(", stringify!($int_ty), "::from_ascii_radix(b\"1 \", 10).is_err());")]
1507 /// ```
1508 #[unstable(feature = "int_from_ascii", issue = "134821")]
1509 #[inline]
1510 pub const fn from_ascii_radix(src: &[u8], radix: u32) -> Result<$int_ty, ParseIntError> {
1511 use self::IntErrorKind::*;
1512 use self::ParseIntError as PIE;
1513
1514 if 2 > radix || radix > 36 {
1515 from_ascii_radix_panic(radix);
1516 }
1517
1518 if src.is_empty() {
1519 return Err(PIE { kind: Empty });
1520 }
1521
1522 #[allow(unused_comparisons)]
1523 let is_signed_ty = 0 > <$int_ty>::MIN;
1524
1525 let (is_positive, mut digits) = match src {
1526 [b'+' | b'-'] => {
1527 return Err(PIE { kind: InvalidDigit });
1528 }
1529 [b'+', rest @ ..] => (true, rest),
1530 [b'-', rest @ ..] if is_signed_ty => (false, rest),
1531 _ => (true, src),
1532 };
1533
1534 let mut result = 0;
1535
1536 macro_rules! unwrap_or_PIE {
1537 ($option:expr, $kind:ident) => {
1538 match $option {
1539 Some(value) => value,
1540 None => return Err(PIE { kind: $kind }),
1541 }
1542 };
1543 }
1544
1545 if can_not_overflow::<$int_ty>(radix, is_signed_ty, digits) {
1546 // If the len of the str is short compared to the range of the type
1547 // we are parsing into, then we can be certain that an overflow will not occur.
1548 // This bound is when `radix.pow(digits.len()) - 1 <= T::MAX` but the condition
1549 // above is a faster (conservative) approximation of this.
1550 //
1551 // Consider radix 16 as it has the highest information density per digit and will thus overflow the earliest:
1552 // `u8::MAX` is `ff` - any str of len 2 is guaranteed to not overflow.
1553 // `i8::MAX` is `7f` - only a str of len 1 is guaranteed to not overflow.
1554 macro_rules! run_unchecked_loop {
1555 ($unchecked_additive_op:tt) => {{
1556 while let [c, rest @ ..] = digits {
1557 result = result * (radix as $int_ty);
1558 let x = unwrap_or_PIE!((*c as char).to_digit(radix), InvalidDigit);
1559 result = result $unchecked_additive_op (x as $int_ty);
1560 digits = rest;
1561 }
1562 }};
1563 }
1564 if is_positive {
1565 run_unchecked_loop!(+)
1566 } else {
1567 run_unchecked_loop!(-)
1568 };
1569 } else {
1570 macro_rules! run_checked_loop {
1571 ($checked_additive_op:ident, $overflow_err:ident) => {{
1572 while let [c, rest @ ..] = digits {
1573 // When `radix` is passed in as a literal, rather than doing a slow `imul`
1574 // the compiler can use shifts if `radix` can be expressed as a
1575 // sum of powers of 2 (x*10 can be written as x*8 + x*2).
1576 // When the compiler can't use these optimisations,
1577 // the latency of the multiplication can be hidden by issuing it
1578 // before the result is needed to improve performance on
1579 // modern out-of-order CPU as multiplication here is slower
1580 // than the other instructions, we can get the end result faster
1581 // doing multiplication first and let the CPU spends other cycles
1582 // doing other computation and get multiplication result later.
1583 let mul = result.checked_mul(radix as $int_ty);
1584 let x = unwrap_or_PIE!((*c as char).to_digit(radix), InvalidDigit) as $int_ty;
1585 result = unwrap_or_PIE!(mul, $overflow_err);
1586 result = unwrap_or_PIE!(<$int_ty>::$checked_additive_op(result, x), $overflow_err);
1587 digits = rest;
1588 }
1589 }};
1590 }
1591 if is_positive {
1592 run_checked_loop!(checked_add, PosOverflow)
1593 } else {
1594 run_checked_loop!(checked_sub, NegOverflow)
1595 };
1596 }
1597 Ok(result)
1598 }
1599 }
1600 )*}
1601}
1602
1603from_str_int_impl! { signed isize i8 i16 i32 i64 i128 }
1604from_str_int_impl! { unsigned usize u8 u16 u32 u64 u128 }
1605