diff options
Diffstat (limited to 'library/core/src/num')
-rw-r--r-- | library/core/src/num/f32.rs | 44 | ||||
-rw-r--r-- | library/core/src/num/f64.rs | 42 | ||||
-rw-r--r-- | library/core/src/num/int_macros.rs | 43 | ||||
-rw-r--r-- | library/core/src/num/mod.rs | 11 | ||||
-rw-r--r-- | library/core/src/num/saturating.rs | 4 | ||||
-rw-r--r-- | library/core/src/num/uint_macros.rs | 18 |
6 files changed, 132 insertions, 30 deletions
diff --git a/library/core/src/num/f32.rs b/library/core/src/num/f32.rs index 290f649f9..f60626b00 100644 --- a/library/core/src/num/f32.rs +++ b/library/core/src/num/f32.rs @@ -377,6 +377,13 @@ impl f32 { pub const MANTISSA_DIGITS: u32 = 24; /// Approximate number of significant digits in base 10. + /// + /// This is the maximum <i>x</i> such that any decimal number with <i>x</i> + /// significant digits can be converted to `f32` and back without loss. + /// + /// Equal to floor(log<sub>10</sub> 2<sup>[`MANTISSA_DIGITS`] − 1</sup>). + /// + /// [`MANTISSA_DIGITS`]: f32::MANTISSA_DIGITS #[stable(feature = "assoc_int_consts", since = "1.43.0")] pub const DIGITS: u32 = 6; @@ -384,31 +391,62 @@ impl f32 { /// /// This is the difference between `1.0` and the next larger representable number. /// + /// Equal to 2<sup>1 − [`MANTISSA_DIGITS`]</sup>. + /// /// [Machine epsilon]: https://en.wikipedia.org/wiki/Machine_epsilon + /// [`MANTISSA_DIGITS`]: f32::MANTISSA_DIGITS #[stable(feature = "assoc_int_consts", since = "1.43.0")] pub const EPSILON: f32 = 1.19209290e-07_f32; /// Smallest finite `f32` value. + /// + /// Equal to −[`MAX`]. + /// + /// [`MAX`]: f32::MAX #[stable(feature = "assoc_int_consts", since = "1.43.0")] pub const MIN: f32 = -3.40282347e+38_f32; /// Smallest positive normal `f32` value. + /// + /// Equal to 2<sup>[`MIN_EXP`] − 1</sup>. + /// + /// [`MIN_EXP`]: f32::MIN_EXP #[stable(feature = "assoc_int_consts", since = "1.43.0")] pub const MIN_POSITIVE: f32 = 1.17549435e-38_f32; /// Largest finite `f32` value. + /// + /// Equal to + /// (1 − 2<sup>−[`MANTISSA_DIGITS`]</sup>) 2<sup>[`MAX_EXP`]</sup>. + /// + /// [`MANTISSA_DIGITS`]: f32::MANTISSA_DIGITS + /// [`MAX_EXP`]: f32::MAX_EXP #[stable(feature = "assoc_int_consts", since = "1.43.0")] pub const MAX: f32 = 3.40282347e+38_f32; /// One greater than the minimum possible normal power of 2 exponent. + /// + /// If <i>x</i> = `MIN_EXP`, then normal numbers + /// ≥ 0.5 × 2<sup><i>x</i></sup>. #[stable(feature = "assoc_int_consts", since = "1.43.0")] pub const MIN_EXP: i32 = -125; /// Maximum possible power of 2 exponent. + /// + /// If <i>x</i> = `MAX_EXP`, then normal numbers + /// < 1 × 2<sup><i>x</i></sup>. #[stable(feature = "assoc_int_consts", since = "1.43.0")] pub const MAX_EXP: i32 = 128; - /// Minimum possible normal power of 10 exponent. + /// Minimum <i>x</i> for which 10<sup><i>x</i></sup> is normal. + /// + /// Equal to ceil(log<sub>10</sub> [`MIN_POSITIVE`]). + /// + /// [`MIN_POSITIVE`]: f32::MIN_POSITIVE #[stable(feature = "assoc_int_consts", since = "1.43.0")] pub const MIN_10_EXP: i32 = -37; - /// Maximum possible power of 10 exponent. + /// Maximum <i>x</i> for which 10<sup><i>x</i></sup> is normal. + /// + /// Equal to floor(log<sub>10</sub> [`MAX`]). + /// + /// [`MAX`]: f32::MAX #[stable(feature = "assoc_int_consts", since = "1.43.0")] pub const MAX_10_EXP: i32 = 38; @@ -820,7 +858,7 @@ impl f32 { /// let angle = std::f32::consts::PI; /// /// let abs_difference = (angle.to_degrees() - 180.0).abs(); - /// + /// # #[cfg(any(not(target_arch = "x86"), target_feature = "sse2"))] /// assert!(abs_difference <= f32::EPSILON); /// ``` #[must_use = "this returns the result of the operation, \ diff --git a/library/core/src/num/f64.rs b/library/core/src/num/f64.rs index 7569d2cd6..0a87021d8 100644 --- a/library/core/src/num/f64.rs +++ b/library/core/src/num/f64.rs @@ -376,6 +376,13 @@ impl f64 { #[stable(feature = "assoc_int_consts", since = "1.43.0")] pub const MANTISSA_DIGITS: u32 = 53; /// Approximate number of significant digits in base 10. + /// + /// This is the maximum <i>x</i> such that any decimal number with <i>x</i> + /// significant digits can be converted to `f64` and back without loss. + /// + /// Equal to floor(log<sub>10</sub> 2<sup>[`MANTISSA_DIGITS`] − 1</sup>). + /// + /// [`MANTISSA_DIGITS`]: f64::MANTISSA_DIGITS #[stable(feature = "assoc_int_consts", since = "1.43.0")] pub const DIGITS: u32 = 15; @@ -383,31 +390,62 @@ impl f64 { /// /// This is the difference between `1.0` and the next larger representable number. /// + /// Equal to 2<sup>1 − [`MANTISSA_DIGITS`]</sup>. + /// /// [Machine epsilon]: https://en.wikipedia.org/wiki/Machine_epsilon + /// [`MANTISSA_DIGITS`]: f64::MANTISSA_DIGITS #[stable(feature = "assoc_int_consts", since = "1.43.0")] pub const EPSILON: f64 = 2.2204460492503131e-16_f64; /// Smallest finite `f64` value. + /// + /// Equal to −[`MAX`]. + /// + /// [`MAX`]: f64::MAX #[stable(feature = "assoc_int_consts", since = "1.43.0")] pub const MIN: f64 = -1.7976931348623157e+308_f64; /// Smallest positive normal `f64` value. + /// + /// Equal to 2<sup>[`MIN_EXP`] − 1</sup>. + /// + /// [`MIN_EXP`]: f64::MIN_EXP #[stable(feature = "assoc_int_consts", since = "1.43.0")] pub const MIN_POSITIVE: f64 = 2.2250738585072014e-308_f64; /// Largest finite `f64` value. + /// + /// Equal to + /// (1 − 2<sup>−[`MANTISSA_DIGITS`]</sup>) 2<sup>[`MAX_EXP`]</sup>. + /// + /// [`MANTISSA_DIGITS`]: f64::MANTISSA_DIGITS + /// [`MAX_EXP`]: f64::MAX_EXP #[stable(feature = "assoc_int_consts", since = "1.43.0")] pub const MAX: f64 = 1.7976931348623157e+308_f64; /// One greater than the minimum possible normal power of 2 exponent. + /// + /// If <i>x</i> = `MIN_EXP`, then normal numbers + /// ≥ 0.5 × 2<sup><i>x</i></sup>. #[stable(feature = "assoc_int_consts", since = "1.43.0")] pub const MIN_EXP: i32 = -1021; /// Maximum possible power of 2 exponent. + /// + /// If <i>x</i> = `MAX_EXP`, then normal numbers + /// < 1 × 2<sup><i>x</i></sup>. #[stable(feature = "assoc_int_consts", since = "1.43.0")] pub const MAX_EXP: i32 = 1024; - /// Minimum possible normal power of 10 exponent. + /// Minimum <i>x</i> for which 10<sup><i>x</i></sup> is normal. + /// + /// Equal to ceil(log<sub>10</sub> [`MIN_POSITIVE`]). + /// + /// [`MIN_POSITIVE`]: f64::MIN_POSITIVE #[stable(feature = "assoc_int_consts", since = "1.43.0")] pub const MIN_10_EXP: i32 = -307; - /// Maximum possible power of 10 exponent. + /// Maximum <i>x</i> for which 10<sup><i>x</i></sup> is normal. + /// + /// Equal to floor(log<sub>10</sub> [`MAX`]). + /// + /// [`MAX`]: f64::MAX #[stable(feature = "assoc_int_consts", since = "1.43.0")] pub const MAX_10_EXP: i32 = 308; diff --git a/library/core/src/num/int_macros.rs b/library/core/src/num/int_macros.rs index 3cbb55af3..fd01f1b26 100644 --- a/library/core/src/num/int_macros.rs +++ b/library/core/src/num/int_macros.rs @@ -471,7 +471,7 @@ macro_rules! int_impl { )] #[must_use = "this returns the result of the operation, \ without modifying the original"] - #[rustc_const_unstable(feature = "const_inherent_unchecked_arith", issue = "85122")] + #[rustc_const_unstable(feature = "unchecked_math", issue = "85122")] #[inline(always)] #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces pub const unsafe fn unchecked_add(self, rhs: Self) -> Self { @@ -539,7 +539,7 @@ macro_rules! int_impl { )] #[must_use = "this returns the result of the operation, \ without modifying the original"] - #[rustc_const_unstable(feature = "const_inherent_unchecked_arith", issue = "85122")] + #[rustc_const_unstable(feature = "unchecked_math", issue = "85122")] #[inline(always)] #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces pub const unsafe fn unchecked_sub(self, rhs: Self) -> Self { @@ -607,7 +607,7 @@ macro_rules! int_impl { )] #[must_use = "this returns the result of the operation, \ without modifying the original"] - #[rustc_const_unstable(feature = "const_inherent_unchecked_arith", issue = "85122")] + #[rustc_const_unstable(feature = "unchecked_math", issue = "85122")] #[inline(always)] #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces pub const unsafe fn unchecked_mul(self, rhs: Self) -> Self { @@ -740,6 +740,31 @@ macro_rules! int_impl { if unlikely!(b) {None} else {Some(a)} } + /// Unchecked negation. Computes `-self`, assuming overflow cannot occur. + /// + /// # Safety + /// + /// This results in undefined behavior when + #[doc = concat!("`self == ", stringify!($SelfT), "::MIN`,")] + /// i.e. when [`checked_neg`] would return `None`. + /// + #[doc = concat!("[`checked_neg`]: ", stringify!($SelfT), "::checked_neg")] + #[unstable( + feature = "unchecked_neg", + reason = "niche optimization path", + issue = "85122", + )] + #[must_use = "this returns the result of the operation, \ + without modifying the original"] + #[rustc_const_unstable(feature = "unchecked_neg", issue = "85122")] + #[inline(always)] + #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces + pub const unsafe fn unchecked_neg(self) -> Self { + // SAFETY: the caller must uphold the safety contract for + // `unchecked_neg`. + unsafe { intrinsics::unchecked_sub(0, self) } + } + /// Checked shift left. Computes `self << rhs`, returning `None` if `rhs` is larger /// than or equal to the number of bits in `self`. /// @@ -772,13 +797,13 @@ macro_rules! int_impl { /// #[doc = concat!("[`checked_shl`]: ", stringify!($SelfT), "::checked_shl")] #[unstable( - feature = "unchecked_math", + feature = "unchecked_shifts", reason = "niche optimization path", issue = "85122", )] #[must_use = "this returns the result of the operation, \ without modifying the original"] - #[rustc_const_unstable(feature = "const_inherent_unchecked_arith", issue = "85122")] + #[rustc_const_unstable(feature = "unchecked_shifts", issue = "85122")] #[inline(always)] #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces pub const unsafe fn unchecked_shl(self, rhs: u32) -> Self { @@ -820,13 +845,13 @@ macro_rules! int_impl { /// #[doc = concat!("[`checked_shr`]: ", stringify!($SelfT), "::checked_shr")] #[unstable( - feature = "unchecked_math", + feature = "unchecked_shifts", reason = "niche optimization path", issue = "85122", )] #[must_use = "this returns the result of the operation, \ without modifying the original"] - #[rustc_const_unstable(feature = "const_inherent_unchecked_arith", issue = "85122")] + #[rustc_const_unstable(feature = "unchecked_shifts", issue = "85122")] #[inline(always)] #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces pub const unsafe fn unchecked_shr(self, rhs: u32) -> Self { @@ -1404,7 +1429,7 @@ macro_rules! int_impl { #[must_use = "this returns the result of the operation, \ without modifying the original"] #[inline(always)] - #[rustc_allow_const_fn_unstable(const_inherent_unchecked_arith)] + #[rustc_allow_const_fn_unstable(unchecked_shifts)] pub const fn wrapping_shl(self, rhs: u32) -> Self { // SAFETY: the masking by the bitsize of the type ensures that we do not shift // out of bounds @@ -1434,7 +1459,7 @@ macro_rules! int_impl { #[must_use = "this returns the result of the operation, \ without modifying the original"] #[inline(always)] - #[rustc_allow_const_fn_unstable(const_inherent_unchecked_arith)] + #[rustc_allow_const_fn_unstable(unchecked_shifts)] pub const fn wrapping_shr(self, rhs: u32) -> Self { // SAFETY: the masking by the bitsize of the type ensures that we do not shift // out of bounds diff --git a/library/core/src/num/mod.rs b/library/core/src/num/mod.rs index 8b127132c..2a0b31404 100644 --- a/library/core/src/num/mod.rs +++ b/library/core/src/num/mod.rs @@ -114,7 +114,7 @@ macro_rules! midpoint_impl { without modifying the original"] #[inline] pub const fn midpoint(self, rhs: $SelfT) -> $SelfT { - // Use the well known branchless algorthim from Hacker's Delight to compute + // Use the well known branchless algorithm from Hacker's Delight to compute // `(a + b) / 2` without overflowing: `((a ^ b) >> 1) + (a & b)`. ((self ^ rhs) >> 1) + (self & rhs) } @@ -791,7 +791,7 @@ impl u8 { #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")] #[inline] pub const fn is_ascii_alphanumeric(&self) -> bool { - matches!(*self, b'0'..=b'9' | b'A'..=b'Z' | b'a'..=b'z') + matches!(*self, b'0'..=b'9') | matches!(*self, b'A'..=b'Z') | matches!(*self, b'a'..=b'z') } /// Checks if the value is an ASCII decimal digit: @@ -894,7 +894,7 @@ impl u8 { #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")] #[inline] pub const fn is_ascii_hexdigit(&self) -> bool { - matches!(*self, b'0'..=b'9' | b'A'..=b'F' | b'a'..=b'f') + matches!(*self, b'0'..=b'9') | matches!(*self, b'A'..=b'F') | matches!(*self, b'a'..=b'f') } /// Checks if the value is an ASCII punctuation character: @@ -932,7 +932,10 @@ impl u8 { #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")] #[inline] pub const fn is_ascii_punctuation(&self) -> bool { - matches!(*self, b'!'..=b'/' | b':'..=b'@' | b'['..=b'`' | b'{'..=b'~') + matches!(*self, b'!'..=b'/') + | matches!(*self, b':'..=b'@') + | matches!(*self, b'['..=b'`') + | matches!(*self, b'{'..=b'~') } /// Checks if the value is an ASCII graphic character: diff --git a/library/core/src/num/saturating.rs b/library/core/src/num/saturating.rs index d9ccc73c4..d040539eb 100644 --- a/library/core/src/num/saturating.rs +++ b/library/core/src/num/saturating.rs @@ -35,9 +35,7 @@ use crate::ops::{Sub, SubAssign}; #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Copy, Default, Hash)] #[repr(transparent)] #[rustc_diagnostic_item = "Saturating"] -pub struct Saturating<T>( - #[stable(feature = "saturating_int_impl", since = "1.74.0")] pub T, -); +pub struct Saturating<T>(#[stable(feature = "saturating_int_impl", since = "1.74.0")] pub T); #[stable(feature = "saturating_int_impl", since = "1.74.0")] impl<T: fmt::Debug> fmt::Debug for Saturating<T> { diff --git a/library/core/src/num/uint_macros.rs b/library/core/src/num/uint_macros.rs index a9c5312a1..11a53aaf1 100644 --- a/library/core/src/num/uint_macros.rs +++ b/library/core/src/num/uint_macros.rs @@ -479,7 +479,7 @@ macro_rules! uint_impl { )] #[must_use = "this returns the result of the operation, \ without modifying the original"] - #[rustc_const_unstable(feature = "const_inherent_unchecked_arith", issue = "85122")] + #[rustc_const_unstable(feature = "unchecked_math", issue = "85122")] #[inline(always)] #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces pub const unsafe fn unchecked_add(self, rhs: Self) -> Self { @@ -548,7 +548,7 @@ macro_rules! uint_impl { )] #[must_use = "this returns the result of the operation, \ without modifying the original"] - #[rustc_const_unstable(feature = "const_inherent_unchecked_arith", issue = "85122")] + #[rustc_const_unstable(feature = "unchecked_math", issue = "85122")] #[inline(always)] #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces pub const unsafe fn unchecked_sub(self, rhs: Self) -> Self { @@ -595,7 +595,7 @@ macro_rules! uint_impl { )] #[must_use = "this returns the result of the operation, \ without modifying the original"] - #[rustc_const_unstable(feature = "const_inherent_unchecked_arith", issue = "85122")] + #[rustc_const_unstable(feature = "unchecked_math", issue = "85122")] #[inline(always)] #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces pub const unsafe fn unchecked_mul(self, rhs: Self) -> Self { @@ -926,13 +926,13 @@ macro_rules! uint_impl { /// #[doc = concat!("[`checked_shl`]: ", stringify!($SelfT), "::checked_shl")] #[unstable( - feature = "unchecked_math", + feature = "unchecked_shifts", reason = "niche optimization path", issue = "85122", )] #[must_use = "this returns the result of the operation, \ without modifying the original"] - #[rustc_const_unstable(feature = "const_inherent_unchecked_arith", issue = "85122")] + #[rustc_const_unstable(feature = "unchecked_shifts", issue = "85122")] #[inline(always)] #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces pub const unsafe fn unchecked_shl(self, rhs: u32) -> Self { @@ -974,13 +974,13 @@ macro_rules! uint_impl { /// #[doc = concat!("[`checked_shr`]: ", stringify!($SelfT), "::checked_shr")] #[unstable( - feature = "unchecked_math", + feature = "unchecked_shifts", reason = "niche optimization path", issue = "85122", )] #[must_use = "this returns the result of the operation, \ without modifying the original"] - #[rustc_const_unstable(feature = "const_inherent_unchecked_arith", issue = "85122")] + #[rustc_const_unstable(feature = "unchecked_shifts", issue = "85122")] #[inline(always)] #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces pub const unsafe fn unchecked_shr(self, rhs: u32) -> Self { @@ -1418,7 +1418,7 @@ macro_rules! uint_impl { #[must_use = "this returns the result of the operation, \ without modifying the original"] #[inline(always)] - #[rustc_allow_const_fn_unstable(const_inherent_unchecked_arith)] + #[rustc_allow_const_fn_unstable(unchecked_shifts)] pub const fn wrapping_shl(self, rhs: u32) -> Self { // SAFETY: the masking by the bitsize of the type ensures that we do not shift // out of bounds @@ -1451,7 +1451,7 @@ macro_rules! uint_impl { #[must_use = "this returns the result of the operation, \ without modifying the original"] #[inline(always)] - #[rustc_allow_const_fn_unstable(const_inherent_unchecked_arith)] + #[rustc_allow_const_fn_unstable(unchecked_shifts)] pub const fn wrapping_shr(self, rhs: u32) -> Self { // SAFETY: the masking by the bitsize of the type ensures that we do not shift // out of bounds |