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