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