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