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