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 swap_op = "0x12",
458 swapped = "0x12",
459 reversed = "0x48",
460 le_bytes = "[0x12]",
461 be_bytes = "[0x12]",
462 to_xe_bytes_doc = u8_xe_bytes_doc!(),
463 from_xe_bytes_doc = u8_xe_bytes_doc!(),
464 bound_condition = "",
465 }
466 midpoint_impl! { u8, u16, unsigned }
467
468 /// Checks if the value is within the ASCII range.
469 ///
470 /// # Examples
471 ///
472 /// ```
473 /// let ascii = 97u8;
474 /// let non_ascii = 150u8;
475 ///
476 /// assert!(ascii.is_ascii());
477 /// assert!(!non_ascii.is_ascii());
478 /// ```
479 #[must_use]
480 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
481 #[rustc_const_stable(feature = "const_u8_is_ascii", since = "1.43.0")]
482 #[inline]
483 pub const fn is_ascii(&self) -> bool {
484 *self <= 127
485 }
486
487 /// If the value of this byte is within the ASCII range, returns it as an
488 /// [ASCII character](ascii::Char). Otherwise, returns `None`.
489 #[must_use]
490 #[unstable(feature = "ascii_char", issue = "110998")]
491 #[inline]
492 pub const fn as_ascii(&self) -> Option<ascii::Char> {
493 ascii::Char::from_u8(*self)
494 }
495
496 /// Converts this byte to an [ASCII character](ascii::Char), without
497 /// checking whether or not it's valid.
498 ///
499 /// # Safety
500 ///
501 /// This byte must be valid ASCII, or else this is UB.
502 #[must_use]
503 #[unstable(feature = "ascii_char", issue = "110998")]
504 #[inline]
505 pub const unsafe fn as_ascii_unchecked(&self) -> ascii::Char {
506 assert_unsafe_precondition!(
507 check_library_ub,
508 "as_ascii_unchecked requires that the byte is valid ASCII",
509 (it: &u8 = self) => it.is_ascii()
510 );
511
512 // SAFETY: the caller promised that this byte is ASCII.
513 unsafe { ascii::Char::from_u8_unchecked(*self) }
514 }
515
516 /// Makes a copy of the value in its ASCII upper case equivalent.
517 ///
518 /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
519 /// but non-ASCII letters are unchanged.
520 ///
521 /// To uppercase the value in-place, use [`make_ascii_uppercase`].
522 ///
523 /// # Examples
524 ///
525 /// ```
526 /// let lowercase_a = 97u8;
527 ///
528 /// assert_eq!(65, lowercase_a.to_ascii_uppercase());
529 /// ```
530 ///
531 /// [`make_ascii_uppercase`]: Self::make_ascii_uppercase
532 #[must_use = "to uppercase the value in-place, use `make_ascii_uppercase()`"]
533 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
534 #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")]
535 #[inline]
536 pub const fn to_ascii_uppercase(&self) -> u8 {
537 // Toggle the 6th bit if this is a lowercase letter
538 *self ^ ((self.is_ascii_lowercase() as u8) * ASCII_CASE_MASK)
539 }
540
541 /// Makes a copy of the value in its ASCII lower case equivalent.
542 ///
543 /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
544 /// but non-ASCII letters are unchanged.
545 ///
546 /// To lowercase the value in-place, use [`make_ascii_lowercase`].
547 ///
548 /// # Examples
549 ///
550 /// ```
551 /// let uppercase_a = 65u8;
552 ///
553 /// assert_eq!(97, uppercase_a.to_ascii_lowercase());
554 /// ```
555 ///
556 /// [`make_ascii_lowercase`]: Self::make_ascii_lowercase
557 #[must_use = "to lowercase the value in-place, use `make_ascii_lowercase()`"]
558 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
559 #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")]
560 #[inline]
561 pub const fn to_ascii_lowercase(&self) -> u8 {
562 // Set the 6th bit if this is an uppercase letter
563 *self | (self.is_ascii_uppercase() as u8 * ASCII_CASE_MASK)
564 }
565
566 /// Assumes self is ascii
567 #[inline]
568 pub(crate) const fn ascii_change_case_unchecked(&self) -> u8 {
569 *self ^ ASCII_CASE_MASK
570 }
571
572 /// Checks that two values are an ASCII case-insensitive match.
573 ///
574 /// This is equivalent to `to_ascii_lowercase(a) == to_ascii_lowercase(b)`.
575 ///
576 /// # Examples
577 ///
578 /// ```
579 /// let lowercase_a = 97u8;
580 /// let uppercase_a = 65u8;
581 ///
582 /// assert!(lowercase_a.eq_ignore_ascii_case(&uppercase_a));
583 /// ```
584 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
585 #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")]
586 #[inline]
587 pub const fn eq_ignore_ascii_case(&self, other: &u8) -> bool {
588 self.to_ascii_lowercase() == other.to_ascii_lowercase()
589 }
590
591 /// Converts this value to its ASCII upper case equivalent in-place.
592 ///
593 /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
594 /// but non-ASCII letters are unchanged.
595 ///
596 /// To return a new uppercased value without modifying the existing one, use
597 /// [`to_ascii_uppercase`].
598 ///
599 /// # Examples
600 ///
601 /// ```
602 /// let mut byte = b'a';
603 ///
604 /// byte.make_ascii_uppercase();
605 ///
606 /// assert_eq!(b'A', byte);
607 /// ```
608 ///
609 /// [`to_ascii_uppercase`]: Self::to_ascii_uppercase
610 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
611 #[rustc_const_stable(feature = "const_make_ascii", since = "1.84.0")]
612 #[inline]
613 pub const fn make_ascii_uppercase(&mut self) {
614 *self = self.to_ascii_uppercase();
615 }
616
617 /// Converts this value to its ASCII lower case equivalent in-place.
618 ///
619 /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
620 /// but non-ASCII letters are unchanged.
621 ///
622 /// To return a new lowercased value without modifying the existing one, use
623 /// [`to_ascii_lowercase`].
624 ///
625 /// # Examples
626 ///
627 /// ```
628 /// let mut byte = b'A';
629 ///
630 /// byte.make_ascii_lowercase();
631 ///
632 /// assert_eq!(b'a', byte);
633 /// ```
634 ///
635 /// [`to_ascii_lowercase`]: Self::to_ascii_lowercase
636 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
637 #[rustc_const_stable(feature = "const_make_ascii", since = "1.84.0")]
638 #[inline]
639 pub const fn make_ascii_lowercase(&mut self) {
640 *self = self.to_ascii_lowercase();
641 }
642
643 /// Checks if the value is an ASCII alphabetic character:
644 ///
645 /// - U+0041 'A' ..= U+005A 'Z', or
646 /// - U+0061 'a' ..= U+007A 'z'.
647 ///
648 /// # Examples
649 ///
650 /// ```
651 /// let uppercase_a = b'A';
652 /// let uppercase_g = b'G';
653 /// let a = b'a';
654 /// let g = b'g';
655 /// let zero = b'0';
656 /// let percent = b'%';
657 /// let space = b' ';
658 /// let lf = b'\n';
659 /// let esc = b'\x1b';
660 ///
661 /// assert!(uppercase_a.is_ascii_alphabetic());
662 /// assert!(uppercase_g.is_ascii_alphabetic());
663 /// assert!(a.is_ascii_alphabetic());
664 /// assert!(g.is_ascii_alphabetic());
665 /// assert!(!zero.is_ascii_alphabetic());
666 /// assert!(!percent.is_ascii_alphabetic());
667 /// assert!(!space.is_ascii_alphabetic());
668 /// assert!(!lf.is_ascii_alphabetic());
669 /// assert!(!esc.is_ascii_alphabetic());
670 /// ```
671 #[must_use]
672 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
673 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
674 #[inline]
675 pub const fn is_ascii_alphabetic(&self) -> bool {
676 matches!(*self, b'A'..=b'Z' | b'a'..=b'z')
677 }
678
679 /// Checks if the value is an ASCII uppercase character:
680 /// U+0041 'A' ..= U+005A 'Z'.
681 ///
682 /// # Examples
683 ///
684 /// ```
685 /// let uppercase_a = b'A';
686 /// let uppercase_g = b'G';
687 /// let a = b'a';
688 /// let g = b'g';
689 /// let zero = b'0';
690 /// let percent = b'%';
691 /// let space = b' ';
692 /// let lf = b'\n';
693 /// let esc = b'\x1b';
694 ///
695 /// assert!(uppercase_a.is_ascii_uppercase());
696 /// assert!(uppercase_g.is_ascii_uppercase());
697 /// assert!(!a.is_ascii_uppercase());
698 /// assert!(!g.is_ascii_uppercase());
699 /// assert!(!zero.is_ascii_uppercase());
700 /// assert!(!percent.is_ascii_uppercase());
701 /// assert!(!space.is_ascii_uppercase());
702 /// assert!(!lf.is_ascii_uppercase());
703 /// assert!(!esc.is_ascii_uppercase());
704 /// ```
705 #[must_use]
706 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
707 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
708 #[inline]
709 pub const fn is_ascii_uppercase(&self) -> bool {
710 matches!(*self, b'A'..=b'Z')
711 }
712
713 /// Checks if the value is an ASCII lowercase character:
714 /// U+0061 'a' ..= U+007A 'z'.
715 ///
716 /// # Examples
717 ///
718 /// ```
719 /// let uppercase_a = b'A';
720 /// let uppercase_g = b'G';
721 /// let a = b'a';
722 /// let g = b'g';
723 /// let zero = b'0';
724 /// let percent = b'%';
725 /// let space = b' ';
726 /// let lf = b'\n';
727 /// let esc = b'\x1b';
728 ///
729 /// assert!(!uppercase_a.is_ascii_lowercase());
730 /// assert!(!uppercase_g.is_ascii_lowercase());
731 /// assert!(a.is_ascii_lowercase());
732 /// assert!(g.is_ascii_lowercase());
733 /// assert!(!zero.is_ascii_lowercase());
734 /// assert!(!percent.is_ascii_lowercase());
735 /// assert!(!space.is_ascii_lowercase());
736 /// assert!(!lf.is_ascii_lowercase());
737 /// assert!(!esc.is_ascii_lowercase());
738 /// ```
739 #[must_use]
740 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
741 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
742 #[inline]
743 pub const fn is_ascii_lowercase(&self) -> bool {
744 matches!(*self, b'a'..=b'z')
745 }
746
747 /// Checks if the value is an ASCII alphanumeric character:
748 ///
749 /// - U+0041 'A' ..= U+005A 'Z', or
750 /// - U+0061 'a' ..= U+007A 'z', or
751 /// - U+0030 '0' ..= U+0039 '9'.
752 ///
753 /// # Examples
754 ///
755 /// ```
756 /// let uppercase_a = b'A';
757 /// let uppercase_g = b'G';
758 /// let a = b'a';
759 /// let g = b'g';
760 /// let zero = b'0';
761 /// let percent = b'%';
762 /// let space = b' ';
763 /// let lf = b'\n';
764 /// let esc = b'\x1b';
765 ///
766 /// assert!(uppercase_a.is_ascii_alphanumeric());
767 /// assert!(uppercase_g.is_ascii_alphanumeric());
768 /// assert!(a.is_ascii_alphanumeric());
769 /// assert!(g.is_ascii_alphanumeric());
770 /// assert!(zero.is_ascii_alphanumeric());
771 /// assert!(!percent.is_ascii_alphanumeric());
772 /// assert!(!space.is_ascii_alphanumeric());
773 /// assert!(!lf.is_ascii_alphanumeric());
774 /// assert!(!esc.is_ascii_alphanumeric());
775 /// ```
776 #[must_use]
777 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
778 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
779 #[inline]
780 pub const fn is_ascii_alphanumeric(&self) -> bool {
781 matches!(*self, b'0'..=b'9') | matches!(*self, b'A'..=b'Z') | matches!(*self, b'a'..=b'z')
782 }
783
784 /// Checks if the value is an ASCII decimal digit:
785 /// U+0030 '0' ..= U+0039 '9'.
786 ///
787 /// # Examples
788 ///
789 /// ```
790 /// let uppercase_a = b'A';
791 /// let uppercase_g = b'G';
792 /// let a = b'a';
793 /// let g = b'g';
794 /// let zero = b'0';
795 /// let percent = b'%';
796 /// let space = b' ';
797 /// let lf = b'\n';
798 /// let esc = b'\x1b';
799 ///
800 /// assert!(!uppercase_a.is_ascii_digit());
801 /// assert!(!uppercase_g.is_ascii_digit());
802 /// assert!(!a.is_ascii_digit());
803 /// assert!(!g.is_ascii_digit());
804 /// assert!(zero.is_ascii_digit());
805 /// assert!(!percent.is_ascii_digit());
806 /// assert!(!space.is_ascii_digit());
807 /// assert!(!lf.is_ascii_digit());
808 /// assert!(!esc.is_ascii_digit());
809 /// ```
810 #[must_use]
811 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
812 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
813 #[inline]
814 pub const fn is_ascii_digit(&self) -> bool {
815 matches!(*self, b'0'..=b'9')
816 }
817
818 /// Checks if the value is an ASCII octal digit:
819 /// U+0030 '0' ..= U+0037 '7'.
820 ///
821 /// # Examples
822 ///
823 /// ```
824 /// #![feature(is_ascii_octdigit)]
825 ///
826 /// let uppercase_a = b'A';
827 /// let a = b'a';
828 /// let zero = b'0';
829 /// let seven = b'7';
830 /// let nine = b'9';
831 /// let percent = b'%';
832 /// let lf = b'\n';
833 ///
834 /// assert!(!uppercase_a.is_ascii_octdigit());
835 /// assert!(!a.is_ascii_octdigit());
836 /// assert!(zero.is_ascii_octdigit());
837 /// assert!(seven.is_ascii_octdigit());
838 /// assert!(!nine.is_ascii_octdigit());
839 /// assert!(!percent.is_ascii_octdigit());
840 /// assert!(!lf.is_ascii_octdigit());
841 /// ```
842 #[must_use]
843 #[unstable(feature = "is_ascii_octdigit", issue = "101288")]
844 #[inline]
845 pub const fn is_ascii_octdigit(&self) -> bool {
846 matches!(*self, b'0'..=b'7')
847 }
848
849 /// Checks if the value is an ASCII hexadecimal digit:
850 ///
851 /// - U+0030 '0' ..= U+0039 '9', or
852 /// - U+0041 'A' ..= U+0046 'F', or
853 /// - U+0061 'a' ..= U+0066 'f'.
854 ///
855 /// # Examples
856 ///
857 /// ```
858 /// let uppercase_a = b'A';
859 /// let uppercase_g = b'G';
860 /// let a = b'a';
861 /// let g = b'g';
862 /// let zero = b'0';
863 /// let percent = b'%';
864 /// let space = b' ';
865 /// let lf = b'\n';
866 /// let esc = b'\x1b';
867 ///
868 /// assert!(uppercase_a.is_ascii_hexdigit());
869 /// assert!(!uppercase_g.is_ascii_hexdigit());
870 /// assert!(a.is_ascii_hexdigit());
871 /// assert!(!g.is_ascii_hexdigit());
872 /// assert!(zero.is_ascii_hexdigit());
873 /// assert!(!percent.is_ascii_hexdigit());
874 /// assert!(!space.is_ascii_hexdigit());
875 /// assert!(!lf.is_ascii_hexdigit());
876 /// assert!(!esc.is_ascii_hexdigit());
877 /// ```
878 #[must_use]
879 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
880 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
881 #[inline]
882 pub const fn is_ascii_hexdigit(&self) -> bool {
883 matches!(*self, b'0'..=b'9') | matches!(*self, b'A'..=b'F') | matches!(*self, b'a'..=b'f')
884 }
885
886 /// Checks if the value is an ASCII punctuation character:
887 ///
888 /// - U+0021 ..= U+002F `! " # $ % & ' ( ) * + , - . /`, or
889 /// - U+003A ..= U+0040 `: ; < = > ? @`, or
890 /// - U+005B ..= U+0060 `` [ \ ] ^ _ ` ``, or
891 /// - U+007B ..= U+007E `{ | } ~`
892 ///
893 /// # Examples
894 ///
895 /// ```
896 /// let uppercase_a = b'A';
897 /// let uppercase_g = b'G';
898 /// let a = b'a';
899 /// let g = b'g';
900 /// let zero = b'0';
901 /// let percent = b'%';
902 /// let space = b' ';
903 /// let lf = b'\n';
904 /// let esc = b'\x1b';
905 ///
906 /// assert!(!uppercase_a.is_ascii_punctuation());
907 /// assert!(!uppercase_g.is_ascii_punctuation());
908 /// assert!(!a.is_ascii_punctuation());
909 /// assert!(!g.is_ascii_punctuation());
910 /// assert!(!zero.is_ascii_punctuation());
911 /// assert!(percent.is_ascii_punctuation());
912 /// assert!(!space.is_ascii_punctuation());
913 /// assert!(!lf.is_ascii_punctuation());
914 /// assert!(!esc.is_ascii_punctuation());
915 /// ```
916 #[must_use]
917 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
918 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
919 #[inline]
920 pub const fn is_ascii_punctuation(&self) -> bool {
921 matches!(*self, b'!'..=b'/')
922 | matches!(*self, b':'..=b'@')
923 | matches!(*self, b'['..=b'`')
924 | matches!(*self, b'{'..=b'~')
925 }
926
927 /// Checks if the value is an ASCII graphic character:
928 /// U+0021 '!' ..= U+007E '~'.
929 ///
930 /// # Examples
931 ///
932 /// ```
933 /// let uppercase_a = b'A';
934 /// let uppercase_g = b'G';
935 /// let a = b'a';
936 /// let g = b'g';
937 /// let zero = b'0';
938 /// let percent = b'%';
939 /// let space = b' ';
940 /// let lf = b'\n';
941 /// let esc = b'\x1b';
942 ///
943 /// assert!(uppercase_a.is_ascii_graphic());
944 /// assert!(uppercase_g.is_ascii_graphic());
945 /// assert!(a.is_ascii_graphic());
946 /// assert!(g.is_ascii_graphic());
947 /// assert!(zero.is_ascii_graphic());
948 /// assert!(percent.is_ascii_graphic());
949 /// assert!(!space.is_ascii_graphic());
950 /// assert!(!lf.is_ascii_graphic());
951 /// assert!(!esc.is_ascii_graphic());
952 /// ```
953 #[must_use]
954 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
955 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
956 #[inline]
957 pub const fn is_ascii_graphic(&self) -> bool {
958 matches!(*self, b'!'..=b'~')
959 }
960
961 /// Checks if the value is an ASCII whitespace character:
962 /// U+0020 SPACE, U+0009 HORIZONTAL TAB, U+000A LINE FEED,
963 /// U+000C FORM FEED, or U+000D CARRIAGE RETURN.
964 ///
965 /// Rust uses the WhatWG Infra Standard's [definition of ASCII
966 /// whitespace][infra-aw]. There are several other definitions in
967 /// wide use. For instance, [the POSIX locale][pct] includes
968 /// U+000B VERTICAL TAB as well as all the above characters,
969 /// but—from the very same specification—[the default rule for
970 /// "field splitting" in the Bourne shell][bfs] considers *only*
971 /// SPACE, HORIZONTAL TAB, and LINE FEED as whitespace.
972 ///
973 /// If you are writing a program that will process an existing
974 /// file format, check what that format's definition of whitespace is
975 /// before using this function.
976 ///
977 /// [infra-aw]: https://infra.spec.whatwg.org/#ascii-whitespace
978 /// [pct]: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html#tag_07_03_01
979 /// [bfs]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_05
980 ///
981 /// # Examples
982 ///
983 /// ```
984 /// let uppercase_a = b'A';
985 /// let uppercase_g = b'G';
986 /// let a = b'a';
987 /// let g = b'g';
988 /// let zero = b'0';
989 /// let percent = b'%';
990 /// let space = b' ';
991 /// let lf = b'\n';
992 /// let esc = b'\x1b';
993 ///
994 /// assert!(!uppercase_a.is_ascii_whitespace());
995 /// assert!(!uppercase_g.is_ascii_whitespace());
996 /// assert!(!a.is_ascii_whitespace());
997 /// assert!(!g.is_ascii_whitespace());
998 /// assert!(!zero.is_ascii_whitespace());
999 /// assert!(!percent.is_ascii_whitespace());
1000 /// assert!(space.is_ascii_whitespace());
1001 /// assert!(lf.is_ascii_whitespace());
1002 /// assert!(!esc.is_ascii_whitespace());
1003 /// ```
1004 #[must_use]
1005 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
1006 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
1007 #[inline]
1008 pub const fn is_ascii_whitespace(&self) -> bool {
1009 matches!(*self, b'\t' | b'\n' | b'\x0C' | b'\r' | b' ')
1010 }
1011
1012 /// Checks if the value is an ASCII control character:
1013 /// U+0000 NUL ..= U+001F UNIT SEPARATOR, or U+007F DELETE.
1014 /// Note that most ASCII whitespace characters are control
1015 /// characters, but SPACE is not.
1016 ///
1017 /// # Examples
1018 ///
1019 /// ```
1020 /// let uppercase_a = b'A';
1021 /// let uppercase_g = b'G';
1022 /// let a = b'a';
1023 /// let g = b'g';
1024 /// let zero = b'0';
1025 /// let percent = b'%';
1026 /// let space = b' ';
1027 /// let lf = b'\n';
1028 /// let esc = b'\x1b';
1029 ///
1030 /// assert!(!uppercase_a.is_ascii_control());
1031 /// assert!(!uppercase_g.is_ascii_control());
1032 /// assert!(!a.is_ascii_control());
1033 /// assert!(!g.is_ascii_control());
1034 /// assert!(!zero.is_ascii_control());
1035 /// assert!(!percent.is_ascii_control());
1036 /// assert!(!space.is_ascii_control());
1037 /// assert!(lf.is_ascii_control());
1038 /// assert!(esc.is_ascii_control());
1039 /// ```
1040 #[must_use]
1041 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
1042 #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")]
1043 #[inline]
1044 pub const fn is_ascii_control(&self) -> bool {
1045 matches!(*self, b'\0'..=b'\x1F' | b'\x7F')
1046 }
1047
1048 /// Returns an iterator that produces an escaped version of a `u8`,
1049 /// treating it as an ASCII character.
1050 ///
1051 /// The behavior is identical to [`ascii::escape_default`].
1052 ///
1053 /// # Examples
1054 ///
1055 /// ```
1056 ///
1057 /// assert_eq!("0", b'0'.escape_ascii().to_string());
1058 /// assert_eq!("\\t", b'\t'.escape_ascii().to_string());
1059 /// assert_eq!("\\r", b'\r'.escape_ascii().to_string());
1060 /// assert_eq!("\\n", b'\n'.escape_ascii().to_string());
1061 /// assert_eq!("\\'", b'\''.escape_ascii().to_string());
1062 /// assert_eq!("\\\"", b'"'.escape_ascii().to_string());
1063 /// assert_eq!("\\\\", b'\\'.escape_ascii().to_string());
1064 /// assert_eq!("\\x9d", b'\x9d'.escape_ascii().to_string());
1065 /// ```
1066 #[must_use = "this returns the escaped byte as an iterator, \
1067 without modifying the original"]
1068 #[stable(feature = "inherent_ascii_escape", since = "1.60.0")]
1069 #[inline]
1070 pub fn escape_ascii(self) -> ascii::EscapeDefault {
1071 ascii::escape_default(self)
1072 }
1073
1074 #[inline]
1075 pub(crate) const fn is_utf8_char_boundary(self) -> bool {
1076 // This is bit magic equivalent to: b < 128 || b >= 192
1077 (self as i8) >= -0x40
1078 }
1079}
1080
1081impl u16 {
1082 uint_impl! {
1083 Self = u16,
1084 ActualT = u16,
1085 SignedT = i16,
1086 BITS = 16,
1087 BITS_MINUS_ONE = 15,
1088 MAX = 65535,
1089 rot = 4,
1090 rot_op = "0xa003",
1091 rot_result = "0x3a",
1092 swap_op = "0x1234",
1093 swapped = "0x3412",
1094 reversed = "0x2c48",
1095 le_bytes = "[0x34, 0x12]",
1096 be_bytes = "[0x12, 0x34]",
1097 to_xe_bytes_doc = "",
1098 from_xe_bytes_doc = "",
1099 bound_condition = "",
1100 }
1101 midpoint_impl! { u16, u32, unsigned }
1102
1103 /// Checks if the value is a Unicode surrogate code point, which are disallowed values for [`char`].
1104 ///
1105 /// # Examples
1106 ///
1107 /// ```
1108 /// #![feature(utf16_extra)]
1109 ///
1110 /// let low_non_surrogate = 0xA000u16;
1111 /// let low_surrogate = 0xD800u16;
1112 /// let high_surrogate = 0xDC00u16;
1113 /// let high_non_surrogate = 0xE000u16;
1114 ///
1115 /// assert!(!low_non_surrogate.is_utf16_surrogate());
1116 /// assert!(low_surrogate.is_utf16_surrogate());
1117 /// assert!(high_surrogate.is_utf16_surrogate());
1118 /// assert!(!high_non_surrogate.is_utf16_surrogate());
1119 /// ```
1120 #[must_use]
1121 #[unstable(feature = "utf16_extra", issue = "94919")]
1122 #[inline]
1123 pub const fn is_utf16_surrogate(self) -> bool {
1124 matches!(self, 0xD800..=0xDFFF)
1125 }
1126}
1127
1128impl u32 {
1129 uint_impl! {
1130 Self = u32,
1131 ActualT = u32,
1132 SignedT = i32,
1133 BITS = 32,
1134 BITS_MINUS_ONE = 31,
1135 MAX = 4294967295,
1136 rot = 8,
1137 rot_op = "0x10000b3",
1138 rot_result = "0xb301",
1139 swap_op = "0x12345678",
1140 swapped = "0x78563412",
1141 reversed = "0x1e6a2c48",
1142 le_bytes = "[0x78, 0x56, 0x34, 0x12]",
1143 be_bytes = "[0x12, 0x34, 0x56, 0x78]",
1144 to_xe_bytes_doc = "",
1145 from_xe_bytes_doc = "",
1146 bound_condition = "",
1147 }
1148 midpoint_impl! { u32, u64, unsigned }
1149}
1150
1151impl u64 {
1152 uint_impl! {
1153 Self = u64,
1154 ActualT = u64,
1155 SignedT = i64,
1156 BITS = 64,
1157 BITS_MINUS_ONE = 63,
1158 MAX = 18446744073709551615,
1159 rot = 12,
1160 rot_op = "0xaa00000000006e1",
1161 rot_result = "0x6e10aa",
1162 swap_op = "0x1234567890123456",
1163 swapped = "0x5634129078563412",
1164 reversed = "0x6a2c48091e6a2c48",
1165 le_bytes = "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
1166 be_bytes = "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
1167 to_xe_bytes_doc = "",
1168 from_xe_bytes_doc = "",
1169 bound_condition = "",
1170 }
1171 midpoint_impl! { u64, u128, unsigned }
1172}
1173
1174impl u128 {
1175 uint_impl! {
1176 Self = u128,
1177 ActualT = u128,
1178 SignedT = i128,
1179 BITS = 128,
1180 BITS_MINUS_ONE = 127,
1181 MAX = 340282366920938463463374607431768211455,
1182 rot = 16,
1183 rot_op = "0x13f40000000000000000000000004f76",
1184 rot_result = "0x4f7613f4",
1185 swap_op = "0x12345678901234567890123456789012",
1186 swapped = "0x12907856341290785634129078563412",
1187 reversed = "0x48091e6a2c48091e6a2c48091e6a2c48",
1188 le_bytes = "[0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, \
1189 0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
1190 be_bytes = "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56, \
1191 0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12]",
1192 to_xe_bytes_doc = "",
1193 from_xe_bytes_doc = "",
1194 bound_condition = "",
1195 }
1196 midpoint_impl! { u128, unsigned }
1197}
1198
1199#[cfg(target_pointer_width = "16")]
1200impl usize {
1201 uint_impl! {
1202 Self = usize,
1203 ActualT = u16,
1204 SignedT = isize,
1205 BITS = 16,
1206 BITS_MINUS_ONE = 15,
1207 MAX = 65535,
1208 rot = 4,
1209 rot_op = "0xa003",
1210 rot_result = "0x3a",
1211 swap_op = "0x1234",
1212 swapped = "0x3412",
1213 reversed = "0x2c48",
1214 le_bytes = "[0x34, 0x12]",
1215 be_bytes = "[0x12, 0x34]",
1216 to_xe_bytes_doc = usize_isize_to_xe_bytes_doc!(),
1217 from_xe_bytes_doc = usize_isize_from_xe_bytes_doc!(),
1218 bound_condition = " on 16-bit targets",
1219 }
1220 midpoint_impl! { usize, u32, unsigned }
1221}
1222
1223#[cfg(target_pointer_width = "32")]
1224impl usize {
1225 uint_impl! {
1226 Self = usize,
1227 ActualT = u32,
1228 SignedT = isize,
1229 BITS = 32,
1230 BITS_MINUS_ONE = 31,
1231 MAX = 4294967295,
1232 rot = 8,
1233 rot_op = "0x10000b3",
1234 rot_result = "0xb301",
1235 swap_op = "0x12345678",
1236 swapped = "0x78563412",
1237 reversed = "0x1e6a2c48",
1238 le_bytes = "[0x78, 0x56, 0x34, 0x12]",
1239 be_bytes = "[0x12, 0x34, 0x56, 0x78]",
1240 to_xe_bytes_doc = usize_isize_to_xe_bytes_doc!(),
1241 from_xe_bytes_doc = usize_isize_from_xe_bytes_doc!(),
1242 bound_condition = " on 32-bit targets",
1243 }
1244 midpoint_impl! { usize, u64, unsigned }
1245}
1246
1247#[cfg(target_pointer_width = "64")]
1248impl usize {
1249 uint_impl! {
1250 Self = usize,
1251 ActualT = u64,
1252 SignedT = isize,
1253 BITS = 64,
1254 BITS_MINUS_ONE = 63,
1255 MAX = 18446744073709551615,
1256 rot = 12,
1257 rot_op = "0xaa00000000006e1",
1258 rot_result = "0x6e10aa",
1259 swap_op = "0x1234567890123456",
1260 swapped = "0x5634129078563412",
1261 reversed = "0x6a2c48091e6a2c48",
1262 le_bytes = "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
1263 be_bytes = "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
1264 to_xe_bytes_doc = usize_isize_to_xe_bytes_doc!(),
1265 from_xe_bytes_doc = usize_isize_from_xe_bytes_doc!(),
1266 bound_condition = " on 64-bit targets",
1267 }
1268 midpoint_impl! { usize, u128, unsigned }
1269}
1270
1271impl usize {
1272 /// Returns an `usize` where every byte is equal to `x`.
1273 #[inline]
1274 pub(crate) const fn repeat_u8(x: u8) -> usize {
1275 usize::from_ne_bytes([x; size_of::<usize>()])
1276 }
1277
1278 /// Returns an `usize` where every byte pair is equal to `x`.
1279 #[inline]
1280 pub(crate) const fn repeat_u16(x: u16) -> usize {
1281 let mut r: usize = 0usize;
1282 let mut i: usize = 0;
1283 while i < size_of::<usize>() {
1284 // Use `wrapping_shl` to make it work on targets with 16-bit `usize`
1285 r = r.wrapping_shl(16) | (x as usize);
1286 i += 2;
1287 }
1288 r
1289 }
1290}
1291
1292/// A classification of floating point numbers.
1293///
1294/// This `enum` is used as the return type for [`f32::classify`] and [`f64::classify`]. See
1295/// their documentation for more.
1296///
1297/// # Examples
1298///
1299/// ```
1300/// use std::num::FpCategory;
1301///
1302/// let num = 12.4_f32;
1303/// let inf = f32::INFINITY;
1304/// let zero = 0f32;
1305/// let sub: f32 = 1.1754942e-38;
1306/// let nan = f32::NAN;
1307///
1308/// assert_eq!(num.classify(), FpCategory::Normal);
1309/// assert_eq!(inf.classify(), FpCategory::Infinite);
1310/// assert_eq!(zero.classify(), FpCategory::Zero);
1311/// assert_eq!(sub.classify(), FpCategory::Subnormal);
1312/// assert_eq!(nan.classify(), FpCategory::Nan);
1313/// ```
1314#[derive(Copy, Clone, PartialEq, Eq, Debug)]
1315#[stable(feature = "rust1", since = "1.0.0")]
1316pub enum FpCategory {
1317 /// NaN (not a number): this value results from calculations like `(-1.0).sqrt()`.
1318 ///
1319 /// See [the documentation for `f32`](f32) for more information on the unusual properties
1320 /// of NaN.
1321 #[stable(feature = "rust1", since = "1.0.0")]
1322 Nan,
1323
1324 /// Positive or negative infinity, which often results from dividing a nonzero number
1325 /// by zero.
1326 #[stable(feature = "rust1", since = "1.0.0")]
1327 Infinite,
1328
1329 /// Positive or negative zero.
1330 ///
1331 /// See [the documentation for `f32`](f32) for more information on the signedness of zeroes.
1332 #[stable(feature = "rust1", since = "1.0.0")]
1333 Zero,
1334
1335 /// “Subnormal” or “denormal” floating point representation (less precise, relative to
1336 /// their magnitude, than [`Normal`]).
1337 ///
1338 /// Subnormal numbers are larger in magnitude than [`Zero`] but smaller in magnitude than all
1339 /// [`Normal`] numbers.
1340 ///
1341 /// [`Normal`]: Self::Normal
1342 /// [`Zero`]: Self::Zero
1343 #[stable(feature = "rust1", since = "1.0.0")]
1344 Subnormal,
1345
1346 /// A regular floating point number, not any of the exceptional categories.
1347 ///
1348 /// The smallest positive normal numbers are [`f32::MIN_POSITIVE`] and [`f64::MIN_POSITIVE`],
1349 /// and the largest positive normal numbers are [`f32::MAX`] and [`f64::MAX`]. (Unlike signed
1350 /// integers, floating point numbers are symmetric in their range, so negating any of these
1351 /// constants will produce their negative counterpart.)
1352 #[stable(feature = "rust1", since = "1.0.0")]
1353 Normal,
1354}
1355
1356/// Determines if a string of text of that length of that radix could be guaranteed to be
1357/// stored in the given type T.
1358/// Note that if the radix is known to the compiler, it is just the check of digits.len that
1359/// is done at runtime.
1360#[doc(hidden)]
1361#[inline(always)]
1362#[unstable(issue = "none", feature = "std_internals")]
1363pub const fn can_not_overflow<T>(radix: u32, is_signed_ty: bool, digits: &[u8]) -> bool {
1364 radix <= 16 && digits.len() <= size_of::<T>() * 2 - is_signed_ty as usize
1365}
1366
1367#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never))]
1368#[cfg_attr(feature = "panic_immediate_abort", inline)]
1369#[cold]
1370#[track_caller]
1371const fn from_ascii_radix_panic(radix: u32) -> ! {
1372 const_panic!(
1373 "from_ascii_radix: radix must lie in the range `[2, 36]`",
1374 "from_ascii_radix: radix must lie in the range `[2, 36]` - found {radix}",
1375 radix: u32 = radix,
1376 )
1377}
1378
1379macro_rules! from_str_int_impl {
1380 ($signedness:ident $($int_ty:ty)+) => {$(
1381 #[stable(feature = "rust1", since = "1.0.0")]
1382 impl FromStr for $int_ty {
1383 type Err = ParseIntError;
1384
1385 /// Parses an integer from a string slice with decimal digits.
1386 ///
1387 /// The characters are expected to be an optional
1388 #[doc = sign_dependent_expr!{
1389 $signedness ?
1390 if signed {
1391 " `+` or `-` "
1392 }
1393 if unsigned {
1394 " `+` "
1395 }
1396 }]
1397 /// sign followed by only digits. Leading and trailing non-digit characters (including
1398 /// whitespace) represent an error. Underscores (which are accepted in Rust literals)
1399 /// also represent an error.
1400 ///
1401 /// # Examples
1402 ///
1403 /// Basic usage:
1404 /// ```
1405 /// use std::str::FromStr;
1406 ///
1407 #[doc = concat!("assert_eq!(", stringify!($int_ty), "::from_str(\"+10\"), Ok(10));")]
1408 /// ```
1409 /// Trailing space returns error:
1410 /// ```
1411 /// # use std::str::FromStr;
1412 /// #
1413 #[doc = concat!("assert!(", stringify!($int_ty), "::from_str(\"1 \").is_err());")]
1414 /// ```
1415 #[inline]
1416 fn from_str(src: &str) -> Result<$int_ty, ParseIntError> {
1417 <$int_ty>::from_str_radix(src, 10)
1418 }
1419 }
1420
1421 impl $int_ty {
1422 /// Parses an integer from a string slice with digits in a given base.
1423 ///
1424 /// The string is expected to be an optional
1425 #[doc = sign_dependent_expr!{
1426 $signedness ?
1427 if signed {
1428 " `+` or `-` "
1429 }
1430 if unsigned {
1431 " `+` "
1432 }
1433 }]
1434 /// sign followed by only digits. Leading and trailing non-digit characters (including
1435 /// whitespace) represent an error. Underscores (which are accepted in Rust literals)
1436 /// also represent an error.
1437 ///
1438 /// Digits are a subset of these characters, depending on `radix`:
1439 /// * `0-9`
1440 /// * `a-z`
1441 /// * `A-Z`
1442 ///
1443 /// # Panics
1444 ///
1445 /// This function panics if `radix` is not in the range from 2 to 36.
1446 ///
1447 /// # Examples
1448 ///
1449 /// Basic usage:
1450 /// ```
1451 #[doc = concat!("assert_eq!(", stringify!($int_ty), "::from_str_radix(\"A\", 16), Ok(10));")]
1452 /// ```
1453 /// Trailing space returns error:
1454 /// ```
1455 #[doc = concat!("assert!(", stringify!($int_ty), "::from_str_radix(\"1 \", 10).is_err());")]
1456 /// ```
1457 #[stable(feature = "rust1", since = "1.0.0")]
1458 #[rustc_const_stable(feature = "const_int_from_str", since = "1.82.0")]
1459 #[inline]
1460 pub const fn from_str_radix(src: &str, radix: u32) -> Result<$int_ty, ParseIntError> {
1461 <$int_ty>::from_ascii_radix(src.as_bytes(), radix)
1462 }
1463
1464 /// Parses an integer from an ASCII-byte slice with decimal digits.
1465 ///
1466 /// The characters are expected to be an optional
1467 #[doc = sign_dependent_expr!{
1468 $signedness ?
1469 if signed {
1470 " `+` or `-` "
1471 }
1472 if unsigned {
1473 " `+` "
1474 }
1475 }]
1476 /// sign followed by only digits. Leading and trailing non-digit characters (including
1477 /// whitespace) represent an error. Underscores (which are accepted in Rust literals)
1478 /// also represent an error.
1479 ///
1480 /// # Examples
1481 ///
1482 /// Basic usage:
1483 /// ```
1484 /// #![feature(int_from_ascii)]
1485 ///
1486 #[doc = concat!("assert_eq!(", stringify!($int_ty), "::from_ascii(b\"+10\"), Ok(10));")]
1487 /// ```
1488 /// Trailing space returns error:
1489 /// ```
1490 /// # #![feature(int_from_ascii)]
1491 /// #
1492 #[doc = concat!("assert!(", stringify!($int_ty), "::from_ascii(b\"1 \").is_err());")]
1493 /// ```
1494 #[unstable(feature = "int_from_ascii", issue = "134821")]
1495 #[inline]
1496 pub const fn from_ascii(src: &[u8]) -> Result<$int_ty, ParseIntError> {
1497 <$int_ty>::from_ascii_radix(src, 10)
1498 }
1499
1500 /// Parses an integer from an ASCII-byte slice with digits in a given base.
1501 ///
1502 /// The characters are expected to be an optional
1503 #[doc = sign_dependent_expr!{
1504 $signedness ?
1505 if signed {
1506 " `+` or `-` "
1507 }
1508 if unsigned {
1509 " `+` "
1510 }
1511 }]
1512 /// sign followed by only digits. Leading and trailing non-digit characters (including
1513 /// whitespace) represent an error. Underscores (which are accepted in Rust literals)
1514 /// also represent an error.
1515 ///
1516 /// Digits are a subset of these characters, depending on `radix`:
1517 /// * `0-9`
1518 /// * `a-z`
1519 /// * `A-Z`
1520 ///
1521 /// # Panics
1522 ///
1523 /// This function panics if `radix` is not in the range from 2 to 36.
1524 ///
1525 /// # Examples
1526 ///
1527 /// Basic usage:
1528 /// ```
1529 /// #![feature(int_from_ascii)]
1530 ///
1531 #[doc = concat!("assert_eq!(", stringify!($int_ty), "::from_ascii_radix(b\"A\", 16), Ok(10));")]
1532 /// ```
1533 /// Trailing space returns error:
1534 /// ```
1535 /// # #![feature(int_from_ascii)]
1536 /// #
1537 #[doc = concat!("assert!(", stringify!($int_ty), "::from_ascii_radix(b\"1 \", 10).is_err());")]
1538 /// ```
1539 #[unstable(feature = "int_from_ascii", issue = "134821")]
1540 #[inline]
1541 pub const fn from_ascii_radix(src: &[u8], radix: u32) -> Result<$int_ty, ParseIntError> {
1542 use self::IntErrorKind::*;
1543 use self::ParseIntError as PIE;
1544
1545 if 2 > radix || radix > 36 {
1546 from_ascii_radix_panic(radix);
1547 }
1548
1549 if src.is_empty() {
1550 return Err(PIE { kind: Empty });
1551 }
1552
1553 #[allow(unused_comparisons)]
1554 let is_signed_ty = 0 > <$int_ty>::MIN;
1555
1556 let (is_positive, mut digits) = match src {
1557 [b'+' | b'-'] => {
1558 return Err(PIE { kind: InvalidDigit });
1559 }
1560 [b'+', rest @ ..] => (true, rest),
1561 [b'-', rest @ ..] if is_signed_ty => (false, rest),
1562 _ => (true, src),
1563 };
1564
1565 let mut result = 0;
1566
1567 macro_rules! unwrap_or_PIE {
1568 ($option:expr, $kind:ident) => {
1569 match $option {
1570 Some(value) => value,
1571 None => return Err(PIE { kind: $kind }),
1572 }
1573 };
1574 }
1575
1576 if can_not_overflow::<$int_ty>(radix, is_signed_ty, digits) {
1577 // If the len of the str is short compared to the range of the type
1578 // we are parsing into, then we can be certain that an overflow will not occur.
1579 // This bound is when `radix.pow(digits.len()) - 1 <= T::MAX` but the condition
1580 // above is a faster (conservative) approximation of this.
1581 //
1582 // Consider radix 16 as it has the highest information density per digit and will thus overflow the earliest:
1583 // `u8::MAX` is `ff` - any str of len 2 is guaranteed to not overflow.
1584 // `i8::MAX` is `7f` - only a str of len 1 is guaranteed to not overflow.
1585 macro_rules! run_unchecked_loop {
1586 ($unchecked_additive_op:tt) => {{
1587 while let [c, rest @ ..] = digits {
1588 result = result * (radix as $int_ty);
1589 let x = unwrap_or_PIE!((*c as char).to_digit(radix), InvalidDigit);
1590 result = result $unchecked_additive_op (x as $int_ty);
1591 digits = rest;
1592 }
1593 }};
1594 }
1595 if is_positive {
1596 run_unchecked_loop!(+)
1597 } else {
1598 run_unchecked_loop!(-)
1599 };
1600 } else {
1601 macro_rules! run_checked_loop {
1602 ($checked_additive_op:ident, $overflow_err:ident) => {{
1603 while let [c, rest @ ..] = digits {
1604 // When `radix` is passed in as a literal, rather than doing a slow `imul`
1605 // the compiler can use shifts if `radix` can be expressed as a
1606 // sum of powers of 2 (x*10 can be written as x*8 + x*2).
1607 // When the compiler can't use these optimisations,
1608 // the latency of the multiplication can be hidden by issuing it
1609 // before the result is needed to improve performance on
1610 // modern out-of-order CPU as multiplication here is slower
1611 // than the other instructions, we can get the end result faster
1612 // doing multiplication first and let the CPU spends other cycles
1613 // doing other computation and get multiplication result later.
1614 let mul = result.checked_mul(radix as $int_ty);
1615 let x = unwrap_or_PIE!((*c as char).to_digit(radix), InvalidDigit) as $int_ty;
1616 result = unwrap_or_PIE!(mul, $overflow_err);
1617 result = unwrap_or_PIE!(<$int_ty>::$checked_additive_op(result, x), $overflow_err);
1618 digits = rest;
1619 }
1620 }};
1621 }
1622 if is_positive {
1623 run_checked_loop!(checked_add, PosOverflow)
1624 } else {
1625 run_checked_loop!(checked_sub, NegOverflow)
1626 };
1627 }
1628 Ok(result)
1629 }
1630 }
1631 )*}
1632}
1633
1634from_str_int_impl! { signed isize i8 i16 i32 i64 i128 }
1635from_str_int_impl! { unsigned usize u8 u16 u32 u64 u128 }
1636