core/num/
mod.rs

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