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