1 // ignore-tidy-filelength
3 //! Numeric traits and functions for the built-in numeric types.
5 #![stable(feature = "rust1", since = "1.0.0")]
7 use crate::convert::{TryFrom, Infallible};
12 use crate::str::FromStr;
14 macro_rules! impl_nonzero_fmt {
15 ( #[$stability: meta] ( $( $Trait: ident ),+ ) for $Ty: ident ) => {
18 impl fmt::$Trait for $Ty {
20 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
28 macro_rules! doc_comment {
29 ($x:expr, $($tt:tt)*) => {
35 macro_rules! nonzero_integers {
36 ( $( #[$stability: meta] $Ty: ident($Int: ty); )+ ) => {
39 concat!("An integer that is known not to equal zero.
41 This enables some memory layout optimization.
42 For example, `Option<", stringify!($Ty), ">` is the same size as `", stringify!($Int), "`:
45 use std::mem::size_of;
46 assert_eq!(size_of::<Option<core::num::", stringify!($Ty), ">>(), size_of::<", stringify!($Int),
50 #[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
52 #[rustc_layout_scalar_valid_range_start(1)]
53 #[cfg_attr(not(stage0), rustc_nonnull_optimization_guaranteed)]
58 /// Creates a non-zero without checking the value.
62 /// The value must not be zero.
65 pub const unsafe fn new_unchecked(n: $Int) -> Self {
69 /// Creates a non-zero if the given value is not zero.
72 pub fn new(n: $Int) -> Option<Self> {
74 Some(unsafe { $Ty(n) })
80 /// Returns the value as a primitive type.
83 pub const fn get(self) -> $Int {
89 #[stable(feature = "from_nonzero", since = "1.31.0")]
90 impl From<$Ty> for $Int {
91 fn from(nonzero: $Ty) -> Self {
97 #[$stability] (Debug, Display, Binary, Octal, LowerHex, UpperHex) for $Ty
104 #[stable(feature = "nonzero", since = "1.28.0")] NonZeroU8(u8);
105 #[stable(feature = "nonzero", since = "1.28.0")] NonZeroU16(u16);
106 #[stable(feature = "nonzero", since = "1.28.0")] NonZeroU32(u32);
107 #[stable(feature = "nonzero", since = "1.28.0")] NonZeroU64(u64);
108 #[stable(feature = "nonzero", since = "1.28.0")] NonZeroU128(u128);
109 #[stable(feature = "nonzero", since = "1.28.0")] NonZeroUsize(usize);
110 #[stable(feature = "signed_nonzero", since = "1.34.0")] NonZeroI8(i8);
111 #[stable(feature = "signed_nonzero", since = "1.34.0")] NonZeroI16(i16);
112 #[stable(feature = "signed_nonzero", since = "1.34.0")] NonZeroI32(i32);
113 #[stable(feature = "signed_nonzero", since = "1.34.0")] NonZeroI64(i64);
114 #[stable(feature = "signed_nonzero", since = "1.34.0")] NonZeroI128(i128);
115 #[stable(feature = "signed_nonzero", since = "1.34.0")] NonZeroIsize(isize);
118 macro_rules! from_str_radix_nzint_impl {
120 #[stable(feature = "nonzero_parse", since = "1.35.0")]
121 impl FromStr for $t {
122 type Err = ParseIntError;
123 fn from_str(src: &str) -> Result<Self, Self::Err> {
124 Self::new(from_str_radix(src, 10)?)
125 .ok_or(ParseIntError {
126 kind: IntErrorKind::Zero
133 from_str_radix_nzint_impl! { NonZeroU8 NonZeroU16 NonZeroU32 NonZeroU64 NonZeroU128 NonZeroUsize
134 NonZeroI8 NonZeroI16 NonZeroI32 NonZeroI64 NonZeroI128 NonZeroIsize }
136 /// Provides intentionally-wrapped arithmetic on `T`.
138 /// Operations like `+` on `u32` values is intended to never overflow,
139 /// and in some debug configurations overflow is detected and results
140 /// in a panic. While most arithmetic falls into this category, some
141 /// code explicitly expects and relies upon modular arithmetic (e.g.,
144 /// Wrapping arithmetic can be achieved either through methods like
145 /// `wrapping_add`, or through the `Wrapping<T>` type, which says that
146 /// all standard arithmetic operations on the underlying value are
147 /// intended to have wrapping semantics.
149 /// The underlying value can be retrieved through the `.0` index of the
150 /// `Wrapping` tuple.
155 /// use std::num::Wrapping;
157 /// let zero = Wrapping(0u32);
158 /// let one = Wrapping(1u32);
160 /// assert_eq!(std::u32::MAX, (zero - one).0);
162 #[stable(feature = "rust1", since = "1.0.0")]
163 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Copy, Default, Hash)]
165 pub struct Wrapping<T>(#[stable(feature = "rust1", since = "1.0.0")]
168 #[stable(feature = "rust1", since = "1.0.0")]
169 impl<T: fmt::Debug> fmt::Debug for Wrapping<T> {
170 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
175 #[stable(feature = "wrapping_display", since = "1.10.0")]
176 impl<T: fmt::Display> fmt::Display for Wrapping<T> {
177 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
182 #[stable(feature = "wrapping_fmt", since = "1.11.0")]
183 impl<T: fmt::Binary> fmt::Binary for Wrapping<T> {
184 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
189 #[stable(feature = "wrapping_fmt", since = "1.11.0")]
190 impl<T: fmt::Octal> fmt::Octal for Wrapping<T> {
191 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
196 #[stable(feature = "wrapping_fmt", since = "1.11.0")]
197 impl<T: fmt::LowerHex> fmt::LowerHex for Wrapping<T> {
198 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
203 #[stable(feature = "wrapping_fmt", since = "1.11.0")]
204 impl<T: fmt::UpperHex> fmt::UpperHex for Wrapping<T> {
205 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
210 // All these modules are technically private and only exposed for coretests:
218 macro_rules! usize_isize_to_xe_bytes_doc {
221 **Note**: This function returns an array of length 2, 4 or 8 bytes
222 depending on the target pointer size.
228 macro_rules! usize_isize_from_xe_bytes_doc {
231 **Note**: This function takes an array of length 2, 4 or 8 bytes
232 depending on the target pointer size.
237 // `Int` + `SignedInt` implemented for signed integers
238 macro_rules! int_impl {
239 ($SelfT:ty, $ActualT:ident, $UnsignedT:ty, $BITS:expr, $Min:expr, $Max:expr, $Feature:expr,
240 $EndFeature:expr, $rot:expr, $rot_op:expr, $rot_result:expr, $swap_op:expr, $swapped:expr,
241 $reversed:expr, $le_bytes:expr, $be_bytes:expr,
242 $to_xe_bytes_doc:expr, $from_xe_bytes_doc:expr) => {
244 concat!("Returns the smallest value that can be represented by this integer type.
251 ", $Feature, "assert_eq!(", stringify!($SelfT), "::min_value(), ", stringify!($Min), ");",
254 #[stable(feature = "rust1", since = "1.0.0")]
257 pub const fn min_value() -> Self {
258 !0 ^ ((!0 as $UnsignedT) >> 1) as Self
263 concat!("Returns the largest value that can be represented by this integer type.
270 ", $Feature, "assert_eq!(", stringify!($SelfT), "::max_value(), ", stringify!($Max), ");",
273 #[stable(feature = "rust1", since = "1.0.0")]
276 pub const fn max_value() -> Self {
282 concat!("Converts a string slice in a given base to an integer.
284 The string is expected to be an optional `+` or `-` sign followed by digits.
285 Leading and trailing whitespace represent an error. Digits are a subset of these characters,
286 depending on `radix`:
294 This function panics if `radix` is not in the range from 2 to 36.
301 ", $Feature, "assert_eq!(", stringify!($SelfT), "::from_str_radix(\"A\", 16), Ok(10));",
304 #[stable(feature = "rust1", since = "1.0.0")]
305 pub fn from_str_radix(src: &str, radix: u32) -> Result<Self, ParseIntError> {
306 from_str_radix(src, radix)
311 concat!("Returns the number of ones in the binary representation of `self`.
318 ", $Feature, "let n = 0b100_0000", stringify!($SelfT), ";
320 assert_eq!(n.count_ones(), 1);",
324 #[stable(feature = "rust1", since = "1.0.0")]
326 pub const fn count_ones(self) -> u32 { (self as $UnsignedT).count_ones() }
330 concat!("Returns the number of zeros in the binary representation of `self`.
337 ", $Feature, "assert_eq!(", stringify!($SelfT), "::max_value().count_zeros(), 1);", $EndFeature, "
339 #[stable(feature = "rust1", since = "1.0.0")]
341 pub const fn count_zeros(self) -> u32 {
347 concat!("Returns the number of leading zeros in the binary representation of `self`.
354 ", $Feature, "let n = -1", stringify!($SelfT), ";
356 assert_eq!(n.leading_zeros(), 0);",
359 #[stable(feature = "rust1", since = "1.0.0")]
361 pub const fn leading_zeros(self) -> u32 {
362 (self as $UnsignedT).leading_zeros()
367 concat!("Returns the number of trailing zeros in the binary representation of `self`.
374 ", $Feature, "let n = -4", stringify!($SelfT), ";
376 assert_eq!(n.trailing_zeros(), 2);",
379 #[stable(feature = "rust1", since = "1.0.0")]
381 pub const fn trailing_zeros(self) -> u32 {
382 (self as $UnsignedT).trailing_zeros()
387 concat!("Shifts the bits to the left by a specified amount, `n`,
388 wrapping the truncated bits to the end of the resulting integer.
390 Please note this isn't the same operation as the `<<` shifting operator!
397 let n = ", $rot_op, stringify!($SelfT), ";
398 let m = ", $rot_result, ";
400 assert_eq!(n.rotate_left(", $rot, "), m);
402 #[stable(feature = "rust1", since = "1.0.0")]
403 #[must_use = "this returns the result of the operation, \
404 without modifying the original"]
406 pub const fn rotate_left(self, n: u32) -> Self {
407 (self as $UnsignedT).rotate_left(n) as Self
412 concat!("Shifts the bits to the right by a specified amount, `n`,
413 wrapping the truncated bits to the beginning of the resulting
416 Please note this isn't the same operation as the `>>` shifting operator!
423 let n = ", $rot_result, stringify!($SelfT), ";
424 let m = ", $rot_op, ";
426 assert_eq!(n.rotate_right(", $rot, "), m);
428 #[stable(feature = "rust1", since = "1.0.0")]
429 #[must_use = "this returns the result of the operation, \
430 without modifying the original"]
432 pub const fn rotate_right(self, n: u32) -> Self {
433 (self as $UnsignedT).rotate_right(n) as Self
438 concat!("Reverses the byte order of the integer.
445 let n = ", $swap_op, stringify!($SelfT), ";
447 let m = n.swap_bytes();
449 assert_eq!(m, ", $swapped, ");
451 #[stable(feature = "rust1", since = "1.0.0")]
453 pub const fn swap_bytes(self) -> Self {
454 (self as $UnsignedT).swap_bytes() as Self
459 concat!("Reverses the bit pattern of the integer.
466 #![feature(reverse_bits)]
468 let n = ", $swap_op, stringify!($SelfT), ";
469 let m = n.reverse_bits();
471 assert_eq!(m, ", $reversed, ");
473 #[unstable(feature = "reverse_bits", issue = "48763")]
474 #[rustc_const_unstable(feature = "const_int_conversion")]
477 pub const fn reverse_bits(self) -> Self {
478 (self as $UnsignedT).reverse_bits() as Self
483 concat!("Converts an integer from big endian to the target's endianness.
485 On big endian this is a no-op. On little endian the bytes are swapped.
492 ", $Feature, "let n = 0x1A", stringify!($SelfT), ";
494 if cfg!(target_endian = \"big\") {
495 assert_eq!(", stringify!($SelfT), "::from_be(n), n)
497 assert_eq!(", stringify!($SelfT), "::from_be(n), n.swap_bytes())
501 #[stable(feature = "rust1", since = "1.0.0")]
503 pub const fn from_be(x: Self) -> Self {
504 #[cfg(target_endian = "big")]
508 #[cfg(not(target_endian = "big"))]
516 concat!("Converts an integer from little endian to the target's endianness.
518 On little endian this is a no-op. On big endian the bytes are swapped.
525 ", $Feature, "let n = 0x1A", stringify!($SelfT), ";
527 if cfg!(target_endian = \"little\") {
528 assert_eq!(", stringify!($SelfT), "::from_le(n), n)
530 assert_eq!(", stringify!($SelfT), "::from_le(n), n.swap_bytes())
534 #[stable(feature = "rust1", since = "1.0.0")]
536 pub const fn from_le(x: Self) -> Self {
537 #[cfg(target_endian = "little")]
541 #[cfg(not(target_endian = "little"))]
549 concat!("Converts `self` to big endian from the target's endianness.
551 On big endian this is a no-op. On little endian the bytes are swapped.
558 ", $Feature, "let n = 0x1A", stringify!($SelfT), ";
560 if cfg!(target_endian = \"big\") {
561 assert_eq!(n.to_be(), n)
563 assert_eq!(n.to_be(), n.swap_bytes())
567 #[stable(feature = "rust1", since = "1.0.0")]
569 pub const fn to_be(self) -> Self { // or not to be?
570 #[cfg(target_endian = "big")]
574 #[cfg(not(target_endian = "big"))]
582 concat!("Converts `self` to little endian from the target's endianness.
584 On little endian this is a no-op. On big endian the bytes are swapped.
591 ", $Feature, "let n = 0x1A", stringify!($SelfT), ";
593 if cfg!(target_endian = \"little\") {
594 assert_eq!(n.to_le(), n)
596 assert_eq!(n.to_le(), n.swap_bytes())
600 #[stable(feature = "rust1", since = "1.0.0")]
602 pub const fn to_le(self) -> Self {
603 #[cfg(target_endian = "little")]
607 #[cfg(not(target_endian = "little"))]
615 concat!("Checked integer addition. Computes `self + rhs`, returning `None`
616 if overflow occurred.
623 ", $Feature, "assert_eq!((", stringify!($SelfT),
624 "::max_value() - 2).checked_add(1), Some(", stringify!($SelfT), "::max_value() - 1));
625 assert_eq!((", stringify!($SelfT), "::max_value() - 2).checked_add(3), None);",
628 #[stable(feature = "rust1", since = "1.0.0")]
629 #[must_use = "this returns the result of the operation, \
630 without modifying the original"]
632 pub fn checked_add(self, rhs: Self) -> Option<Self> {
633 let (a, b) = self.overflowing_add(rhs);
634 if b {None} else {Some(a)}
639 concat!("Checked integer subtraction. Computes `self - rhs`, returning `None` if
647 ", $Feature, "assert_eq!((", stringify!($SelfT),
648 "::min_value() + 2).checked_sub(1), Some(", stringify!($SelfT), "::min_value() + 1));
649 assert_eq!((", stringify!($SelfT), "::min_value() + 2).checked_sub(3), None);",
652 #[stable(feature = "rust1", since = "1.0.0")]
653 #[must_use = "this returns the result of the operation, \
654 without modifying the original"]
656 pub fn checked_sub(self, rhs: Self) -> Option<Self> {
657 let (a, b) = self.overflowing_sub(rhs);
658 if b {None} else {Some(a)}
663 concat!("Checked integer multiplication. Computes `self * rhs`, returning `None` if
671 ", $Feature, "assert_eq!(", stringify!($SelfT),
672 "::max_value().checked_mul(1), Some(", stringify!($SelfT), "::max_value()));
673 assert_eq!(", stringify!($SelfT), "::max_value().checked_mul(2), None);",
676 #[stable(feature = "rust1", since = "1.0.0")]
677 #[must_use = "this returns the result of the operation, \
678 without modifying the original"]
680 pub fn checked_mul(self, rhs: Self) -> Option<Self> {
681 let (a, b) = self.overflowing_mul(rhs);
682 if b {None} else {Some(a)}
687 concat!("Checked integer division. Computes `self / rhs`, returning `None` if `rhs == 0`
688 or the division results in overflow.
695 ", $Feature, "assert_eq!((", stringify!($SelfT),
696 "::min_value() + 1).checked_div(-1), Some(", stringify!($Max), "));
697 assert_eq!(", stringify!($SelfT), "::min_value().checked_div(-1), None);
698 assert_eq!((1", stringify!($SelfT), ").checked_div(0), None);",
701 #[stable(feature = "rust1", since = "1.0.0")]
702 #[must_use = "this returns the result of the operation, \
703 without modifying the original"]
705 pub fn checked_div(self, rhs: Self) -> Option<Self> {
706 if rhs == 0 || (self == Self::min_value() && rhs == -1) {
709 Some(unsafe { intrinsics::unchecked_div(self, rhs) })
715 concat!("Checked Euclidean division. Computes `self.div_euclid(rhs)`,
716 returning `None` if `rhs == 0` or the division results in overflow.
723 #![feature(euclidean_division)]
724 assert_eq!((", stringify!($SelfT),
725 "::min_value() + 1).checked_div_euclid(-1), Some(", stringify!($Max), "));
726 assert_eq!(", stringify!($SelfT), "::min_value().checked_div_euclid(-1), None);
727 assert_eq!((1", stringify!($SelfT), ").checked_div_euclid(0), None);
729 #[unstable(feature = "euclidean_division", issue = "49048")]
730 #[must_use = "this returns the result of the operation, \
731 without modifying the original"]
733 pub fn checked_div_euclid(self, rhs: Self) -> Option<Self> {
734 if rhs == 0 || (self == Self::min_value() && rhs == -1) {
737 Some(self.div_euclid(rhs))
743 concat!("Checked integer remainder. Computes `self % rhs`, returning `None` if
744 `rhs == 0` or the division results in overflow.
751 ", $Feature, "use std::", stringify!($SelfT), ";
753 assert_eq!(5", stringify!($SelfT), ".checked_rem(2), Some(1));
754 assert_eq!(5", stringify!($SelfT), ".checked_rem(0), None);
755 assert_eq!(", stringify!($SelfT), "::MIN.checked_rem(-1), None);",
758 #[stable(feature = "wrapping", since = "1.7.0")]
759 #[must_use = "this returns the result of the operation, \
760 without modifying the original"]
762 pub fn checked_rem(self, rhs: Self) -> Option<Self> {
763 if rhs == 0 || (self == Self::min_value() && rhs == -1) {
766 Some(unsafe { intrinsics::unchecked_rem(self, rhs) })
772 concat!("Checked Euclidean remainder. Computes `self.rem_euclid(rhs)`, returning `None`
773 if `rhs == 0` or the division results in overflow.
780 #![feature(euclidean_division)]
781 use std::", stringify!($SelfT), ";
783 assert_eq!(5", stringify!($SelfT), ".checked_rem_euclid(2), Some(1));
784 assert_eq!(5", stringify!($SelfT), ".checked_rem_euclid(0), None);
785 assert_eq!(", stringify!($SelfT), "::MIN.checked_rem_euclid(-1), None);
787 #[unstable(feature = "euclidean_division", issue = "49048")]
788 #[must_use = "this returns the result of the operation, \
789 without modifying the original"]
791 pub fn checked_rem_euclid(self, rhs: Self) -> Option<Self> {
792 if rhs == 0 || (self == Self::min_value() && rhs == -1) {
795 Some(self.rem_euclid(rhs))
801 concat!("Checked negation. Computes `-self`, returning `None` if `self == MIN`.
808 ", $Feature, "use std::", stringify!($SelfT), ";
810 assert_eq!(5", stringify!($SelfT), ".checked_neg(), Some(-5));
811 assert_eq!(", stringify!($SelfT), "::MIN.checked_neg(), None);",
814 #[stable(feature = "wrapping", since = "1.7.0")]
816 pub fn checked_neg(self) -> Option<Self> {
817 let (a, b) = self.overflowing_neg();
818 if b {None} else {Some(a)}
823 concat!("Checked shift left. Computes `self << rhs`, returning `None` if `rhs` is larger
824 than or equal to the number of bits in `self`.
831 ", $Feature, "assert_eq!(0x1", stringify!($SelfT), ".checked_shl(4), Some(0x10));
832 assert_eq!(0x1", stringify!($SelfT), ".checked_shl(129), None);",
835 #[stable(feature = "wrapping", since = "1.7.0")]
836 #[must_use = "this returns the result of the operation, \
837 without modifying the original"]
839 pub fn checked_shl(self, rhs: u32) -> Option<Self> {
840 let (a, b) = self.overflowing_shl(rhs);
841 if b {None} else {Some(a)}
846 concat!("Checked shift right. Computes `self >> rhs`, returning `None` if `rhs` is
847 larger than or equal to the number of bits in `self`.
854 ", $Feature, "assert_eq!(0x10", stringify!($SelfT), ".checked_shr(4), Some(0x1));
855 assert_eq!(0x10", stringify!($SelfT), ".checked_shr(128), None);",
858 #[stable(feature = "wrapping", since = "1.7.0")]
859 #[must_use = "this returns the result of the operation, \
860 without modifying the original"]
862 pub fn checked_shr(self, rhs: u32) -> Option<Self> {
863 let (a, b) = self.overflowing_shr(rhs);
864 if b {None} else {Some(a)}
869 concat!("Checked absolute value. Computes `self.abs()`, returning `None` if
877 ", $Feature, "use std::", stringify!($SelfT), ";
879 assert_eq!((-5", stringify!($SelfT), ").checked_abs(), Some(5));
880 assert_eq!(", stringify!($SelfT), "::MIN.checked_abs(), None);",
883 #[stable(feature = "no_panic_abs", since = "1.13.0")]
885 pub fn checked_abs(self) -> Option<Self> {
886 if self.is_negative() {
895 concat!("Checked exponentiation. Computes `self.pow(exp)`, returning `None` if
903 ", $Feature, "assert_eq!(8", stringify!($SelfT), ".checked_pow(2), Some(64));
904 assert_eq!(", stringify!($SelfT), "::max_value().checked_pow(2), None);",
908 #[stable(feature = "no_panic_pow", since = "1.34.0")]
909 #[must_use = "this returns the result of the operation, \
910 without modifying the original"]
912 pub fn checked_pow(self, mut exp: u32) -> Option<Self> {
914 let mut acc: Self = 1;
918 acc = acc.checked_mul(base)?;
921 base = base.checked_mul(base)?;
924 // Deal with the final bit of the exponent separately, since
925 // squaring the base afterwards is not necessary and may cause a
926 // needless overflow.
928 acc = acc.checked_mul(base)?;
936 concat!("Saturating integer addition. Computes `self + rhs`, saturating at the numeric
937 bounds instead of overflowing.
944 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".saturating_add(1), 101);
945 assert_eq!(", stringify!($SelfT), "::max_value().saturating_add(100), ", stringify!($SelfT),
950 #[stable(feature = "rust1", since = "1.0.0")]
951 #[rustc_const_unstable(feature = "const_saturating_int_methods")]
952 #[must_use = "this returns the result of the operation, \
953 without modifying the original"]
955 pub const fn saturating_add(self, rhs: Self) -> Self {
956 intrinsics::saturating_add(self, rhs)
962 concat!("Saturating integer subtraction. Computes `self - rhs`, saturating at the
963 numeric bounds instead of overflowing.
970 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".saturating_sub(127), -27);
971 assert_eq!(", stringify!($SelfT), "::min_value().saturating_sub(100), ", stringify!($SelfT),
975 #[stable(feature = "rust1", since = "1.0.0")]
976 #[rustc_const_unstable(feature = "const_saturating_int_methods")]
977 #[must_use = "this returns the result of the operation, \
978 without modifying the original"]
980 pub const fn saturating_sub(self, rhs: Self) -> Self {
981 intrinsics::saturating_sub(self, rhs)
986 concat!("Saturating integer negation. Computes `-self`, returning `MAX` if `self == MIN`
987 instead of overflowing.
994 ", $Feature, "#![feature(saturating_neg)]
995 assert_eq!(100", stringify!($SelfT), ".saturating_neg(), -100);
996 assert_eq!((-100", stringify!($SelfT), ").saturating_neg(), 100);
997 assert_eq!(", stringify!($SelfT), "::min_value().saturating_neg(), ", stringify!($SelfT),
999 assert_eq!(", stringify!($SelfT), "::max_value().saturating_neg(), ", stringify!($SelfT),
1000 "::min_value() + 1);",
1004 #[unstable(feature = "saturating_neg", issue = "59983")]
1006 pub fn saturating_neg(self) -> Self {
1007 intrinsics::saturating_sub(0, self)
1012 concat!("Saturating absolute value. Computes `self.abs()`, returning `MAX` if `self ==
1013 MIN` instead of overflowing.
1020 ", $Feature, "#![feature(saturating_neg)]
1021 assert_eq!(100", stringify!($SelfT), ".saturating_abs(), 100);
1022 assert_eq!((-100", stringify!($SelfT), ").saturating_abs(), 100);
1023 assert_eq!(", stringify!($SelfT), "::min_value().saturating_abs(), ", stringify!($SelfT),
1025 assert_eq!((", stringify!($SelfT), "::min_value() + 1).saturating_abs(), ", stringify!($SelfT),
1030 #[unstable(feature = "saturating_neg", issue = "59983")]
1032 pub fn saturating_abs(self) -> Self {
1033 if self.is_negative() {
1034 self.saturating_neg()
1042 concat!("Saturating integer multiplication. Computes `self * rhs`, saturating at the
1043 numeric bounds instead of overflowing.
1050 ", $Feature, "use std::", stringify!($SelfT), ";
1052 assert_eq!(10", stringify!($SelfT), ".saturating_mul(12), 120);
1053 assert_eq!(", stringify!($SelfT), "::MAX.saturating_mul(10), ", stringify!($SelfT), "::MAX);
1054 assert_eq!(", stringify!($SelfT), "::MIN.saturating_mul(10), ", stringify!($SelfT), "::MIN);",
1057 #[stable(feature = "wrapping", since = "1.7.0")]
1058 #[must_use = "this returns the result of the operation, \
1059 without modifying the original"]
1061 pub fn saturating_mul(self, rhs: Self) -> Self {
1062 self.checked_mul(rhs).unwrap_or_else(|| {
1063 if (self < 0 && rhs < 0) || (self > 0 && rhs > 0) {
1073 concat!("Saturating integer exponentiation. Computes `self.pow(exp)`,
1074 saturating at the numeric bounds instead of overflowing.
1081 ", $Feature, "use std::", stringify!($SelfT), ";
1083 assert_eq!((-4", stringify!($SelfT), ").saturating_pow(3), -64);
1084 assert_eq!(", stringify!($SelfT), "::MIN.saturating_pow(2), ", stringify!($SelfT), "::MAX);
1085 assert_eq!(", stringify!($SelfT), "::MIN.saturating_pow(3), ", stringify!($SelfT), "::MIN);",
1088 #[stable(feature = "no_panic_pow", since = "1.34.0")]
1089 #[must_use = "this returns the result of the operation, \
1090 without modifying the original"]
1092 pub fn saturating_pow(self, exp: u32) -> Self {
1093 match self.checked_pow(exp) {
1095 None if self < 0 && exp % 2 == 1 => Self::min_value(),
1096 None => Self::max_value(),
1102 concat!("Wrapping (modular) addition. Computes `self + rhs`, wrapping around at the
1103 boundary of the type.
1110 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".wrapping_add(27), 127);
1111 assert_eq!(", stringify!($SelfT), "::max_value().wrapping_add(2), ", stringify!($SelfT),
1112 "::min_value() + 1);",
1115 #[stable(feature = "rust1", since = "1.0.0")]
1116 #[must_use = "this returns the result of the operation, \
1117 without modifying the original"]
1119 pub const fn wrapping_add(self, rhs: Self) -> Self {
1120 intrinsics::overflowing_add(self, rhs)
1125 concat!("Wrapping (modular) subtraction. Computes `self - rhs`, wrapping around at the
1126 boundary of the type.
1133 ", $Feature, "assert_eq!(0", stringify!($SelfT), ".wrapping_sub(127), -127);
1134 assert_eq!((-2", stringify!($SelfT), ").wrapping_sub(", stringify!($SelfT), "::max_value()), ",
1135 stringify!($SelfT), "::max_value());",
1138 #[stable(feature = "rust1", since = "1.0.0")]
1139 #[must_use = "this returns the result of the operation, \
1140 without modifying the original"]
1142 pub const fn wrapping_sub(self, rhs: Self) -> Self {
1143 intrinsics::overflowing_sub(self, rhs)
1148 concat!("Wrapping (modular) multiplication. Computes `self * rhs`, wrapping around at
1149 the boundary of the type.
1156 ", $Feature, "assert_eq!(10", stringify!($SelfT), ".wrapping_mul(12), 120);
1157 assert_eq!(11i8.wrapping_mul(12), -124);",
1160 #[stable(feature = "rust1", since = "1.0.0")]
1161 #[must_use = "this returns the result of the operation, \
1162 without modifying the original"]
1164 pub const fn wrapping_mul(self, rhs: Self) -> Self {
1165 intrinsics::overflowing_mul(self, rhs)
1170 concat!("Wrapping (modular) division. Computes `self / rhs`, wrapping around at the
1171 boundary of the type.
1173 The only case where such wrapping can occur is when one divides `MIN / -1` on a signed type (where
1174 `MIN` is the negative minimal value for the type); this is equivalent to `-MIN`, a positive value
1175 that is too large to represent in the type. In such a case, this function returns `MIN` itself.
1179 This function will panic if `rhs` is 0.
1186 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".wrapping_div(10), 10);
1187 assert_eq!((-128i8).wrapping_div(-1), -128);",
1190 #[stable(feature = "num_wrapping", since = "1.2.0")]
1191 #[must_use = "this returns the result of the operation, \
1192 without modifying the original"]
1194 pub fn wrapping_div(self, rhs: Self) -> Self {
1195 self.overflowing_div(rhs).0
1200 concat!("Wrapping Euclidean division. Computes `self.div_euclid(rhs)`,
1201 wrapping around at the boundary of the type.
1203 Wrapping will only occur in `MIN / -1` on a signed type (where `MIN` is the negative minimal value
1204 for the type). This is equivalent to `-MIN`, a positive value that is too large to represent in the
1205 type. In this case, this method returns `MIN` itself.
1209 This function will panic if `rhs` is 0.
1216 #![feature(euclidean_division)]
1217 assert_eq!(100", stringify!($SelfT), ".wrapping_div_euclid(10), 10);
1218 assert_eq!((-128i8).wrapping_div_euclid(-1), -128);
1220 #[unstable(feature = "euclidean_division", issue = "49048")]
1221 #[must_use = "this returns the result of the operation, \
1222 without modifying the original"]
1224 pub fn wrapping_div_euclid(self, rhs: Self) -> Self {
1225 self.overflowing_div_euclid(rhs).0
1230 concat!("Wrapping (modular) remainder. Computes `self % rhs`, wrapping around at the
1231 boundary of the type.
1233 Such wrap-around never actually occurs mathematically; implementation artifacts make `x % y`
1234 invalid for `MIN / -1` on a signed type (where `MIN` is the negative minimal value). In such a case,
1235 this function returns `0`.
1239 This function will panic if `rhs` is 0.
1246 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".wrapping_rem(10), 0);
1247 assert_eq!((-128i8).wrapping_rem(-1), 0);",
1250 #[stable(feature = "num_wrapping", since = "1.2.0")]
1251 #[must_use = "this returns the result of the operation, \
1252 without modifying the original"]
1254 pub fn wrapping_rem(self, rhs: Self) -> Self {
1255 self.overflowing_rem(rhs).0
1260 concat!("Wrapping Euclidean remainder. Computes `self.rem_euclid(rhs)`, wrapping around
1261 at the boundary of the type.
1263 Wrapping will only occur in `MIN % -1` on a signed type (where `MIN` is the negative minimal value
1264 for the type). In this case, this method returns 0.
1268 This function will panic if `rhs` is 0.
1275 #![feature(euclidean_division)]
1276 assert_eq!(100", stringify!($SelfT), ".wrapping_rem_euclid(10), 0);
1277 assert_eq!((-128i8).wrapping_rem_euclid(-1), 0);
1279 #[unstable(feature = "euclidean_division", issue = "49048")]
1280 #[must_use = "this returns the result of the operation, \
1281 without modifying the original"]
1283 pub fn wrapping_rem_euclid(self, rhs: Self) -> Self {
1284 self.overflowing_rem_euclid(rhs).0
1289 concat!("Wrapping (modular) negation. Computes `-self`, wrapping around at the boundary
1292 The only case where such wrapping can occur is when one negates `MIN` on a signed type (where `MIN`
1293 is the negative minimal value for the type); this is a positive value that is too large to represent
1294 in the type. In such a case, this function returns `MIN` itself.
1301 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".wrapping_neg(), -100);
1302 assert_eq!(", stringify!($SelfT), "::min_value().wrapping_neg(), ", stringify!($SelfT),
1306 #[stable(feature = "num_wrapping", since = "1.2.0")]
1308 pub const fn wrapping_neg(self) -> Self {
1309 self.overflowing_neg().0
1314 concat!("Panic-free bitwise shift-left; yields `self << mask(rhs)`, where `mask` removes
1315 any high-order bits of `rhs` that would cause the shift to exceed the bitwidth of the type.
1317 Note that this is *not* the same as a rotate-left; the RHS of a wrapping shift-left is restricted to
1318 the range of the type, rather than the bits shifted out of the LHS being returned to the other end.
1319 The primitive integer types all implement a `rotate_left` function, which may be what you want
1327 ", $Feature, "assert_eq!((-1", stringify!($SelfT), ").wrapping_shl(7), -128);
1328 assert_eq!((-1", stringify!($SelfT), ").wrapping_shl(128), -1);",
1331 #[stable(feature = "num_wrapping", since = "1.2.0")]
1332 #[must_use = "this returns the result of the operation, \
1333 without modifying the original"]
1335 pub const fn wrapping_shl(self, rhs: u32) -> Self {
1337 intrinsics::unchecked_shl(self, (rhs & ($BITS - 1)) as $SelfT)
1343 concat!("Panic-free bitwise shift-right; yields `self >> mask(rhs)`, where `mask`
1344 removes any high-order bits of `rhs` that would cause the shift to exceed the bitwidth of the type.
1346 Note that this is *not* the same as a rotate-right; the RHS of a wrapping shift-right is restricted
1347 to the range of the type, rather than the bits shifted out of the LHS being returned to the other
1348 end. The primitive integer types all implement a `rotate_right` function, which may be what you want
1356 ", $Feature, "assert_eq!((-128", stringify!($SelfT), ").wrapping_shr(7), -1);
1357 assert_eq!((-128i16).wrapping_shr(64), -128);",
1360 #[stable(feature = "num_wrapping", since = "1.2.0")]
1361 #[must_use = "this returns the result of the operation, \
1362 without modifying the original"]
1364 pub const fn wrapping_shr(self, rhs: u32) -> Self {
1366 intrinsics::unchecked_shr(self, (rhs & ($BITS - 1)) as $SelfT)
1372 concat!("Wrapping (modular) absolute value. Computes `self.abs()`, wrapping around at
1373 the boundary of the type.
1375 The only case where such wrapping can occur is when one takes the absolute value of the negative
1376 minimal value for the type this is a positive value that is too large to represent in the type. In
1377 such a case, this function returns `MIN` itself.
1384 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".wrapping_abs(), 100);
1385 assert_eq!((-100", stringify!($SelfT), ").wrapping_abs(), 100);
1386 assert_eq!(", stringify!($SelfT), "::min_value().wrapping_abs(), ", stringify!($SelfT),
1388 assert_eq!((-128i8).wrapping_abs() as u8, 128);",
1391 #[stable(feature = "no_panic_abs", since = "1.13.0")]
1393 pub fn wrapping_abs(self) -> Self {
1394 if self.is_negative() {
1403 concat!("Wrapping (modular) exponentiation. Computes `self.pow(exp)`,
1404 wrapping around at the boundary of the type.
1411 ", $Feature, "assert_eq!(3", stringify!($SelfT), ".wrapping_pow(4), 81);
1412 assert_eq!(3i8.wrapping_pow(5), -13);
1413 assert_eq!(3i8.wrapping_pow(6), -39);",
1416 #[stable(feature = "no_panic_pow", since = "1.34.0")]
1417 #[must_use = "this returns the result of the operation, \
1418 without modifying the original"]
1420 pub fn wrapping_pow(self, mut exp: u32) -> Self {
1421 let mut base = self;
1422 let mut acc: Self = 1;
1426 acc = acc.wrapping_mul(base);
1429 base = base.wrapping_mul(base);
1432 // Deal with the final bit of the exponent separately, since
1433 // squaring the base afterwards is not necessary and may cause a
1434 // needless overflow.
1436 acc = acc.wrapping_mul(base);
1444 concat!("Calculates `self` + `rhs`
1446 Returns a tuple of the addition along with a boolean indicating whether an arithmetic overflow would
1447 occur. If an overflow would have occurred then the wrapped value is returned.
1454 ", $Feature, "use std::", stringify!($SelfT), ";
1456 assert_eq!(5", stringify!($SelfT), ".overflowing_add(2), (7, false));
1457 assert_eq!(", stringify!($SelfT), "::MAX.overflowing_add(1), (", stringify!($SelfT),
1458 "::MIN, true));", $EndFeature, "
1460 #[stable(feature = "wrapping", since = "1.7.0")]
1461 #[must_use = "this returns the result of the operation, \
1462 without modifying the original"]
1464 pub const fn overflowing_add(self, rhs: Self) -> (Self, bool) {
1465 let (a, b) = intrinsics::add_with_overflow(self as $ActualT, rhs as $ActualT);
1471 concat!("Calculates `self` - `rhs`
1473 Returns a tuple of the subtraction along with a boolean indicating whether an arithmetic overflow
1474 would occur. If an overflow would have occurred then the wrapped value is returned.
1481 ", $Feature, "use std::", stringify!($SelfT), ";
1483 assert_eq!(5", stringify!($SelfT), ".overflowing_sub(2), (3, false));
1484 assert_eq!(", stringify!($SelfT), "::MIN.overflowing_sub(1), (", stringify!($SelfT),
1485 "::MAX, true));", $EndFeature, "
1487 #[stable(feature = "wrapping", since = "1.7.0")]
1488 #[must_use = "this returns the result of the operation, \
1489 without modifying the original"]
1491 pub const fn overflowing_sub(self, rhs: Self) -> (Self, bool) {
1492 let (a, b) = intrinsics::sub_with_overflow(self as $ActualT, rhs as $ActualT);
1498 concat!("Calculates the multiplication of `self` and `rhs`.
1500 Returns a tuple of the multiplication along with a boolean indicating whether an arithmetic overflow
1501 would occur. If an overflow would have occurred then the wrapped value is returned.
1508 ", $Feature, "assert_eq!(5", stringify!($SelfT), ".overflowing_mul(2), (10, false));
1509 assert_eq!(1_000_000_000i32.overflowing_mul(10), (1410065408, true));",
1512 #[stable(feature = "wrapping", since = "1.7.0")]
1513 #[must_use = "this returns the result of the operation, \
1514 without modifying the original"]
1516 pub const fn overflowing_mul(self, rhs: Self) -> (Self, bool) {
1517 let (a, b) = intrinsics::mul_with_overflow(self as $ActualT, rhs as $ActualT);
1523 concat!("Calculates the divisor when `self` is divided by `rhs`.
1525 Returns a tuple of the divisor along with a boolean indicating whether an arithmetic overflow would
1526 occur. If an overflow would occur then self is returned.
1530 This function will panic if `rhs` is 0.
1537 ", $Feature, "use std::", stringify!($SelfT), ";
1539 assert_eq!(5", stringify!($SelfT), ".overflowing_div(2), (2, false));
1540 assert_eq!(", stringify!($SelfT), "::MIN.overflowing_div(-1), (", stringify!($SelfT),
1545 #[stable(feature = "wrapping", since = "1.7.0")]
1546 #[must_use = "this returns the result of the operation, \
1547 without modifying the original"]
1548 pub fn overflowing_div(self, rhs: Self) -> (Self, bool) {
1549 if self == Self::min_value() && rhs == -1 {
1558 concat!("Calculates the quotient of Euclidean division `self.div_euclid(rhs)`.
1560 Returns a tuple of the divisor along with a boolean indicating whether an arithmetic overflow would
1561 occur. If an overflow would occur then `self` is returned.
1565 This function will panic if `rhs` is 0.
1572 #![feature(euclidean_division)]
1573 use std::", stringify!($SelfT), ";
1575 assert_eq!(5", stringify!($SelfT), ".overflowing_div_euclid(2), (2, false));
1576 assert_eq!(", stringify!($SelfT), "::MIN.overflowing_div_euclid(-1), (", stringify!($SelfT),
1580 #[unstable(feature = "euclidean_division", issue = "49048")]
1581 #[must_use = "this returns the result of the operation, \
1582 without modifying the original"]
1583 pub fn overflowing_div_euclid(self, rhs: Self) -> (Self, bool) {
1584 if self == Self::min_value() && rhs == -1 {
1587 (self.div_euclid(rhs), false)
1593 concat!("Calculates the remainder when `self` is divided by `rhs`.
1595 Returns a tuple of the remainder after dividing along with a boolean indicating whether an
1596 arithmetic overflow would occur. If an overflow would occur then 0 is returned.
1600 This function will panic if `rhs` is 0.
1607 ", $Feature, "use std::", stringify!($SelfT), ";
1609 assert_eq!(5", stringify!($SelfT), ".overflowing_rem(2), (1, false));
1610 assert_eq!(", stringify!($SelfT), "::MIN.overflowing_rem(-1), (0, true));",
1614 #[stable(feature = "wrapping", since = "1.7.0")]
1615 #[must_use = "this returns the result of the operation, \
1616 without modifying the original"]
1617 pub fn overflowing_rem(self, rhs: Self) -> (Self, bool) {
1618 if self == Self::min_value() && rhs == -1 {
1628 concat!("Overflowing Euclidean remainder. Calculates `self.rem_euclid(rhs)`.
1630 Returns a tuple of the remainder after dividing along with a boolean indicating whether an
1631 arithmetic overflow would occur. If an overflow would occur then 0 is returned.
1635 This function will panic if `rhs` is 0.
1642 #![feature(euclidean_division)]
1643 use std::", stringify!($SelfT), ";
1645 assert_eq!(5", stringify!($SelfT), ".overflowing_rem_euclid(2), (1, false));
1646 assert_eq!(", stringify!($SelfT), "::MIN.overflowing_rem_euclid(-1), (0, true));
1648 #[unstable(feature = "euclidean_division", issue = "49048")]
1649 #[must_use = "this returns the result of the operation, \
1650 without modifying the original"]
1652 pub fn overflowing_rem_euclid(self, rhs: Self) -> (Self, bool) {
1653 if self == Self::min_value() && rhs == -1 {
1656 (self.rem_euclid(rhs), false)
1663 concat!("Negates self, overflowing if this is equal to the minimum value.
1665 Returns a tuple of the negated version of self along with a boolean indicating whether an overflow
1666 happened. If `self` is the minimum value (e.g., `i32::MIN` for values of type `i32`), then the
1667 minimum value will be returned again and `true` will be returned for an overflow happening.
1674 ", $Feature, "use std::", stringify!($SelfT), ";
1676 assert_eq!(2", stringify!($SelfT), ".overflowing_neg(), (-2, false));
1677 assert_eq!(", stringify!($SelfT), "::MIN.overflowing_neg(), (", stringify!($SelfT),
1678 "::MIN, true));", $EndFeature, "
1681 #[stable(feature = "wrapping", since = "1.7.0")]
1682 pub const fn overflowing_neg(self) -> (Self, bool) {
1683 ((!self).wrapping_add(1), self == Self::min_value())
1688 concat!("Shifts self left by `rhs` bits.
1690 Returns a tuple of the shifted version of self along with a boolean indicating whether the shift
1691 value was larger than or equal to the number of bits. If the shift value is too large, then value is
1692 masked (N-1) where N is the number of bits, and this value is then used to perform the shift.
1699 ", $Feature, "assert_eq!(0x1", stringify!($SelfT),".overflowing_shl(4), (0x10, false));
1700 assert_eq!(0x1i32.overflowing_shl(36), (0x10, true));",
1703 #[stable(feature = "wrapping", since = "1.7.0")]
1704 #[must_use = "this returns the result of the operation, \
1705 without modifying the original"]
1707 pub const fn overflowing_shl(self, rhs: u32) -> (Self, bool) {
1708 (self.wrapping_shl(rhs), (rhs > ($BITS - 1)))
1713 concat!("Shifts self right by `rhs` bits.
1715 Returns a tuple of the shifted version of self along with a boolean indicating whether the shift
1716 value was larger than or equal to the number of bits. If the shift value is too large, then value is
1717 masked (N-1) where N is the number of bits, and this value is then used to perform the shift.
1724 ", $Feature, "assert_eq!(0x10", stringify!($SelfT), ".overflowing_shr(4), (0x1, false));
1725 assert_eq!(0x10i32.overflowing_shr(36), (0x1, true));",
1728 #[stable(feature = "wrapping", since = "1.7.0")]
1729 #[must_use = "this returns the result of the operation, \
1730 without modifying the original"]
1732 pub const fn overflowing_shr(self, rhs: u32) -> (Self, bool) {
1733 (self.wrapping_shr(rhs), (rhs > ($BITS - 1)))
1738 concat!("Computes the absolute value of `self`.
1740 Returns a tuple of the absolute version of self along with a boolean indicating whether an overflow
1741 happened. If self is the minimum value (e.g., ", stringify!($SelfT), "::MIN for values of type
1742 ", stringify!($SelfT), "), then the minimum value will be returned again and true will be returned
1743 for an overflow happening.
1750 ", $Feature, "assert_eq!(10", stringify!($SelfT), ".overflowing_abs(), (10, false));
1751 assert_eq!((-10", stringify!($SelfT), ").overflowing_abs(), (10, false));
1752 assert_eq!((", stringify!($SelfT), "::min_value()).overflowing_abs(), (", stringify!($SelfT),
1753 "::min_value(), true));",
1756 #[stable(feature = "no_panic_abs", since = "1.13.0")]
1758 pub fn overflowing_abs(self) -> (Self, bool) {
1759 if self.is_negative() {
1760 self.overflowing_neg()
1768 concat!("Raises self to the power of `exp`, using exponentiation by squaring.
1770 Returns a tuple of the exponentiation along with a bool indicating
1771 whether an overflow happened.
1778 ", $Feature, "assert_eq!(3", stringify!($SelfT), ".overflowing_pow(4), (81, false));
1779 assert_eq!(3i8.overflowing_pow(5), (-13, true));",
1782 #[stable(feature = "no_panic_pow", since = "1.34.0")]
1783 #[must_use = "this returns the result of the operation, \
1784 without modifying the original"]
1786 pub fn overflowing_pow(self, mut exp: u32) -> (Self, bool) {
1787 let mut base = self;
1788 let mut acc: Self = 1;
1789 let mut overflown = false;
1790 // Scratch space for storing results of overflowing_mul.
1795 r = acc.overflowing_mul(base);
1800 r = base.overflowing_mul(base);
1805 // Deal with the final bit of the exponent separately, since
1806 // squaring the base afterwards is not necessary and may cause a
1807 // needless overflow.
1809 r = acc.overflowing_mul(base);
1819 concat!("Raises self to the power of `exp`, using exponentiation by squaring.
1826 ", $Feature, "let x: ", stringify!($SelfT), " = 2; // or any other integer type
1828 assert_eq!(x.pow(5), 32);",
1831 #[stable(feature = "rust1", since = "1.0.0")]
1832 #[must_use = "this returns the result of the operation, \
1833 without modifying the original"]
1835 #[rustc_inherit_overflow_checks]
1836 pub fn pow(self, mut exp: u32) -> Self {
1837 let mut base = self;
1848 // Deal with the final bit of the exponent separately, since
1849 // squaring the base afterwards is not necessary and may cause a
1850 // needless overflow.
1860 concat!("Calculates the quotient of Euclidean division of `self` by `rhs`.
1862 This computes the integer `n` such that `self = n * rhs + self.rem_euclid(rhs)`,
1863 with `0 <= self.rem_euclid(rhs) < rhs`.
1865 In other words, the result is `self / rhs` rounded to the integer `n`
1866 such that `self >= n * rhs`.
1867 If `self > 0`, this is equal to round towards zero (the default in Rust);
1868 if `self < 0`, this is equal to round towards +/- infinity.
1872 This function will panic if `rhs` is 0.
1879 #![feature(euclidean_division)]
1880 let a: ", stringify!($SelfT), " = 7; // or any other integer type
1883 assert_eq!(a.div_euclid(b), 1); // 7 >= 4 * 1
1884 assert_eq!(a.div_euclid(-b), -1); // 7 >= -4 * -1
1885 assert_eq!((-a).div_euclid(b), -2); // -7 >= 4 * -2
1886 assert_eq!((-a).div_euclid(-b), 2); // -7 >= -4 * 2
1888 #[unstable(feature = "euclidean_division", issue = "49048")]
1889 #[must_use = "this returns the result of the operation, \
1890 without modifying the original"]
1892 #[rustc_inherit_overflow_checks]
1893 pub fn div_euclid(self, rhs: Self) -> Self {
1896 return if rhs > 0 { q - 1 } else { q + 1 }
1904 concat!("Calculates the least nonnegative remainder of `self (mod rhs)`.
1906 This is done as if by the Euclidean division algorithm -- given
1907 `r = self.rem_euclid(rhs)`, `self = rhs * self.div_euclid(rhs) + r`, and
1908 `0 <= r < abs(rhs)`.
1912 This function will panic if `rhs` is 0.
1919 #![feature(euclidean_division)]
1920 let a: ", stringify!($SelfT), " = 7; // or any other integer type
1923 assert_eq!(a.rem_euclid(b), 3);
1924 assert_eq!((-a).rem_euclid(b), 1);
1925 assert_eq!(a.rem_euclid(-b), 3);
1926 assert_eq!((-a).rem_euclid(-b), 1);
1928 #[unstable(feature = "euclidean_division", issue = "49048")]
1929 #[must_use = "this returns the result of the operation, \
1930 without modifying the original"]
1932 #[rustc_inherit_overflow_checks]
1933 pub fn rem_euclid(self, rhs: Self) -> Self {
1948 concat!("Computes the absolute value of `self`.
1952 The absolute value of `", stringify!($SelfT), "::min_value()` cannot be represented as an
1953 `", stringify!($SelfT), "`, and attempting to calculate it will cause an overflow. This means that
1954 code in debug mode will trigger a panic on this case and optimized code will return `",
1955 stringify!($SelfT), "::min_value()` without a panic.
1962 ", $Feature, "assert_eq!(10", stringify!($SelfT), ".abs(), 10);
1963 assert_eq!((-10", stringify!($SelfT), ").abs(), 10);",
1966 #[stable(feature = "rust1", since = "1.0.0")]
1968 #[rustc_inherit_overflow_checks]
1969 pub fn abs(self) -> Self {
1970 if self.is_negative() {
1971 // Note that the #[inline] above means that the overflow
1972 // semantics of this negation depend on the crate we're being
1982 concat!("Returns a number representing sign of `self`.
1984 - `0` if the number is zero
1985 - `1` if the number is positive
1986 - `-1` if the number is negative
1993 ", $Feature, "assert_eq!(10", stringify!($SelfT), ".signum(), 1);
1994 assert_eq!(0", stringify!($SelfT), ".signum(), 0);
1995 assert_eq!((-10", stringify!($SelfT), ").signum(), -1);",
1998 #[stable(feature = "rust1", since = "1.0.0")]
2000 pub fn signum(self) -> Self {
2010 concat!("Returns `true` if `self` is positive and `false` if the number is zero or
2018 ", $Feature, "assert!(10", stringify!($SelfT), ".is_positive());
2019 assert!(!(-10", stringify!($SelfT), ").is_positive());",
2022 #[stable(feature = "rust1", since = "1.0.0")]
2024 pub const fn is_positive(self) -> bool { self > 0 }
2028 concat!("Returns `true` if `self` is negative and `false` if the number is zero or
2036 ", $Feature, "assert!((-10", stringify!($SelfT), ").is_negative());
2037 assert!(!10", stringify!($SelfT), ".is_negative());",
2040 #[stable(feature = "rust1", since = "1.0.0")]
2042 pub const fn is_negative(self) -> bool { self < 0 }
2046 concat!("Return the memory representation of this integer as a byte array in
2047 big-endian (network) byte order.
2054 let bytes = ", $swap_op, stringify!($SelfT), ".to_be_bytes();
2055 assert_eq!(bytes, ", $be_bytes, ");
2057 #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2058 #[rustc_const_unstable(feature = "const_int_conversion")]
2060 pub const fn to_be_bytes(self) -> [u8; mem::size_of::<Self>()] {
2061 self.to_be().to_ne_bytes()
2066 concat!("Return the memory representation of this integer as a byte array in
2067 little-endian byte order.
2074 let bytes = ", $swap_op, stringify!($SelfT), ".to_le_bytes();
2075 assert_eq!(bytes, ", $le_bytes, ");
2077 #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2078 #[rustc_const_unstable(feature = "const_int_conversion")]
2080 pub const fn to_le_bytes(self) -> [u8; mem::size_of::<Self>()] {
2081 self.to_le().to_ne_bytes()
2087 Return the memory representation of this integer as a byte array in
2090 As the target platform's native endianness is used, portable code
2091 should use [`to_be_bytes`] or [`to_le_bytes`], as appropriate,
2096 [`to_be_bytes`]: #method.to_be_bytes
2097 [`to_le_bytes`]: #method.to_le_bytes
2102 let bytes = ", $swap_op, stringify!($SelfT), ".to_ne_bytes();
2103 assert_eq!(bytes, if cfg!(target_endian = \"big\") {
2109 #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2110 #[rustc_const_unstable(feature = "const_int_conversion")]
2112 pub const fn to_ne_bytes(self) -> [u8; mem::size_of::<Self>()] {
2113 unsafe { mem::transmute(self) }
2118 concat!("Create an integer value from its representation as a byte array in
2126 let value = ", stringify!($SelfT), "::from_be_bytes(", $be_bytes, ");
2127 assert_eq!(value, ", $swap_op, ");
2130 When starting from a slice rather than an array, fallible conversion APIs can be used:
2133 use std::convert::TryInto;
2135 fn read_be_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {
2136 let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());
2138 ", stringify!($SelfT), "::from_be_bytes(int_bytes.try_into().unwrap())
2141 #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2142 #[rustc_const_unstable(feature = "const_int_conversion")]
2144 pub const fn from_be_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
2145 Self::from_be(Self::from_ne_bytes(bytes))
2151 Create an integer value from its representation as a byte array in
2159 let value = ", stringify!($SelfT), "::from_le_bytes(", $le_bytes, ");
2160 assert_eq!(value, ", $swap_op, ");
2163 When starting from a slice rather than an array, fallible conversion APIs can be used:
2166 use std::convert::TryInto;
2168 fn read_le_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {
2169 let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());
2171 ", stringify!($SelfT), "::from_le_bytes(int_bytes.try_into().unwrap())
2174 #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2175 #[rustc_const_unstable(feature = "const_int_conversion")]
2177 pub const fn from_le_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
2178 Self::from_le(Self::from_ne_bytes(bytes))
2183 concat!("Create an integer value from its memory representation as a byte
2184 array in native endianness.
2186 As the target platform's native endianness is used, portable code
2187 likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as
2188 appropriate instead.
2190 [`from_be_bytes`]: #method.from_be_bytes
2191 [`from_le_bytes`]: #method.from_le_bytes
2198 let value = ", stringify!($SelfT), "::from_ne_bytes(if cfg!(target_endian = \"big\") {
2203 assert_eq!(value, ", $swap_op, ");
2206 When starting from a slice rather than an array, fallible conversion APIs can be used:
2209 use std::convert::TryInto;
2211 fn read_ne_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {
2212 let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());
2214 ", stringify!($SelfT), "::from_ne_bytes(int_bytes.try_into().unwrap())
2217 #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2218 #[rustc_const_unstable(feature = "const_int_conversion")]
2220 pub const fn from_ne_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
2221 unsafe { mem::transmute(bytes) }
2229 int_impl! { i8, i8, u8, 8, -128, 127, "", "", 2, "-0x7e", "0xa", "0x12", "0x12", "0x48",
2230 "[0x12]", "[0x12]", "", "" }
2235 int_impl! { i16, i16, u16, 16, -32768, 32767, "", "", 4, "-0x5ffd", "0x3a", "0x1234", "0x3412",
2236 "0x2c48", "[0x34, 0x12]", "[0x12, 0x34]", "", "" }
2241 int_impl! { i32, i32, u32, 32, -2147483648, 2147483647, "", "", 8, "0x10000b3", "0xb301",
2242 "0x12345678", "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]",
2243 "[0x12, 0x34, 0x56, 0x78]", "", "" }
2248 int_impl! { i64, i64, u64, 64, -9223372036854775808, 9223372036854775807, "", "", 12,
2249 "0xaa00000000006e1", "0x6e10aa", "0x1234567890123456", "0x5634129078563412",
2250 "0x6a2c48091e6a2c48", "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
2251 "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]", "", "" }
2256 int_impl! { i128, i128, u128, 128, -170141183460469231731687303715884105728,
2257 170141183460469231731687303715884105727, "", "", 16,
2258 "0x13f40000000000000000000000004f76", "0x4f7613f4", "0x12345678901234567890123456789012",
2259 "0x12907856341290785634129078563412", "0x48091e6a2c48091e6a2c48091e6a2c48",
2260 "[0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, \
2261 0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
2262 "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56, \
2263 0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12]", "", "" }
2266 #[cfg(target_pointer_width = "16")]
2269 int_impl! { isize, i16, u16, 16, -32768, 32767, "", "", 4, "-0x5ffd", "0x3a", "0x1234",
2270 "0x3412", "0x2c48", "[0x34, 0x12]", "[0x12, 0x34]",
2271 usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
2274 #[cfg(target_pointer_width = "32")]
2277 int_impl! { isize, i32, u32, 32, -2147483648, 2147483647, "", "", 8, "0x10000b3", "0xb301",
2278 "0x12345678", "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]",
2279 "[0x12, 0x34, 0x56, 0x78]",
2280 usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
2283 #[cfg(target_pointer_width = "64")]
2286 int_impl! { isize, i64, u64, 64, -9223372036854775808, 9223372036854775807, "", "",
2287 12, "0xaa00000000006e1", "0x6e10aa", "0x1234567890123456", "0x5634129078563412",
2288 "0x6a2c48091e6a2c48", "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
2289 "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
2290 usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
2293 // `Int` + `UnsignedInt` implemented for unsigned integers
2294 macro_rules! uint_impl {
2295 ($SelfT:ty, $ActualT:ty, $BITS:expr, $MaxV:expr, $Feature:expr, $EndFeature:expr,
2296 $rot:expr, $rot_op:expr, $rot_result:expr, $swap_op:expr, $swapped:expr,
2297 $reversed:expr, $le_bytes:expr, $be_bytes:expr,
2298 $to_xe_bytes_doc:expr, $from_xe_bytes_doc:expr) => {
2300 concat!("Returns the smallest value that can be represented by this integer type.
2307 ", $Feature, "assert_eq!(", stringify!($SelfT), "::min_value(), 0);", $EndFeature, "
2309 #[stable(feature = "rust1", since = "1.0.0")]
2312 pub const fn min_value() -> Self { 0 }
2316 concat!("Returns the largest value that can be represented by this integer type.
2323 ", $Feature, "assert_eq!(", stringify!($SelfT), "::max_value(), ",
2324 stringify!($MaxV), ");", $EndFeature, "
2326 #[stable(feature = "rust1", since = "1.0.0")]
2329 pub const fn max_value() -> Self { !0 }
2333 concat!("Converts a string slice in a given base to an integer.
2335 The string is expected to be an optional `+` sign
2337 Leading and trailing whitespace represent an error.
2338 Digits are a subset of these characters, depending on `radix`:
2346 This function panics if `radix` is not in the range from 2 to 36.
2353 ", $Feature, "assert_eq!(", stringify!($SelfT), "::from_str_radix(\"A\", 16), Ok(10));",
2356 #[stable(feature = "rust1", since = "1.0.0")]
2357 pub fn from_str_radix(src: &str, radix: u32) -> Result<Self, ParseIntError> {
2358 from_str_radix(src, radix)
2363 concat!("Returns the number of ones in the binary representation of `self`.
2370 ", $Feature, "let n = 0b01001100", stringify!($SelfT), ";
2372 assert_eq!(n.count_ones(), 3);", $EndFeature, "
2374 #[stable(feature = "rust1", since = "1.0.0")]
2376 pub const fn count_ones(self) -> u32 {
2377 intrinsics::ctpop(self as $ActualT) as u32
2382 concat!("Returns the number of zeros in the binary representation of `self`.
2389 ", $Feature, "assert_eq!(", stringify!($SelfT), "::max_value().count_zeros(), 0);", $EndFeature, "
2391 #[stable(feature = "rust1", since = "1.0.0")]
2393 pub const fn count_zeros(self) -> u32 {
2394 (!self).count_ones()
2399 concat!("Returns the number of leading zeros in the binary representation of `self`.
2406 ", $Feature, "let n = ", stringify!($SelfT), "::max_value() >> 2;
2408 assert_eq!(n.leading_zeros(), 2);", $EndFeature, "
2410 #[stable(feature = "rust1", since = "1.0.0")]
2412 pub const fn leading_zeros(self) -> u32 {
2413 intrinsics::ctlz(self as $ActualT) as u32
2418 concat!("Returns the number of trailing zeros in the binary representation
2426 ", $Feature, "let n = 0b0101000", stringify!($SelfT), ";
2428 assert_eq!(n.trailing_zeros(), 3);", $EndFeature, "
2430 #[stable(feature = "rust1", since = "1.0.0")]
2432 pub const fn trailing_zeros(self) -> u32 {
2433 intrinsics::cttz(self) as u32
2438 concat!("Shifts the bits to the left by a specified amount, `n`,
2439 wrapping the truncated bits to the end of the resulting integer.
2441 Please note this isn't the same operation as the `<<` shifting operator!
2448 let n = ", $rot_op, stringify!($SelfT), ";
2449 let m = ", $rot_result, ";
2451 assert_eq!(n.rotate_left(", $rot, "), m);
2453 #[stable(feature = "rust1", since = "1.0.0")]
2454 #[must_use = "this returns the result of the operation, \
2455 without modifying the original"]
2457 pub const fn rotate_left(self, n: u32) -> Self {
2458 intrinsics::rotate_left(self, n as $SelfT)
2463 concat!("Shifts the bits to the right by a specified amount, `n`,
2464 wrapping the truncated bits to the beginning of the resulting
2467 Please note this isn't the same operation as the `>>` shifting operator!
2474 let n = ", $rot_result, stringify!($SelfT), ";
2475 let m = ", $rot_op, ";
2477 assert_eq!(n.rotate_right(", $rot, "), m);
2479 #[stable(feature = "rust1", since = "1.0.0")]
2480 #[must_use = "this returns the result of the operation, \
2481 without modifying the original"]
2483 pub const fn rotate_right(self, n: u32) -> Self {
2484 intrinsics::rotate_right(self, n as $SelfT)
2490 Reverses the byte order of the integer.
2497 let n = ", $swap_op, stringify!($SelfT), ";
2498 let m = n.swap_bytes();
2500 assert_eq!(m, ", $swapped, ");
2502 #[stable(feature = "rust1", since = "1.0.0")]
2504 pub const fn swap_bytes(self) -> Self {
2505 intrinsics::bswap(self as $ActualT) as Self
2510 concat!("Reverses the bit pattern of the integer.
2517 #![feature(reverse_bits)]
2519 let n = ", $swap_op, stringify!($SelfT), ";
2520 let m = n.reverse_bits();
2522 assert_eq!(m, ", $reversed, ");
2524 #[unstable(feature = "reverse_bits", issue = "48763")]
2527 pub const fn reverse_bits(self) -> Self {
2528 intrinsics::bitreverse(self as $ActualT) as Self
2533 concat!("Converts an integer from big endian to the target's endianness.
2535 On big endian this is a no-op. On little endian the bytes are
2543 ", $Feature, "let n = 0x1A", stringify!($SelfT), ";
2545 if cfg!(target_endian = \"big\") {
2546 assert_eq!(", stringify!($SelfT), "::from_be(n), n)
2548 assert_eq!(", stringify!($SelfT), "::from_be(n), n.swap_bytes())
2551 #[stable(feature = "rust1", since = "1.0.0")]
2553 pub const fn from_be(x: Self) -> Self {
2554 #[cfg(target_endian = "big")]
2558 #[cfg(not(target_endian = "big"))]
2566 concat!("Converts an integer from little endian to the target's endianness.
2568 On little endian this is a no-op. On big endian the bytes are
2576 ", $Feature, "let n = 0x1A", stringify!($SelfT), ";
2578 if cfg!(target_endian = \"little\") {
2579 assert_eq!(", stringify!($SelfT), "::from_le(n), n)
2581 assert_eq!(", stringify!($SelfT), "::from_le(n), n.swap_bytes())
2584 #[stable(feature = "rust1", since = "1.0.0")]
2586 pub const fn from_le(x: Self) -> Self {
2587 #[cfg(target_endian = "little")]
2591 #[cfg(not(target_endian = "little"))]
2599 concat!("Converts `self` to big endian from the target's endianness.
2601 On big endian this is a no-op. On little endian the bytes are
2609 ", $Feature, "let n = 0x1A", stringify!($SelfT), ";
2611 if cfg!(target_endian = \"big\") {
2612 assert_eq!(n.to_be(), n)
2614 assert_eq!(n.to_be(), n.swap_bytes())
2617 #[stable(feature = "rust1", since = "1.0.0")]
2619 pub const fn to_be(self) -> Self { // or not to be?
2620 #[cfg(target_endian = "big")]
2624 #[cfg(not(target_endian = "big"))]
2632 concat!("Converts `self` to little endian from the target's endianness.
2634 On little endian this is a no-op. On big endian the bytes are
2642 ", $Feature, "let n = 0x1A", stringify!($SelfT), ";
2644 if cfg!(target_endian = \"little\") {
2645 assert_eq!(n.to_le(), n)
2647 assert_eq!(n.to_le(), n.swap_bytes())
2650 #[stable(feature = "rust1", since = "1.0.0")]
2652 pub const fn to_le(self) -> Self {
2653 #[cfg(target_endian = "little")]
2657 #[cfg(not(target_endian = "little"))]
2665 concat!("Checked integer addition. Computes `self + rhs`, returning `None`
2666 if overflow occurred.
2673 ", $Feature, "assert_eq!((", stringify!($SelfT), "::max_value() - 2).checked_add(1), ",
2674 "Some(", stringify!($SelfT), "::max_value() - 1));
2675 assert_eq!((", stringify!($SelfT), "::max_value() - 2).checked_add(3), None);", $EndFeature, "
2677 #[stable(feature = "rust1", since = "1.0.0")]
2678 #[must_use = "this returns the result of the operation, \
2679 without modifying the original"]
2681 pub fn checked_add(self, rhs: Self) -> Option<Self> {
2682 let (a, b) = self.overflowing_add(rhs);
2683 if b {None} else {Some(a)}
2688 concat!("Checked integer subtraction. Computes `self - rhs`, returning
2689 `None` if overflow occurred.
2696 ", $Feature, "assert_eq!(1", stringify!($SelfT), ".checked_sub(1), Some(0));
2697 assert_eq!(0", stringify!($SelfT), ".checked_sub(1), None);", $EndFeature, "
2699 #[stable(feature = "rust1", since = "1.0.0")]
2700 #[must_use = "this returns the result of the operation, \
2701 without modifying the original"]
2703 pub fn checked_sub(self, rhs: Self) -> Option<Self> {
2704 let (a, b) = self.overflowing_sub(rhs);
2705 if b {None} else {Some(a)}
2710 concat!("Checked integer multiplication. Computes `self * rhs`, returning
2711 `None` if overflow occurred.
2718 ", $Feature, "assert_eq!(5", stringify!($SelfT), ".checked_mul(1), Some(5));
2719 assert_eq!(", stringify!($SelfT), "::max_value().checked_mul(2), None);", $EndFeature, "
2721 #[stable(feature = "rust1", since = "1.0.0")]
2722 #[must_use = "this returns the result of the operation, \
2723 without modifying the original"]
2725 pub fn checked_mul(self, rhs: Self) -> Option<Self> {
2726 let (a, b) = self.overflowing_mul(rhs);
2727 if b {None} else {Some(a)}
2732 concat!("Checked integer division. Computes `self / rhs`, returning `None`
2740 ", $Feature, "assert_eq!(128", stringify!($SelfT), ".checked_div(2), Some(64));
2741 assert_eq!(1", stringify!($SelfT), ".checked_div(0), None);", $EndFeature, "
2743 #[stable(feature = "rust1", since = "1.0.0")]
2744 #[must_use = "this returns the result of the operation, \
2745 without modifying the original"]
2747 pub fn checked_div(self, rhs: Self) -> Option<Self> {
2750 rhs => Some(unsafe { intrinsics::unchecked_div(self, rhs) }),
2756 concat!("Checked Euclidean division. Computes `self.div_euclid(rhs)`, returning `None`
2764 #![feature(euclidean_division)]
2765 assert_eq!(128", stringify!($SelfT), ".checked_div_euclid(2), Some(64));
2766 assert_eq!(1", stringify!($SelfT), ".checked_div_euclid(0), None);
2768 #[unstable(feature = "euclidean_division", issue = "49048")]
2769 #[must_use = "this returns the result of the operation, \
2770 without modifying the original"]
2772 pub fn checked_div_euclid(self, rhs: Self) -> Option<Self> {
2776 Some(self.div_euclid(rhs))
2783 concat!("Checked integer remainder. Computes `self % rhs`, returning `None`
2791 ", $Feature, "assert_eq!(5", stringify!($SelfT), ".checked_rem(2), Some(1));
2792 assert_eq!(5", stringify!($SelfT), ".checked_rem(0), None);", $EndFeature, "
2794 #[stable(feature = "wrapping", since = "1.7.0")]
2795 #[must_use = "this returns the result of the operation, \
2796 without modifying the original"]
2798 pub fn checked_rem(self, rhs: Self) -> Option<Self> {
2802 Some(unsafe { intrinsics::unchecked_rem(self, rhs) })
2808 concat!("Checked Euclidean modulo. Computes `self.rem_euclid(rhs)`, returning `None`
2816 #![feature(euclidean_division)]
2817 assert_eq!(5", stringify!($SelfT), ".checked_rem_euclid(2), Some(1));
2818 assert_eq!(5", stringify!($SelfT), ".checked_rem_euclid(0), None);
2820 #[unstable(feature = "euclidean_division", issue = "49048")]
2821 #[must_use = "this returns the result of the operation, \
2822 without modifying the original"]
2824 pub fn checked_rem_euclid(self, rhs: Self) -> Option<Self> {
2828 Some(self.rem_euclid(rhs))
2834 concat!("Checked negation. Computes `-self`, returning `None` unless `self ==
2837 Note that negating any positive integer will overflow.
2844 ", $Feature, "assert_eq!(0", stringify!($SelfT), ".checked_neg(), Some(0));
2845 assert_eq!(1", stringify!($SelfT), ".checked_neg(), None);", $EndFeature, "
2847 #[stable(feature = "wrapping", since = "1.7.0")]
2849 pub fn checked_neg(self) -> Option<Self> {
2850 let (a, b) = self.overflowing_neg();
2851 if b {None} else {Some(a)}
2856 concat!("Checked shift left. Computes `self << rhs`, returning `None`
2857 if `rhs` is larger than or equal to the number of bits in `self`.
2864 ", $Feature, "assert_eq!(0x1", stringify!($SelfT), ".checked_shl(4), Some(0x10));
2865 assert_eq!(0x10", stringify!($SelfT), ".checked_shl(129), None);", $EndFeature, "
2867 #[stable(feature = "wrapping", since = "1.7.0")]
2868 #[must_use = "this returns the result of the operation, \
2869 without modifying the original"]
2871 pub fn checked_shl(self, rhs: u32) -> Option<Self> {
2872 let (a, b) = self.overflowing_shl(rhs);
2873 if b {None} else {Some(a)}
2878 concat!("Checked shift right. Computes `self >> rhs`, returning `None`
2879 if `rhs` is larger than or equal to the number of bits in `self`.
2886 ", $Feature, "assert_eq!(0x10", stringify!($SelfT), ".checked_shr(4), Some(0x1));
2887 assert_eq!(0x10", stringify!($SelfT), ".checked_shr(129), None);", $EndFeature, "
2889 #[stable(feature = "wrapping", since = "1.7.0")]
2890 #[must_use = "this returns the result of the operation, \
2891 without modifying the original"]
2893 pub fn checked_shr(self, rhs: u32) -> Option<Self> {
2894 let (a, b) = self.overflowing_shr(rhs);
2895 if b {None} else {Some(a)}
2900 concat!("Checked exponentiation. Computes `self.pow(exp)`, returning `None` if
2908 ", $Feature, "assert_eq!(2", stringify!($SelfT), ".checked_pow(5), Some(32));
2909 assert_eq!(", stringify!($SelfT), "::max_value().checked_pow(2), None);", $EndFeature, "
2911 #[stable(feature = "no_panic_pow", since = "1.34.0")]
2912 #[must_use = "this returns the result of the operation, \
2913 without modifying the original"]
2915 pub fn checked_pow(self, mut exp: u32) -> Option<Self> {
2916 let mut base = self;
2917 let mut acc: Self = 1;
2921 acc = acc.checked_mul(base)?;
2924 base = base.checked_mul(base)?;
2927 // Deal with the final bit of the exponent separately, since
2928 // squaring the base afterwards is not necessary and may cause a
2929 // needless overflow.
2931 acc = acc.checked_mul(base)?;
2939 concat!("Saturating integer addition. Computes `self + rhs`, saturating at
2940 the numeric bounds instead of overflowing.
2947 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".saturating_add(1), 101);
2948 assert_eq!(200u8.saturating_add(127), 255);", $EndFeature, "
2951 #[stable(feature = "rust1", since = "1.0.0")]
2952 #[must_use = "this returns the result of the operation, \
2953 without modifying the original"]
2954 #[rustc_const_unstable(feature = "const_saturating_int_methods")]
2956 pub const fn saturating_add(self, rhs: Self) -> Self {
2957 intrinsics::saturating_add(self, rhs)
2962 concat!("Saturating integer subtraction. Computes `self - rhs`, saturating
2963 at the numeric bounds instead of overflowing.
2970 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".saturating_sub(27), 73);
2971 assert_eq!(13", stringify!($SelfT), ".saturating_sub(127), 0);", $EndFeature, "
2973 #[stable(feature = "rust1", since = "1.0.0")]
2974 #[must_use = "this returns the result of the operation, \
2975 without modifying the original"]
2976 #[rustc_const_unstable(feature = "const_saturating_int_methods")]
2978 pub const fn saturating_sub(self, rhs: Self) -> Self {
2979 intrinsics::saturating_sub(self, rhs)
2984 concat!("Saturating integer multiplication. Computes `self * rhs`,
2985 saturating at the numeric bounds instead of overflowing.
2992 ", $Feature, "use std::", stringify!($SelfT), ";
2994 assert_eq!(2", stringify!($SelfT), ".saturating_mul(10), 20);
2995 assert_eq!((", stringify!($SelfT), "::MAX).saturating_mul(10), ", stringify!($SelfT),
2996 "::MAX);", $EndFeature, "
2998 #[stable(feature = "wrapping", since = "1.7.0")]
2999 #[must_use = "this returns the result of the operation, \
3000 without modifying the original"]
3002 pub fn saturating_mul(self, rhs: Self) -> Self {
3003 self.checked_mul(rhs).unwrap_or(Self::max_value())
3008 concat!("Saturating integer exponentiation. Computes `self.pow(exp)`,
3009 saturating at the numeric bounds instead of overflowing.
3016 ", $Feature, "use std::", stringify!($SelfT), ";
3018 assert_eq!(4", stringify!($SelfT), ".saturating_pow(3), 64);
3019 assert_eq!(", stringify!($SelfT), "::MAX.saturating_pow(2), ", stringify!($SelfT), "::MAX);",
3022 #[stable(feature = "no_panic_pow", since = "1.34.0")]
3023 #[must_use = "this returns the result of the operation, \
3024 without modifying the original"]
3026 pub fn saturating_pow(self, exp: u32) -> Self {
3027 match self.checked_pow(exp) {
3029 None => Self::max_value(),
3035 concat!("Wrapping (modular) addition. Computes `self + rhs`,
3036 wrapping around at the boundary of the type.
3043 ", $Feature, "assert_eq!(200", stringify!($SelfT), ".wrapping_add(55), 255);
3044 assert_eq!(200", stringify!($SelfT), ".wrapping_add(", stringify!($SelfT), "::max_value()), 199);",
3047 #[stable(feature = "rust1", since = "1.0.0")]
3048 #[must_use = "this returns the result of the operation, \
3049 without modifying the original"]
3051 pub const fn wrapping_add(self, rhs: Self) -> Self {
3052 intrinsics::overflowing_add(self, rhs)
3057 concat!("Wrapping (modular) subtraction. Computes `self - rhs`,
3058 wrapping around at the boundary of the type.
3065 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".wrapping_sub(100), 0);
3066 assert_eq!(100", stringify!($SelfT), ".wrapping_sub(", stringify!($SelfT), "::max_value()), 101);",
3069 #[stable(feature = "rust1", since = "1.0.0")]
3070 #[must_use = "this returns the result of the operation, \
3071 without modifying the original"]
3073 pub const fn wrapping_sub(self, rhs: Self) -> Self {
3074 intrinsics::overflowing_sub(self, rhs)
3078 /// Wrapping (modular) multiplication. Computes `self *
3079 /// rhs`, wrapping around at the boundary of the type.
3085 /// Please note that this example is shared between integer types.
3086 /// Which explains why `u8` is used here.
3089 /// assert_eq!(10u8.wrapping_mul(12), 120);
3090 /// assert_eq!(25u8.wrapping_mul(12), 44);
3092 #[stable(feature = "rust1", since = "1.0.0")]
3093 #[must_use = "this returns the result of the operation, \
3094 without modifying the original"]
3096 pub const fn wrapping_mul(self, rhs: Self) -> Self {
3097 intrinsics::overflowing_mul(self, rhs)
3101 concat!("Wrapping (modular) division. Computes `self / rhs`.
3102 Wrapped division on unsigned types is just normal division.
3103 There's no way wrapping could ever happen.
3104 This function exists, so that all operations
3105 are accounted for in the wrapping operations.
3112 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".wrapping_div(10), 10);", $EndFeature, "
3114 #[stable(feature = "num_wrapping", since = "1.2.0")]
3115 #[must_use = "this returns the result of the operation, \
3116 without modifying the original"]
3118 pub fn wrapping_div(self, rhs: Self) -> Self {
3124 concat!("Wrapping Euclidean division. Computes `self.div_euclid(rhs)`.
3125 Wrapped division on unsigned types is just normal division.
3126 There's no way wrapping could ever happen.
3127 This function exists, so that all operations
3128 are accounted for in the wrapping operations.
3129 Since, for the positive integers, all common
3130 definitions of division are equal, this
3131 is exactly equal to `self.wrapping_div(rhs)`.
3138 #![feature(euclidean_division)]
3139 assert_eq!(100", stringify!($SelfT), ".wrapping_div_euclid(10), 10);
3141 #[unstable(feature = "euclidean_division", issue = "49048")]
3142 #[must_use = "this returns the result of the operation, \
3143 without modifying the original"]
3145 pub fn wrapping_div_euclid(self, rhs: Self) -> Self {
3151 concat!("Wrapping (modular) remainder. Computes `self % rhs`.
3152 Wrapped remainder calculation on unsigned types is
3153 just the regular remainder calculation.
3154 There's no way wrapping could ever happen.
3155 This function exists, so that all operations
3156 are accounted for in the wrapping operations.
3163 ", $Feature, "assert_eq!(100", stringify!($SelfT), ".wrapping_rem(10), 0);", $EndFeature, "
3165 #[stable(feature = "num_wrapping", since = "1.2.0")]
3166 #[must_use = "this returns the result of the operation, \
3167 without modifying the original"]
3169 pub fn wrapping_rem(self, rhs: Self) -> Self {
3175 concat!("Wrapping Euclidean modulo. Computes `self.rem_euclid(rhs)`.
3176 Wrapped modulo calculation on unsigned types is
3177 just the regular remainder calculation.
3178 There's no way wrapping could ever happen.
3179 This function exists, so that all operations
3180 are accounted for in the wrapping operations.
3181 Since, for the positive integers, all common
3182 definitions of division are equal, this
3183 is exactly equal to `self.wrapping_rem(rhs)`.
3190 #![feature(euclidean_division)]
3191 assert_eq!(100", stringify!($SelfT), ".wrapping_rem_euclid(10), 0);
3193 #[unstable(feature = "euclidean_division", issue = "49048")]
3194 #[must_use = "this returns the result of the operation, \
3195 without modifying the original"]
3197 pub fn wrapping_rem_euclid(self, rhs: Self) -> Self {
3202 /// Wrapping (modular) negation. Computes `-self`,
3203 /// wrapping around at the boundary of the type.
3205 /// Since unsigned types do not have negative equivalents
3206 /// all applications of this function will wrap (except for `-0`).
3207 /// For values smaller than the corresponding signed type's maximum
3208 /// the result is the same as casting the corresponding signed value.
3209 /// Any larger values are equivalent to `MAX + 1 - (val - MAX - 1)` where
3210 /// `MAX` is the corresponding signed type's maximum.
3216 /// Please note that this example is shared between integer types.
3217 /// Which explains why `i8` is used here.
3220 /// assert_eq!(100i8.wrapping_neg(), -100);
3221 /// assert_eq!((-128i8).wrapping_neg(), -128);
3223 #[stable(feature = "num_wrapping", since = "1.2.0")]
3225 pub const fn wrapping_neg(self) -> Self {
3226 self.overflowing_neg().0
3230 concat!("Panic-free bitwise shift-left; yields `self << mask(rhs)`,
3231 where `mask` removes any high-order bits of `rhs` that
3232 would cause the shift to exceed the bitwidth of the type.
3234 Note that this is *not* the same as a rotate-left; the
3235 RHS of a wrapping shift-left is restricted to the range
3236 of the type, rather than the bits shifted out of the LHS
3237 being returned to the other end. The primitive integer
3238 types all implement a `rotate_left` function, which may
3239 be what you want instead.
3246 ", $Feature, "assert_eq!(1", stringify!($SelfT), ".wrapping_shl(7), 128);
3247 assert_eq!(1", stringify!($SelfT), ".wrapping_shl(128), 1);", $EndFeature, "
3249 #[stable(feature = "num_wrapping", since = "1.2.0")]
3250 #[must_use = "this returns the result of the operation, \
3251 without modifying the original"]
3253 pub const fn wrapping_shl(self, rhs: u32) -> Self {
3255 intrinsics::unchecked_shl(self, (rhs & ($BITS - 1)) as $SelfT)
3261 concat!("Panic-free bitwise shift-right; yields `self >> mask(rhs)`,
3262 where `mask` removes any high-order bits of `rhs` that
3263 would cause the shift to exceed the bitwidth of the type.
3265 Note that this is *not* the same as a rotate-right; the
3266 RHS of a wrapping shift-right is restricted to the range
3267 of the type, rather than the bits shifted out of the LHS
3268 being returned to the other end. The primitive integer
3269 types all implement a `rotate_right` function, which may
3270 be what you want instead.
3277 ", $Feature, "assert_eq!(128", stringify!($SelfT), ".wrapping_shr(7), 1);
3278 assert_eq!(128", stringify!($SelfT), ".wrapping_shr(128), 128);", $EndFeature, "
3280 #[stable(feature = "num_wrapping", since = "1.2.0")]
3281 #[must_use = "this returns the result of the operation, \
3282 without modifying the original"]
3284 pub const fn wrapping_shr(self, rhs: u32) -> Self {
3286 intrinsics::unchecked_shr(self, (rhs & ($BITS - 1)) as $SelfT)
3292 concat!("Wrapping (modular) exponentiation. Computes `self.pow(exp)`,
3293 wrapping around at the boundary of the type.
3300 ", $Feature, "assert_eq!(3", stringify!($SelfT), ".wrapping_pow(5), 243);
3301 assert_eq!(3u8.wrapping_pow(6), 217);", $EndFeature, "
3303 #[stable(feature = "no_panic_pow", since = "1.34.0")]
3304 #[must_use = "this returns the result of the operation, \
3305 without modifying the original"]
3307 pub fn wrapping_pow(self, mut exp: u32) -> Self {
3308 let mut base = self;
3309 let mut acc: Self = 1;
3313 acc = acc.wrapping_mul(base);
3316 base = base.wrapping_mul(base);
3319 // Deal with the final bit of the exponent separately, since
3320 // squaring the base afterwards is not necessary and may cause a
3321 // needless overflow.
3323 acc = acc.wrapping_mul(base);
3331 concat!("Calculates `self` + `rhs`
3333 Returns a tuple of the addition along with a boolean indicating
3334 whether an arithmetic overflow would occur. If an overflow would
3335 have occurred then the wrapped value is returned.
3342 ", $Feature, "use std::", stringify!($SelfT), ";
3344 assert_eq!(5", stringify!($SelfT), ".overflowing_add(2), (7, false));
3345 assert_eq!(", stringify!($SelfT), "::MAX.overflowing_add(1), (0, true));", $EndFeature, "
3347 #[stable(feature = "wrapping", since = "1.7.0")]
3348 #[must_use = "this returns the result of the operation, \
3349 without modifying the original"]
3351 pub const fn overflowing_add(self, rhs: Self) -> (Self, bool) {
3352 let (a, b) = intrinsics::add_with_overflow(self as $ActualT, rhs as $ActualT);
3358 concat!("Calculates `self` - `rhs`
3360 Returns a tuple of the subtraction along with a boolean indicating
3361 whether an arithmetic overflow would occur. If an overflow would
3362 have occurred then the wrapped value is returned.
3369 ", $Feature, "use std::", stringify!($SelfT), ";
3371 assert_eq!(5", stringify!($SelfT), ".overflowing_sub(2), (3, false));
3372 assert_eq!(0", stringify!($SelfT), ".overflowing_sub(1), (", stringify!($SelfT), "::MAX, true));",
3375 #[stable(feature = "wrapping", since = "1.7.0")]
3376 #[must_use = "this returns the result of the operation, \
3377 without modifying the original"]
3379 pub const fn overflowing_sub(self, rhs: Self) -> (Self, bool) {
3380 let (a, b) = intrinsics::sub_with_overflow(self as $ActualT, rhs as $ActualT);
3385 /// Calculates the multiplication of `self` and `rhs`.
3387 /// Returns a tuple of the multiplication along with a boolean
3388 /// indicating whether an arithmetic overflow would occur. If an
3389 /// overflow would have occurred then the wrapped value is returned.
3395 /// Please note that this example is shared between integer types.
3396 /// Which explains why `u32` is used here.
3399 /// assert_eq!(5u32.overflowing_mul(2), (10, false));
3400 /// assert_eq!(1_000_000_000u32.overflowing_mul(10), (1410065408, true));
3402 #[stable(feature = "wrapping", since = "1.7.0")]
3403 #[must_use = "this returns the result of the operation, \
3404 without modifying the original"]
3406 pub const fn overflowing_mul(self, rhs: Self) -> (Self, bool) {
3407 let (a, b) = intrinsics::mul_with_overflow(self as $ActualT, rhs as $ActualT);
3412 concat!("Calculates the divisor when `self` is divided by `rhs`.
3414 Returns a tuple of the divisor along with a boolean indicating
3415 whether an arithmetic overflow would occur. Note that for unsigned
3416 integers overflow never occurs, so the second value is always
3421 This function will panic if `rhs` is 0.
3428 ", $Feature, "assert_eq!(5", stringify!($SelfT), ".overflowing_div(2), (2, false));", $EndFeature, "
3431 #[stable(feature = "wrapping", since = "1.7.0")]
3432 #[must_use = "this returns the result of the operation, \
3433 without modifying the original"]
3434 pub fn overflowing_div(self, rhs: Self) -> (Self, bool) {
3440 concat!("Calculates the quotient of Euclidean division `self.div_euclid(rhs)`.
3442 Returns a tuple of the divisor along with a boolean indicating
3443 whether an arithmetic overflow would occur. Note that for unsigned
3444 integers overflow never occurs, so the second value is always
3446 Since, for the positive integers, all common
3447 definitions of division are equal, this
3448 is exactly equal to `self.overflowing_div(rhs)`.
3452 This function will panic if `rhs` is 0.
3459 #![feature(euclidean_division)]
3460 assert_eq!(5", stringify!($SelfT), ".overflowing_div_euclid(2), (2, false));
3463 #[unstable(feature = "euclidean_division", issue = "49048")]
3464 #[must_use = "this returns the result of the operation, \
3465 without modifying the original"]
3466 pub fn overflowing_div_euclid(self, rhs: Self) -> (Self, bool) {
3472 concat!("Calculates the remainder when `self` is divided by `rhs`.
3474 Returns a tuple of the remainder after dividing along with a boolean
3475 indicating whether an arithmetic overflow would occur. Note that for
3476 unsigned integers overflow never occurs, so the second value is
3481 This function will panic if `rhs` is 0.
3488 ", $Feature, "assert_eq!(5", stringify!($SelfT), ".overflowing_rem(2), (1, false));", $EndFeature, "
3491 #[stable(feature = "wrapping", since = "1.7.0")]
3492 #[must_use = "this returns the result of the operation, \
3493 without modifying the original"]
3494 pub fn overflowing_rem(self, rhs: Self) -> (Self, bool) {
3500 concat!("Calculates the remainder `self.rem_euclid(rhs)` as if by Euclidean division.
3502 Returns a tuple of the modulo after dividing along with a boolean
3503 indicating whether an arithmetic overflow would occur. Note that for
3504 unsigned integers overflow never occurs, so the second value is
3506 Since, for the positive integers, all common
3507 definitions of division are equal, this operation
3508 is exactly equal to `self.overflowing_rem(rhs)`.
3512 This function will panic if `rhs` is 0.
3519 #![feature(euclidean_division)]
3520 assert_eq!(5", stringify!($SelfT), ".overflowing_rem_euclid(2), (1, false));
3523 #[unstable(feature = "euclidean_division", issue = "49048")]
3524 #[must_use = "this returns the result of the operation, \
3525 without modifying the original"]
3526 pub fn overflowing_rem_euclid(self, rhs: Self) -> (Self, bool) {
3532 concat!("Negates self in an overflowing fashion.
3534 Returns `!self + 1` using wrapping operations to return the value
3535 that represents the negation of this unsigned value. Note that for
3536 positive unsigned values overflow always occurs, but negating 0 does
3544 ", $Feature, "assert_eq!(0", stringify!($SelfT), ".overflowing_neg(), (0, false));
3545 assert_eq!(2", stringify!($SelfT), ".overflowing_neg(), (-2i32 as ", stringify!($SelfT),
3546 ", true));", $EndFeature, "
3549 #[stable(feature = "wrapping", since = "1.7.0")]
3550 pub const fn overflowing_neg(self) -> (Self, bool) {
3551 ((!self).wrapping_add(1), self != 0)
3556 concat!("Shifts self left by `rhs` bits.
3558 Returns a tuple of the shifted version of self along with a boolean
3559 indicating whether the shift value was larger than or equal to the
3560 number of bits. If the shift value is too large, then value is
3561 masked (N-1) where N is the number of bits, and this value is then
3562 used to perform the shift.
3569 ", $Feature, "assert_eq!(0x1", stringify!($SelfT), ".overflowing_shl(4), (0x10, false));
3570 assert_eq!(0x1", stringify!($SelfT), ".overflowing_shl(132), (0x10, true));", $EndFeature, "
3572 #[stable(feature = "wrapping", since = "1.7.0")]
3573 #[must_use = "this returns the result of the operation, \
3574 without modifying the original"]
3576 pub const fn overflowing_shl(self, rhs: u32) -> (Self, bool) {
3577 (self.wrapping_shl(rhs), (rhs > ($BITS - 1)))
3582 concat!("Shifts self right by `rhs` bits.
3584 Returns a tuple of the shifted version of self along with a boolean
3585 indicating whether the shift value was larger than or equal to the
3586 number of bits. If the shift value is too large, then value is
3587 masked (N-1) where N is the number of bits, and this value is then
3588 used to perform the shift.
3595 ", $Feature, "assert_eq!(0x10", stringify!($SelfT), ".overflowing_shr(4), (0x1, false));
3596 assert_eq!(0x10", stringify!($SelfT), ".overflowing_shr(132), (0x1, true));", $EndFeature, "
3598 #[stable(feature = "wrapping", since = "1.7.0")]
3599 #[must_use = "this returns the result of the operation, \
3600 without modifying the original"]
3602 pub const fn overflowing_shr(self, rhs: u32) -> (Self, bool) {
3603 (self.wrapping_shr(rhs), (rhs > ($BITS - 1)))
3608 concat!("Raises self to the power of `exp`, using exponentiation by squaring.
3610 Returns a tuple of the exponentiation along with a bool indicating
3611 whether an overflow happened.
3618 ", $Feature, "assert_eq!(3", stringify!($SelfT), ".overflowing_pow(5), (243, false));
3619 assert_eq!(3u8.overflowing_pow(6), (217, true));", $EndFeature, "
3621 #[stable(feature = "no_panic_pow", since = "1.34.0")]
3622 #[must_use = "this returns the result of the operation, \
3623 without modifying the original"]
3625 pub fn overflowing_pow(self, mut exp: u32) -> (Self, bool) {
3626 let mut base = self;
3627 let mut acc: Self = 1;
3628 let mut overflown = false;
3629 // Scratch space for storing results of overflowing_mul.
3634 r = acc.overflowing_mul(base);
3639 r = base.overflowing_mul(base);
3644 // Deal with the final bit of the exponent separately, since
3645 // squaring the base afterwards is not necessary and may cause a
3646 // needless overflow.
3648 r = acc.overflowing_mul(base);
3658 concat!("Raises self to the power of `exp`, using exponentiation by squaring.
3665 ", $Feature, "assert_eq!(2", stringify!($SelfT), ".pow(5), 32);", $EndFeature, "
3667 #[stable(feature = "rust1", since = "1.0.0")]
3668 #[must_use = "this returns the result of the operation, \
3669 without modifying the original"]
3671 #[rustc_inherit_overflow_checks]
3672 pub fn pow(self, mut exp: u32) -> Self {
3673 let mut base = self;
3684 // Deal with the final bit of the exponent separately, since
3685 // squaring the base afterwards is not necessary and may cause a
3686 // needless overflow.
3696 concat!("Performs Euclidean division.
3698 Since, for the positive integers, all common
3699 definitions of division are equal, this
3700 is exactly equal to `self / rhs`.
3707 #![feature(euclidean_division)]
3708 assert_eq!(7", stringify!($SelfT), ".div_euclid(4), 1); // or any other integer type
3710 #[unstable(feature = "euclidean_division", issue = "49048")]
3711 #[must_use = "this returns the result of the operation, \
3712 without modifying the original"]
3714 #[rustc_inherit_overflow_checks]
3715 pub fn div_euclid(self, rhs: Self) -> Self {
3722 concat!("Calculates the least remainder of `self (mod rhs)`.
3724 Since, for the positive integers, all common
3725 definitions of division are equal, this
3726 is exactly equal to `self % rhs`.
3733 #![feature(euclidean_division)]
3734 assert_eq!(7", stringify!($SelfT), ".rem_euclid(4), 3); // or any other integer type
3736 #[unstable(feature = "euclidean_division", issue = "49048")]
3737 #[must_use = "this returns the result of the operation, \
3738 without modifying the original"]
3740 #[rustc_inherit_overflow_checks]
3741 pub fn rem_euclid(self, rhs: Self) -> Self {
3747 concat!("Returns `true` if and only if `self == 2^k` for some `k`.
3754 ", $Feature, "assert!(16", stringify!($SelfT), ".is_power_of_two());
3755 assert!(!10", stringify!($SelfT), ".is_power_of_two());", $EndFeature, "
3757 #[stable(feature = "rust1", since = "1.0.0")]
3759 pub fn is_power_of_two(self) -> bool {
3760 (self.wrapping_sub(1)) & self == 0 && !(self == 0)
3764 // Returns one less than next power of two.
3765 // (For 8u8 next power of two is 8u8 and for 6u8 it is 8u8)
3767 // 8u8.one_less_than_next_power_of_two() == 7
3768 // 6u8.one_less_than_next_power_of_two() == 7
3770 // This method cannot overflow, as in the `next_power_of_two`
3771 // overflow cases it instead ends up returning the maximum value
3772 // of the type, and can return 0 for 0.
3774 fn one_less_than_next_power_of_two(self) -> Self {
3775 if self <= 1 { return 0; }
3777 // Because `p > 0`, it cannot consist entirely of leading zeros.
3778 // That means the shift is always in-bounds, and some processors
3779 // (such as intel pre-haswell) have more efficient ctlz
3780 // intrinsics when the argument is non-zero.
3782 let z = unsafe { intrinsics::ctlz_nonzero(p) };
3783 <$SelfT>::max_value() >> z
3787 concat!("Returns the smallest power of two greater than or equal to `self`.
3789 When return value overflows (i.e., `self > (1 << (N-1))` for type
3790 `uN`), it panics in debug mode and return value is wrapped to 0 in
3791 release mode (the only situation in which method can return 0).
3798 ", $Feature, "assert_eq!(2", stringify!($SelfT), ".next_power_of_two(), 2);
3799 assert_eq!(3", stringify!($SelfT), ".next_power_of_two(), 4);", $EndFeature, "
3801 #[stable(feature = "rust1", since = "1.0.0")]
3803 pub fn next_power_of_two(self) -> Self {
3804 // Call the trait to get overflow checks
3805 ops::Add::add(self.one_less_than_next_power_of_two(), 1)
3810 concat!("Returns the smallest power of two greater than or equal to `n`. If
3811 the next power of two is greater than the type's maximum value,
3812 `None` is returned, otherwise the power of two is wrapped in `Some`.
3819 ", $Feature, "assert_eq!(2", stringify!($SelfT),
3820 ".checked_next_power_of_two(), Some(2));
3821 assert_eq!(3", stringify!($SelfT), ".checked_next_power_of_two(), Some(4));
3822 assert_eq!(", stringify!($SelfT), "::max_value().checked_next_power_of_two(), None);",
3826 #[stable(feature = "rust1", since = "1.0.0")]
3827 pub fn checked_next_power_of_two(self) -> Option<Self> {
3828 self.one_less_than_next_power_of_two().checked_add(1)
3833 concat!("Returns the smallest power of two greater than or equal to `n`. If
3834 the next power of two is greater than the type's maximum value,
3835 the return value is wrapped to `0`.
3842 #![feature(wrapping_next_power_of_two)]
3844 assert_eq!(2", stringify!($SelfT), ".wrapping_next_power_of_two(), 2);
3845 assert_eq!(3", stringify!($SelfT), ".wrapping_next_power_of_two(), 4);
3846 assert_eq!(", stringify!($SelfT), "::max_value().wrapping_next_power_of_two(), 0);",
3849 #[unstable(feature = "wrapping_next_power_of_two", issue = "32463",
3850 reason = "needs decision on wrapping behaviour")]
3851 pub fn wrapping_next_power_of_two(self) -> Self {
3852 self.one_less_than_next_power_of_two().wrapping_add(1)
3857 concat!("Return the memory representation of this integer as a byte array in
3858 big-endian (network) byte order.
3865 let bytes = ", $swap_op, stringify!($SelfT), ".to_be_bytes();
3866 assert_eq!(bytes, ", $be_bytes, ");
3868 #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
3869 #[rustc_const_unstable(feature = "const_int_conversion")]
3871 pub const fn to_be_bytes(self) -> [u8; mem::size_of::<Self>()] {
3872 self.to_be().to_ne_bytes()
3877 concat!("Return the memory representation of this integer as a byte array in
3878 little-endian byte order.
3885 let bytes = ", $swap_op, stringify!($SelfT), ".to_le_bytes();
3886 assert_eq!(bytes, ", $le_bytes, ");
3888 #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
3889 #[rustc_const_unstable(feature = "const_int_conversion")]
3891 pub const fn to_le_bytes(self) -> [u8; mem::size_of::<Self>()] {
3892 self.to_le().to_ne_bytes()
3898 Return the memory representation of this integer as a byte array in
3901 As the target platform's native endianness is used, portable code
3902 should use [`to_be_bytes`] or [`to_le_bytes`], as appropriate,
3907 [`to_be_bytes`]: #method.to_be_bytes
3908 [`to_le_bytes`]: #method.to_le_bytes
3913 let bytes = ", $swap_op, stringify!($SelfT), ".to_ne_bytes();
3914 assert_eq!(bytes, if cfg!(target_endian = \"big\") {
3920 #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
3921 #[rustc_const_unstable(feature = "const_int_conversion")]
3923 pub const fn to_ne_bytes(self) -> [u8; mem::size_of::<Self>()] {
3924 unsafe { mem::transmute(self) }
3929 concat!("Create an integer value from its representation as a byte array in
3937 let value = ", stringify!($SelfT), "::from_be_bytes(", $be_bytes, ");
3938 assert_eq!(value, ", $swap_op, ");
3941 When starting from a slice rather than an array, fallible conversion APIs can be used:
3944 use std::convert::TryInto;
3946 fn read_be_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {
3947 let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());
3949 ", stringify!($SelfT), "::from_be_bytes(int_bytes.try_into().unwrap())
3952 #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
3953 #[rustc_const_unstable(feature = "const_int_conversion")]
3955 pub const fn from_be_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
3956 Self::from_be(Self::from_ne_bytes(bytes))
3962 Create an integer value from its representation as a byte array in
3970 let value = ", stringify!($SelfT), "::from_le_bytes(", $le_bytes, ");
3971 assert_eq!(value, ", $swap_op, ");
3974 When starting from a slice rather than an array, fallible conversion APIs can be used:
3977 use std::convert::TryInto;
3979 fn read_le_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {
3980 let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());
3982 ", stringify!($SelfT), "::from_le_bytes(int_bytes.try_into().unwrap())
3985 #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
3986 #[rustc_const_unstable(feature = "const_int_conversion")]
3988 pub const fn from_le_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
3989 Self::from_le(Self::from_ne_bytes(bytes))
3994 concat!("Create an integer value from its memory representation as a byte
3995 array in native endianness.
3997 As the target platform's native endianness is used, portable code
3998 likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as
3999 appropriate instead.
4001 [`from_be_bytes`]: #method.from_be_bytes
4002 [`from_le_bytes`]: #method.from_le_bytes
4009 let value = ", stringify!($SelfT), "::from_ne_bytes(if cfg!(target_endian = \"big\") {
4014 assert_eq!(value, ", $swap_op, ");
4017 When starting from a slice rather than an array, fallible conversion APIs can be used:
4020 use std::convert::TryInto;
4022 fn read_ne_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {
4023 let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());
4025 ", stringify!($SelfT), "::from_ne_bytes(int_bytes.try_into().unwrap())
4028 #[stable(feature = "int_to_from_bytes", since = "1.32.0")]
4029 #[rustc_const_unstable(feature = "const_int_conversion")]
4031 pub const fn from_ne_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
4032 unsafe { mem::transmute(bytes) }
4040 uint_impl! { u8, u8, 8, 255, "", "", 2, "0x82", "0xa", "0x12", "0x12", "0x48", "[0x12]",
4044 /// Checks if the value is within the ASCII range.
4049 /// let ascii = 97u8;
4050 /// let non_ascii = 150u8;
4052 /// assert!(ascii.is_ascii());
4053 /// assert!(!non_ascii.is_ascii());
4055 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4057 pub fn is_ascii(&self) -> bool {
4061 /// Makes a copy of the value in its ASCII upper case equivalent.
4063 /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
4064 /// but non-ASCII letters are unchanged.
4066 /// To uppercase the value in-place, use [`make_ascii_uppercase`].
4071 /// let lowercase_a = 97u8;
4073 /// assert_eq!(65, lowercase_a.to_ascii_uppercase());
4076 /// [`make_ascii_uppercase`]: #method.make_ascii_uppercase
4077 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4079 pub fn to_ascii_uppercase(&self) -> u8 {
4080 // Unset the fith bit if this is a lowercase letter
4081 *self & !((self.is_ascii_lowercase() as u8) << 5)
4084 /// Makes a copy of the value in its ASCII lower case equivalent.
4086 /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
4087 /// but non-ASCII letters are unchanged.
4089 /// To lowercase the value in-place, use [`make_ascii_lowercase`].
4094 /// let uppercase_a = 65u8;
4096 /// assert_eq!(97, uppercase_a.to_ascii_lowercase());
4099 /// [`make_ascii_lowercase`]: #method.make_ascii_lowercase
4100 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4102 pub fn to_ascii_lowercase(&self) -> u8 {
4103 // Set the fith bit if this is an uppercase letter
4104 *self | ((self.is_ascii_uppercase() as u8) << 5)
4107 /// Checks that two values are an ASCII case-insensitive match.
4109 /// This is equivalent to `to_ascii_lowercase(a) == to_ascii_lowercase(b)`.
4114 /// let lowercase_a = 97u8;
4115 /// let uppercase_a = 65u8;
4117 /// assert!(lowercase_a.eq_ignore_ascii_case(&uppercase_a));
4119 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4121 pub fn eq_ignore_ascii_case(&self, other: &u8) -> bool {
4122 self.to_ascii_lowercase() == other.to_ascii_lowercase()
4125 /// Converts this value to its ASCII upper case equivalent in-place.
4127 /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
4128 /// but non-ASCII letters are unchanged.
4130 /// To return a new uppercased value without modifying the existing one, use
4131 /// [`to_ascii_uppercase`].
4136 /// let mut byte = b'a';
4138 /// byte.make_ascii_uppercase();
4140 /// assert_eq!(b'A', byte);
4143 /// [`to_ascii_uppercase`]: #method.to_ascii_uppercase
4144 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4146 pub fn make_ascii_uppercase(&mut self) {
4147 *self = self.to_ascii_uppercase();
4150 /// Converts this value to its ASCII lower case equivalent in-place.
4152 /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
4153 /// but non-ASCII letters are unchanged.
4155 /// To return a new lowercased value without modifying the existing one, use
4156 /// [`to_ascii_lowercase`].
4161 /// let mut byte = b'A';
4163 /// byte.make_ascii_lowercase();
4165 /// assert_eq!(b'a', byte);
4168 /// [`to_ascii_lowercase`]: #method.to_ascii_lowercase
4169 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4171 pub fn make_ascii_lowercase(&mut self) {
4172 *self = self.to_ascii_lowercase();
4175 /// Checks if the value is an ASCII alphabetic character:
4177 /// - U+0041 'A' ... U+005A 'Z', or
4178 /// - U+0061 'a' ... U+007A 'z'.
4183 /// let uppercase_a = b'A';
4184 /// let uppercase_g = b'G';
4187 /// let zero = b'0';
4188 /// let percent = b'%';
4189 /// let space = b' ';
4191 /// let esc = 0x1b_u8;
4193 /// assert!(uppercase_a.is_ascii_alphabetic());
4194 /// assert!(uppercase_g.is_ascii_alphabetic());
4195 /// assert!(a.is_ascii_alphabetic());
4196 /// assert!(g.is_ascii_alphabetic());
4197 /// assert!(!zero.is_ascii_alphabetic());
4198 /// assert!(!percent.is_ascii_alphabetic());
4199 /// assert!(!space.is_ascii_alphabetic());
4200 /// assert!(!lf.is_ascii_alphabetic());
4201 /// assert!(!esc.is_ascii_alphabetic());
4203 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4205 pub fn is_ascii_alphabetic(&self) -> bool {
4207 b'A'..=b'Z' | b'a'..=b'z' => true,
4212 /// Checks if the value is an ASCII uppercase character:
4213 /// U+0041 'A' ... U+005A 'Z'.
4218 /// let uppercase_a = b'A';
4219 /// let uppercase_g = b'G';
4222 /// let zero = b'0';
4223 /// let percent = b'%';
4224 /// let space = b' ';
4226 /// let esc = 0x1b_u8;
4228 /// assert!(uppercase_a.is_ascii_uppercase());
4229 /// assert!(uppercase_g.is_ascii_uppercase());
4230 /// assert!(!a.is_ascii_uppercase());
4231 /// assert!(!g.is_ascii_uppercase());
4232 /// assert!(!zero.is_ascii_uppercase());
4233 /// assert!(!percent.is_ascii_uppercase());
4234 /// assert!(!space.is_ascii_uppercase());
4235 /// assert!(!lf.is_ascii_uppercase());
4236 /// assert!(!esc.is_ascii_uppercase());
4238 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4240 pub fn is_ascii_uppercase(&self) -> bool {
4242 b'A'..=b'Z' => true,
4247 /// Checks if the value is an ASCII lowercase character:
4248 /// U+0061 'a' ... U+007A 'z'.
4253 /// let uppercase_a = b'A';
4254 /// let uppercase_g = b'G';
4257 /// let zero = b'0';
4258 /// let percent = b'%';
4259 /// let space = b' ';
4261 /// let esc = 0x1b_u8;
4263 /// assert!(!uppercase_a.is_ascii_lowercase());
4264 /// assert!(!uppercase_g.is_ascii_lowercase());
4265 /// assert!(a.is_ascii_lowercase());
4266 /// assert!(g.is_ascii_lowercase());
4267 /// assert!(!zero.is_ascii_lowercase());
4268 /// assert!(!percent.is_ascii_lowercase());
4269 /// assert!(!space.is_ascii_lowercase());
4270 /// assert!(!lf.is_ascii_lowercase());
4271 /// assert!(!esc.is_ascii_lowercase());
4273 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4275 pub fn is_ascii_lowercase(&self) -> bool {
4277 b'a'..=b'z' => true,
4282 /// Checks if the value is an ASCII alphanumeric character:
4284 /// - U+0041 'A' ... U+005A 'Z', or
4285 /// - U+0061 'a' ... U+007A 'z', or
4286 /// - U+0030 '0' ... U+0039 '9'.
4291 /// let uppercase_a = b'A';
4292 /// let uppercase_g = b'G';
4295 /// let zero = b'0';
4296 /// let percent = b'%';
4297 /// let space = b' ';
4299 /// let esc = 0x1b_u8;
4301 /// assert!(uppercase_a.is_ascii_alphanumeric());
4302 /// assert!(uppercase_g.is_ascii_alphanumeric());
4303 /// assert!(a.is_ascii_alphanumeric());
4304 /// assert!(g.is_ascii_alphanumeric());
4305 /// assert!(zero.is_ascii_alphanumeric());
4306 /// assert!(!percent.is_ascii_alphanumeric());
4307 /// assert!(!space.is_ascii_alphanumeric());
4308 /// assert!(!lf.is_ascii_alphanumeric());
4309 /// assert!(!esc.is_ascii_alphanumeric());
4311 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4313 pub fn is_ascii_alphanumeric(&self) -> bool {
4315 b'0'..=b'9' | b'A'..=b'Z' | b'a'..=b'z' => true,
4320 /// Checks if the value is an ASCII decimal digit:
4321 /// U+0030 '0' ... U+0039 '9'.
4326 /// let uppercase_a = b'A';
4327 /// let uppercase_g = b'G';
4330 /// let zero = b'0';
4331 /// let percent = b'%';
4332 /// let space = b' ';
4334 /// let esc = 0x1b_u8;
4336 /// assert!(!uppercase_a.is_ascii_digit());
4337 /// assert!(!uppercase_g.is_ascii_digit());
4338 /// assert!(!a.is_ascii_digit());
4339 /// assert!(!g.is_ascii_digit());
4340 /// assert!(zero.is_ascii_digit());
4341 /// assert!(!percent.is_ascii_digit());
4342 /// assert!(!space.is_ascii_digit());
4343 /// assert!(!lf.is_ascii_digit());
4344 /// assert!(!esc.is_ascii_digit());
4346 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4348 pub fn is_ascii_digit(&self) -> bool {
4350 b'0'..=b'9' => true,
4355 /// Checks if the value is an ASCII hexadecimal digit:
4357 /// - U+0030 '0' ... U+0039 '9', or
4358 /// - U+0041 'A' ... U+0046 'F', or
4359 /// - U+0061 'a' ... U+0066 'f'.
4364 /// let uppercase_a = b'A';
4365 /// let uppercase_g = b'G';
4368 /// let zero = b'0';
4369 /// let percent = b'%';
4370 /// let space = b' ';
4372 /// let esc = 0x1b_u8;
4374 /// assert!(uppercase_a.is_ascii_hexdigit());
4375 /// assert!(!uppercase_g.is_ascii_hexdigit());
4376 /// assert!(a.is_ascii_hexdigit());
4377 /// assert!(!g.is_ascii_hexdigit());
4378 /// assert!(zero.is_ascii_hexdigit());
4379 /// assert!(!percent.is_ascii_hexdigit());
4380 /// assert!(!space.is_ascii_hexdigit());
4381 /// assert!(!lf.is_ascii_hexdigit());
4382 /// assert!(!esc.is_ascii_hexdigit());
4384 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4386 pub fn is_ascii_hexdigit(&self) -> bool {
4388 b'0'..=b'9' | b'A'..=b'F' | b'a'..=b'f' => true,
4393 /// Checks if the value is an ASCII punctuation character:
4395 /// - U+0021 ... U+002F `! " # $ % & ' ( ) * + , - . /`, or
4396 /// - U+003A ... U+0040 `: ; < = > ? @`, or
4397 /// - U+005B ... U+0060 ``[ \ ] ^ _ ` ``, or
4398 /// - U+007B ... U+007E `{ | } ~`
4403 /// let uppercase_a = b'A';
4404 /// let uppercase_g = b'G';
4407 /// let zero = b'0';
4408 /// let percent = b'%';
4409 /// let space = b' ';
4411 /// let esc = 0x1b_u8;
4413 /// assert!(!uppercase_a.is_ascii_punctuation());
4414 /// assert!(!uppercase_g.is_ascii_punctuation());
4415 /// assert!(!a.is_ascii_punctuation());
4416 /// assert!(!g.is_ascii_punctuation());
4417 /// assert!(!zero.is_ascii_punctuation());
4418 /// assert!(percent.is_ascii_punctuation());
4419 /// assert!(!space.is_ascii_punctuation());
4420 /// assert!(!lf.is_ascii_punctuation());
4421 /// assert!(!esc.is_ascii_punctuation());
4423 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4425 pub fn is_ascii_punctuation(&self) -> bool {
4427 b'!'..=b'/' | b':'..=b'@' | b'['..=b'`' | b'{'..=b'~' => true,
4432 /// Checks if the value is an ASCII graphic character:
4433 /// U+0021 '!' ... U+007E '~'.
4438 /// let uppercase_a = b'A';
4439 /// let uppercase_g = b'G';
4442 /// let zero = b'0';
4443 /// let percent = b'%';
4444 /// let space = b' ';
4446 /// let esc = 0x1b_u8;
4448 /// assert!(uppercase_a.is_ascii_graphic());
4449 /// assert!(uppercase_g.is_ascii_graphic());
4450 /// assert!(a.is_ascii_graphic());
4451 /// assert!(g.is_ascii_graphic());
4452 /// assert!(zero.is_ascii_graphic());
4453 /// assert!(percent.is_ascii_graphic());
4454 /// assert!(!space.is_ascii_graphic());
4455 /// assert!(!lf.is_ascii_graphic());
4456 /// assert!(!esc.is_ascii_graphic());
4458 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4460 pub fn is_ascii_graphic(&self) -> bool {
4462 b'!'..=b'~' => true,
4467 /// Checks if the value is an ASCII whitespace character:
4468 /// U+0020 SPACE, U+0009 HORIZONTAL TAB, U+000A LINE FEED,
4469 /// U+000C FORM FEED, or U+000D CARRIAGE RETURN.
4471 /// Rust uses the WhatWG Infra Standard's [definition of ASCII
4472 /// whitespace][infra-aw]. There are several other definitions in
4473 /// wide use. For instance, [the POSIX locale][pct] includes
4474 /// U+000B VERTICAL TAB as well as all the above characters,
4475 /// but—from the very same specification—[the default rule for
4476 /// "field splitting" in the Bourne shell][bfs] considers *only*
4477 /// SPACE, HORIZONTAL TAB, and LINE FEED as whitespace.
4479 /// If you are writing a program that will process an existing
4480 /// file format, check what that format's definition of whitespace is
4481 /// before using this function.
4483 /// [infra-aw]: https://infra.spec.whatwg.org/#ascii-whitespace
4484 /// [pct]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html#tag_07_03_01
4485 /// [bfs]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_05
4490 /// let uppercase_a = b'A';
4491 /// let uppercase_g = b'G';
4494 /// let zero = b'0';
4495 /// let percent = b'%';
4496 /// let space = b' ';
4498 /// let esc = 0x1b_u8;
4500 /// assert!(!uppercase_a.is_ascii_whitespace());
4501 /// assert!(!uppercase_g.is_ascii_whitespace());
4502 /// assert!(!a.is_ascii_whitespace());
4503 /// assert!(!g.is_ascii_whitespace());
4504 /// assert!(!zero.is_ascii_whitespace());
4505 /// assert!(!percent.is_ascii_whitespace());
4506 /// assert!(space.is_ascii_whitespace());
4507 /// assert!(lf.is_ascii_whitespace());
4508 /// assert!(!esc.is_ascii_whitespace());
4510 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4512 pub fn is_ascii_whitespace(&self) -> bool {
4514 b'\t' | b'\n' | b'\x0C' | b'\r' | b' ' => true,
4519 /// Checks if the value is an ASCII control character:
4520 /// U+0000 NUL ... U+001F UNIT SEPARATOR, or U+007F DELETE.
4521 /// Note that most ASCII whitespace characters are control
4522 /// characters, but SPACE is not.
4527 /// let uppercase_a = b'A';
4528 /// let uppercase_g = b'G';
4531 /// let zero = b'0';
4532 /// let percent = b'%';
4533 /// let space = b' ';
4535 /// let esc = 0x1b_u8;
4537 /// assert!(!uppercase_a.is_ascii_control());
4538 /// assert!(!uppercase_g.is_ascii_control());
4539 /// assert!(!a.is_ascii_control());
4540 /// assert!(!g.is_ascii_control());
4541 /// assert!(!zero.is_ascii_control());
4542 /// assert!(!percent.is_ascii_control());
4543 /// assert!(!space.is_ascii_control());
4544 /// assert!(lf.is_ascii_control());
4545 /// assert!(esc.is_ascii_control());
4547 #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")]
4549 pub fn is_ascii_control(&self) -> bool {
4551 b'\0'..=b'\x1F' | b'\x7F' => true,
4559 uint_impl! { u16, u16, 16, 65535, "", "", 4, "0xa003", "0x3a", "0x1234", "0x3412", "0x2c48",
4560 "[0x34, 0x12]", "[0x12, 0x34]", "", "" }
4565 uint_impl! { u32, u32, 32, 4294967295, "", "", 8, "0x10000b3", "0xb301", "0x12345678",
4566 "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]", "[0x12, 0x34, 0x56, 0x78]", "", "" }
4571 uint_impl! { u64, u64, 64, 18446744073709551615, "", "", 12, "0xaa00000000006e1", "0x6e10aa",
4572 "0x1234567890123456", "0x5634129078563412", "0x6a2c48091e6a2c48",
4573 "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
4574 "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
4580 uint_impl! { u128, u128, 128, 340282366920938463463374607431768211455, "", "", 16,
4581 "0x13f40000000000000000000000004f76", "0x4f7613f4", "0x12345678901234567890123456789012",
4582 "0x12907856341290785634129078563412", "0x48091e6a2c48091e6a2c48091e6a2c48",
4583 "[0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, \
4584 0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
4585 "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56, \
4586 0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12]",
4590 #[cfg(target_pointer_width = "16")]
4593 uint_impl! { usize, u16, 16, 65535, "", "", 4, "0xa003", "0x3a", "0x1234", "0x3412", "0x2c48",
4594 "[0x34, 0x12]", "[0x12, 0x34]",
4595 usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
4597 #[cfg(target_pointer_width = "32")]
4600 uint_impl! { usize, u32, 32, 4294967295, "", "", 8, "0x10000b3", "0xb301", "0x12345678",
4601 "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]", "[0x12, 0x34, 0x56, 0x78]",
4602 usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
4605 #[cfg(target_pointer_width = "64")]
4608 uint_impl! { usize, u64, 64, 18446744073709551615, "", "", 12, "0xaa00000000006e1", "0x6e10aa",
4609 "0x1234567890123456", "0x5634129078563412", "0x6a2c48091e6a2c48",
4610 "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
4611 "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
4612 usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
4615 /// A classification of floating point numbers.
4617 /// This `enum` is used as the return type for [`f32::classify`] and [`f64::classify`]. See
4618 /// their documentation for more.
4620 /// [`f32::classify`]: ../../std/primitive.f32.html#method.classify
4621 /// [`f64::classify`]: ../../std/primitive.f64.html#method.classify
4626 /// use std::num::FpCategory;
4629 /// let num = 12.4_f32;
4630 /// let inf = f32::INFINITY;
4631 /// let zero = 0f32;
4632 /// let sub: f32 = 1.1754942e-38;
4633 /// let nan = f32::NAN;
4635 /// assert_eq!(num.classify(), FpCategory::Normal);
4636 /// assert_eq!(inf.classify(), FpCategory::Infinite);
4637 /// assert_eq!(zero.classify(), FpCategory::Zero);
4638 /// assert_eq!(nan.classify(), FpCategory::Nan);
4639 /// assert_eq!(sub.classify(), FpCategory::Subnormal);
4641 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
4642 #[stable(feature = "rust1", since = "1.0.0")]
4643 pub enum FpCategory {
4644 /// "Not a Number", often obtained by dividing by zero.
4645 #[stable(feature = "rust1", since = "1.0.0")]
4648 /// Positive or negative infinity.
4649 #[stable(feature = "rust1", since = "1.0.0")]
4652 /// Positive or negative zero.
4653 #[stable(feature = "rust1", since = "1.0.0")]
4656 /// De-normalized floating point representation (less precise than `Normal`).
4657 #[stable(feature = "rust1", since = "1.0.0")]
4660 /// A regular floating point number.
4661 #[stable(feature = "rust1", since = "1.0.0")]
4665 macro_rules! from_str_radix_int_impl {
4667 #[stable(feature = "rust1", since = "1.0.0")]
4668 impl FromStr for $t {
4669 type Err = ParseIntError;
4670 fn from_str(src: &str) -> Result<Self, ParseIntError> {
4671 from_str_radix(src, 10)
4676 from_str_radix_int_impl! { isize i8 i16 i32 i64 i128 usize u8 u16 u32 u64 u128 }
4678 /// The error type returned when a checked integral type conversion fails.
4679 #[stable(feature = "try_from", since = "1.34.0")]
4680 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
4681 pub struct TryFromIntError(());
4683 impl TryFromIntError {
4684 #[unstable(feature = "int_error_internals",
4685 reason = "available through Error trait and this method should \
4686 not be exposed publicly",
4689 pub fn __description(&self) -> &str {
4690 "out of range integral type conversion attempted"
4694 #[stable(feature = "try_from", since = "1.34.0")]
4695 impl fmt::Display for TryFromIntError {
4696 fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
4697 self.__description().fmt(fmt)
4701 #[stable(feature = "try_from", since = "1.34.0")]
4702 impl From<Infallible> for TryFromIntError {
4703 fn from(x: Infallible) -> TryFromIntError {
4708 #[unstable(feature = "never_type", issue = "35121")]
4709 impl From<!> for TryFromIntError {
4710 fn from(never: !) -> TryFromIntError {
4711 // Match rather than coerce to make sure that code like
4712 // `From<Infallible> for TryFromIntError` above will keep working
4713 // when `Infallible` becomes an alias to `!`.
4718 // no possible bounds violation
4719 macro_rules! try_from_unbounded {
4720 ($source:ty, $($target:ty),*) => {$(
4721 #[stable(feature = "try_from", since = "1.34.0")]
4722 impl TryFrom<$source> for $target {
4723 type Error = TryFromIntError;
4725 /// Try to create the target number type from a source
4726 /// number type. This returns an error if the source value
4727 /// is outside of the range of the target type.
4729 fn try_from(value: $source) -> Result<Self, Self::Error> {
4730 Ok(value as $target)
4736 // only negative bounds
4737 macro_rules! try_from_lower_bounded {
4738 ($source:ty, $($target:ty),*) => {$(
4739 #[stable(feature = "try_from", since = "1.34.0")]
4740 impl TryFrom<$source> for $target {
4741 type Error = TryFromIntError;
4743 /// Try to create the target number type from a source
4744 /// number type. This returns an error if the source value
4745 /// is outside of the range of the target type.
4747 fn try_from(u: $source) -> Result<$target, TryFromIntError> {
4751 Err(TryFromIntError(()))
4758 // unsigned to signed (only positive bound)
4759 macro_rules! try_from_upper_bounded {
4760 ($source:ty, $($target:ty),*) => {$(
4761 #[stable(feature = "try_from", since = "1.34.0")]
4762 impl TryFrom<$source> for $target {
4763 type Error = TryFromIntError;
4765 /// Try to create the target number type from a source
4766 /// number type. This returns an error if the source value
4767 /// is outside of the range of the target type.
4769 fn try_from(u: $source) -> Result<$target, TryFromIntError> {
4770 if u > (<$target>::max_value() as $source) {
4771 Err(TryFromIntError(()))
4781 macro_rules! try_from_both_bounded {
4782 ($source:ty, $($target:ty),*) => {$(
4783 #[stable(feature = "try_from", since = "1.34.0")]
4784 impl TryFrom<$source> for $target {
4785 type Error = TryFromIntError;
4787 /// Try to create the target number type from a source
4788 /// number type. This returns an error if the source value
4789 /// is outside of the range of the target type.
4791 fn try_from(u: $source) -> Result<$target, TryFromIntError> {
4792 let min = <$target>::min_value() as $source;
4793 let max = <$target>::max_value() as $source;
4794 if u < min || u > max {
4795 Err(TryFromIntError(()))
4805 ($mac:ident, $source:ty, $($target:ty),*) => {$(
4806 $mac!($target, $source);
4810 // intra-sign conversions
4811 try_from_upper_bounded!(u16, u8);
4812 try_from_upper_bounded!(u32, u16, u8);
4813 try_from_upper_bounded!(u64, u32, u16, u8);
4814 try_from_upper_bounded!(u128, u64, u32, u16, u8);
4816 try_from_both_bounded!(i16, i8);
4817 try_from_both_bounded!(i32, i16, i8);
4818 try_from_both_bounded!(i64, i32, i16, i8);
4819 try_from_both_bounded!(i128, i64, i32, i16, i8);
4821 // unsigned-to-signed
4822 try_from_upper_bounded!(u8, i8);
4823 try_from_upper_bounded!(u16, i8, i16);
4824 try_from_upper_bounded!(u32, i8, i16, i32);
4825 try_from_upper_bounded!(u64, i8, i16, i32, i64);
4826 try_from_upper_bounded!(u128, i8, i16, i32, i64, i128);
4828 // signed-to-unsigned
4829 try_from_lower_bounded!(i8, u8, u16, u32, u64, u128);
4830 try_from_lower_bounded!(i16, u16, u32, u64, u128);
4831 try_from_lower_bounded!(i32, u32, u64, u128);
4832 try_from_lower_bounded!(i64, u64, u128);
4833 try_from_lower_bounded!(i128, u128);
4834 try_from_both_bounded!(i16, u8);
4835 try_from_both_bounded!(i32, u16, u8);
4836 try_from_both_bounded!(i64, u32, u16, u8);
4837 try_from_both_bounded!(i128, u64, u32, u16, u8);
4840 try_from_upper_bounded!(usize, isize);
4841 try_from_lower_bounded!(isize, usize);
4843 #[cfg(target_pointer_width = "16")]
4844 mod ptr_try_from_impls {
4845 use super::TryFromIntError;
4846 use crate::convert::TryFrom;
4848 try_from_upper_bounded!(usize, u8);
4849 try_from_unbounded!(usize, u16, u32, u64, u128);
4850 try_from_upper_bounded!(usize, i8, i16);
4851 try_from_unbounded!(usize, i32, i64, i128);
4853 try_from_both_bounded!(isize, u8);
4854 try_from_lower_bounded!(isize, u16, u32, u64, u128);
4855 try_from_both_bounded!(isize, i8);
4856 try_from_unbounded!(isize, i16, i32, i64, i128);
4858 rev!(try_from_upper_bounded, usize, u32, u64, u128);
4859 rev!(try_from_lower_bounded, usize, i8, i16);
4860 rev!(try_from_both_bounded, usize, i32, i64, i128);
4862 rev!(try_from_upper_bounded, isize, u16, u32, u64, u128);
4863 rev!(try_from_both_bounded, isize, i32, i64, i128);
4866 #[cfg(target_pointer_width = "32")]
4867 mod ptr_try_from_impls {
4868 use super::TryFromIntError;
4869 use crate::convert::TryFrom;
4871 try_from_upper_bounded!(usize, u8, u16);
4872 try_from_unbounded!(usize, u32, u64, u128);
4873 try_from_upper_bounded!(usize, i8, i16, i32);
4874 try_from_unbounded!(usize, i64, i128);
4876 try_from_both_bounded!(isize, u8, u16);
4877 try_from_lower_bounded!(isize, u32, u64, u128);
4878 try_from_both_bounded!(isize, i8, i16);
4879 try_from_unbounded!(isize, i32, i64, i128);
4881 rev!(try_from_unbounded, usize, u32);
4882 rev!(try_from_upper_bounded, usize, u64, u128);
4883 rev!(try_from_lower_bounded, usize, i8, i16, i32);
4884 rev!(try_from_both_bounded, usize, i64, i128);
4886 rev!(try_from_unbounded, isize, u16);
4887 rev!(try_from_upper_bounded, isize, u32, u64, u128);
4888 rev!(try_from_unbounded, isize, i32);
4889 rev!(try_from_both_bounded, isize, i64, i128);
4892 #[cfg(target_pointer_width = "64")]
4893 mod ptr_try_from_impls {
4894 use super::TryFromIntError;
4895 use crate::convert::TryFrom;
4897 try_from_upper_bounded!(usize, u8, u16, u32);
4898 try_from_unbounded!(usize, u64, u128);
4899 try_from_upper_bounded!(usize, i8, i16, i32, i64);
4900 try_from_unbounded!(usize, i128);
4902 try_from_both_bounded!(isize, u8, u16, u32);
4903 try_from_lower_bounded!(isize, u64, u128);
4904 try_from_both_bounded!(isize, i8, i16, i32);
4905 try_from_unbounded!(isize, i64, i128);
4907 rev!(try_from_unbounded, usize, u32, u64);
4908 rev!(try_from_upper_bounded, usize, u128);
4909 rev!(try_from_lower_bounded, usize, i8, i16, i32, i64);
4910 rev!(try_from_both_bounded, usize, i128);
4912 rev!(try_from_unbounded, isize, u16, u32);
4913 rev!(try_from_upper_bounded, isize, u64, u128);
4914 rev!(try_from_unbounded, isize, i32, i64);
4915 rev!(try_from_both_bounded, isize, i128);
4919 trait FromStrRadixHelper: PartialOrd + Copy {
4920 fn min_value() -> Self;
4921 fn max_value() -> Self;
4922 fn from_u32(u: u32) -> Self;
4923 fn checked_mul(&self, other: u32) -> Option<Self>;
4924 fn checked_sub(&self, other: u32) -> Option<Self>;
4925 fn checked_add(&self, other: u32) -> Option<Self>;
4929 ($($t:ty)*) => ($(impl FromStrRadixHelper for $t {
4931 fn min_value() -> Self { Self::min_value() }
4933 fn max_value() -> Self { Self::max_value() }
4935 fn from_u32(u: u32) -> Self { u as Self }
4937 fn checked_mul(&self, other: u32) -> Option<Self> {
4938 Self::checked_mul(*self, other as Self)
4941 fn checked_sub(&self, other: u32) -> Option<Self> {
4942 Self::checked_sub(*self, other as Self)
4945 fn checked_add(&self, other: u32) -> Option<Self> {
4946 Self::checked_add(*self, other as Self)
4950 doit! { i8 i16 i32 i64 i128 isize u8 u16 u32 u64 u128 usize }
4952 fn from_str_radix<T: FromStrRadixHelper>(src: &str, radix: u32) -> Result<T, ParseIntError> {
4953 use self::IntErrorKind::*;
4954 use self::ParseIntError as PIE;
4956 assert!(radix >= 2 && radix <= 36,
4957 "from_str_radix_int: must lie in the range `[2, 36]` - found {}",
4961 return Err(PIE { kind: Empty });
4964 let is_signed_ty = T::from_u32(0) > T::min_value();
4966 // all valid digits are ascii, so we will just iterate over the utf8 bytes
4967 // and cast them to chars. .to_digit() will safely return None for anything
4968 // other than a valid ascii digit for the given radix, including the first-byte
4969 // of multi-byte sequences
4970 let src = src.as_bytes();
4972 let (is_positive, digits) = match src[0] {
4973 b'+' => (true, &src[1..]),
4974 b'-' if is_signed_ty => (false, &src[1..]),
4978 if digits.is_empty() {
4979 return Err(PIE { kind: Empty });
4982 let mut result = T::from_u32(0);
4984 // The number is positive
4986 let x = match (c as char).to_digit(radix) {
4988 None => return Err(PIE { kind: InvalidDigit }),
4990 result = match result.checked_mul(radix) {
4991 Some(result) => result,
4992 None => return Err(PIE { kind: Overflow }),
4994 result = match result.checked_add(x) {
4995 Some(result) => result,
4996 None => return Err(PIE { kind: Overflow }),
5000 // The number is negative
5002 let x = match (c as char).to_digit(radix) {
5004 None => return Err(PIE { kind: InvalidDigit }),
5006 result = match result.checked_mul(radix) {
5007 Some(result) => result,
5008 None => return Err(PIE { kind: Underflow }),
5010 result = match result.checked_sub(x) {
5011 Some(result) => result,
5012 None => return Err(PIE { kind: Underflow }),
5019 /// An error which can be returned when parsing an integer.
5021 /// This error is used as the error type for the `from_str_radix()` functions
5022 /// on the primitive integer types, such as [`i8::from_str_radix`].
5024 /// # Potential causes
5026 /// Among other causes, `ParseIntError` can be thrown because of leading or trailing whitespace
5027 /// in the string e.g., when it is obtained from the standard input.
5028 /// Using the [`str.trim()`] method ensures that no whitespace remains before parsing.
5030 /// [`str.trim()`]: ../../std/primitive.str.html#method.trim
5031 /// [`i8::from_str_radix`]: ../../std/primitive.i8.html#method.from_str_radix
5032 #[derive(Debug, Clone, PartialEq, Eq)]
5033 #[stable(feature = "rust1", since = "1.0.0")]
5034 pub struct ParseIntError {
5038 /// Enum to store the various types of errors that can cause parsing an integer to fail.
5039 #[unstable(feature = "int_error_matching",
5040 reason = "it can be useful to match errors when making error messages \
5041 for integer parsing",
5043 #[derive(Debug, Clone, PartialEq, Eq)]
5045 pub enum IntErrorKind {
5046 /// Value being parsed is empty.
5048 /// Among other causes, this variant will be constructed when parsing an empty string.
5050 /// Contains an invalid digit.
5052 /// Among other causes, this variant will be constructed when parsing a string that
5053 /// contains a letter.
5055 /// Integer is too large to store in target integer type.
5057 /// Integer is too small to store in target integer type.
5061 /// This variant will be emitted when the parsing string has a value of zero, which
5062 /// would be illegal for non-zero types.
5066 impl ParseIntError {
5067 /// Outputs the detailed cause of parsing an integer failing.
5068 #[unstable(feature = "int_error_matching",
5069 reason = "it can be useful to match errors when making error messages \
5070 for integer parsing",
5072 pub fn kind(&self) -> &IntErrorKind {
5075 #[unstable(feature = "int_error_internals",
5076 reason = "available through Error trait and this method should \
5077 not be exposed publicly",
5080 pub fn __description(&self) -> &str {
5082 IntErrorKind::Empty => "cannot parse integer from empty string",
5083 IntErrorKind::InvalidDigit => "invalid digit found in string",
5084 IntErrorKind::Overflow => "number too large to fit in target type",
5085 IntErrorKind::Underflow => "number too small to fit in target type",
5086 IntErrorKind::Zero => "number would be zero for non-zero type",
5091 #[stable(feature = "rust1", since = "1.0.0")]
5092 impl fmt::Display for ParseIntError {
5093 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
5094 self.__description().fmt(f)
5098 #[stable(feature = "rust1", since = "1.0.0")]
5099 pub use crate::num::dec2flt::ParseFloatError;
5101 // Conversion traits for primitive integer and float types
5102 // Conversions T -> T are covered by a blanket impl and therefore excluded
5103 // Some conversions from and to usize/isize are not implemented due to portability concerns
5104 macro_rules! impl_from {
5105 ($Small: ty, $Large: ty, #[$attr:meta], $doc: expr) => {
5108 impl From<$Small> for $Large {
5110 fn from(small: $Small) -> $Large {
5115 ($Small: ty, $Large: ty, #[$attr:meta]) => {
5119 concat!("Converts `",
5127 macro_rules! impl_from_bool {
5128 ($target: ty, #[$attr:meta]) => {
5129 impl_from!(bool, $target, #[$attr], concat!("Converts a `bool` to a `",
5130 stringify!($target), "`. The resulting value is `0` for `false` and `1` for `true`
5136 assert_eq!(", stringify!($target), "::from(true), 1);
5137 assert_eq!(", stringify!($target), "::from(false), 0);
5143 impl_from_bool! { u8, #[stable(feature = "from_bool", since = "1.28.0")] }
5144 impl_from_bool! { u16, #[stable(feature = "from_bool", since = "1.28.0")] }
5145 impl_from_bool! { u32, #[stable(feature = "from_bool", since = "1.28.0")] }
5146 impl_from_bool! { u64, #[stable(feature = "from_bool", since = "1.28.0")] }
5147 impl_from_bool! { u128, #[stable(feature = "from_bool", since = "1.28.0")] }
5148 impl_from_bool! { usize, #[stable(feature = "from_bool", since = "1.28.0")] }
5149 impl_from_bool! { i8, #[stable(feature = "from_bool", since = "1.28.0")] }
5150 impl_from_bool! { i16, #[stable(feature = "from_bool", since = "1.28.0")] }
5151 impl_from_bool! { i32, #[stable(feature = "from_bool", since = "1.28.0")] }
5152 impl_from_bool! { i64, #[stable(feature = "from_bool", since = "1.28.0")] }
5153 impl_from_bool! { i128, #[stable(feature = "from_bool", since = "1.28.0")] }
5154 impl_from_bool! { isize, #[stable(feature = "from_bool", since = "1.28.0")] }
5156 // Unsigned -> Unsigned
5157 impl_from! { u8, u16, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5158 impl_from! { u8, u32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5159 impl_from! { u8, u64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5160 impl_from! { u8, u128, #[stable(feature = "i128", since = "1.26.0")] }
5161 impl_from! { u8, usize, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5162 impl_from! { u16, u32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5163 impl_from! { u16, u64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5164 impl_from! { u16, u128, #[stable(feature = "i128", since = "1.26.0")] }
5165 impl_from! { u32, u64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5166 impl_from! { u32, u128, #[stable(feature = "i128", since = "1.26.0")] }
5167 impl_from! { u64, u128, #[stable(feature = "i128", since = "1.26.0")] }
5170 impl_from! { i8, i16, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5171 impl_from! { i8, i32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5172 impl_from! { i8, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5173 impl_from! { i8, i128, #[stable(feature = "i128", since = "1.26.0")] }
5174 impl_from! { i8, isize, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5175 impl_from! { i16, i32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5176 impl_from! { i16, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5177 impl_from! { i16, i128, #[stable(feature = "i128", since = "1.26.0")] }
5178 impl_from! { i32, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5179 impl_from! { i32, i128, #[stable(feature = "i128", since = "1.26.0")] }
5180 impl_from! { i64, i128, #[stable(feature = "i128", since = "1.26.0")] }
5182 // Unsigned -> Signed
5183 impl_from! { u8, i16, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5184 impl_from! { u8, i32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5185 impl_from! { u8, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5186 impl_from! { u8, i128, #[stable(feature = "i128", since = "1.26.0")] }
5187 impl_from! { u16, i32, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5188 impl_from! { u16, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5189 impl_from! { u16, i128, #[stable(feature = "i128", since = "1.26.0")] }
5190 impl_from! { u32, i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")] }
5191 impl_from! { u32, i128, #[stable(feature = "i128", since = "1.26.0")] }
5192 impl_from! { u64, i128, #[stable(feature = "i128", since = "1.26.0")] }
5194 // The C99 standard defines bounds on INTPTR_MIN, INTPTR_MAX, and UINTPTR_MAX
5195 // which imply that pointer-sized integers must be at least 16 bits:
5196 // https://port70.net/~nsz/c/c99/n1256.html#7.18.2.4
5197 impl_from! { u16, usize, #[stable(feature = "lossless_iusize_conv", since = "1.26.0")] }
5198 impl_from! { u8, isize, #[stable(feature = "lossless_iusize_conv", since = "1.26.0")] }
5199 impl_from! { i16, isize, #[stable(feature = "lossless_iusize_conv", since = "1.26.0")] }
5201 // RISC-V defines the possibility of a 128-bit address space (RV128).
5203 // CHERI proposes 256-bit “capabilities”. Unclear if this would be relevant to usize/isize.
5204 // https://www.cl.cam.ac.uk/research/security/ctsrd/pdfs/20171017a-cheri-poster.pdf
5205 // http://www.csl.sri.com/users/neumann/2012resolve-cheri.pdf
5208 // Note: integers can only be represented with full precision in a float if
5209 // they fit in the significand, which is 24 bits in f32 and 53 bits in f64.
5210 // Lossy float conversions are not implemented at this time.
5213 impl_from! { i8, f32, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
5214 impl_from! { i8, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
5215 impl_from! { i16, f32, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
5216 impl_from! { i16, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
5217 impl_from! { i32, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
5219 // Unsigned -> Float
5220 impl_from! { u8, f32, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
5221 impl_from! { u8, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
5222 impl_from! { u16, f32, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
5223 impl_from! { u16, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
5224 impl_from! { u32, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }
5227 impl_from! { f32, f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")] }