mod.rs - source
Description: Source of the Rust file `library/core/src/num/mod.rs`.

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