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