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

core/num/
mod.rs
