diff options
| -rw-r--r-- | library/core/src/num/dec2flt/mod.rs | 6 | ||||
| -rw-r--r-- | library/core/src/primitive_docs.rs | 13 | ||||
| -rw-r--r-- | library/std/src/primitive_docs.rs | 13 |
3 files changed, 30 insertions, 2 deletions
diff --git a/library/core/src/num/dec2flt/mod.rs b/library/core/src/num/dec2flt/mod.rs index 541adb69b8e..df0e7431f1f 100644 --- a/library/core/src/num/dec2flt/mod.rs +++ b/library/core/src/num/dec2flt/mod.rs @@ -143,8 +143,10 @@ macro_rules! from_str_float_impl { /// # Return value /// /// `Err(ParseFloatError)` if the string did not represent a valid - /// number. Otherwise, `Ok(n)` where `n` is the floating-point - /// number represented by `src`. + /// number. Otherwise, `Ok(n)` where `n` is the closest + /// representable floating-point number to the number represented + /// by `src` (following the same rules for rounding as for the + /// results of primitive operations). #[inline] fn from_str(src: &str) -> Result<Self, ParseFloatError> { dec2flt(src) diff --git a/library/core/src/primitive_docs.rs b/library/core/src/primitive_docs.rs index ac4e668112b..631cc313fa0 100644 --- a/library/core/src/primitive_docs.rs +++ b/library/core/src/primitive_docs.rs @@ -994,6 +994,19 @@ mod prim_tuple {} /// surprising results upon inspecting the bit patterns, /// as the same calculations might produce NaNs with different bit patterns. /// +/// When the number resulting from a primitive operation (addition, +/// subtraction, multiplication, or division) on this type is not exactly +/// representable as `f32`, it is rounded according to the roundTiesToEven +/// direction defined in IEEE 754-2008. That means: +/// +/// - The result is the representable value closest to the true value, if there +/// is a unique closest representable value. +/// - If the true value is exactly half-way between two representable values, +/// the result is the one with an even least-significant binary digit. +/// - If the true value's magnitude is ≥ `f32::MAX` + 2<sup>(`f32::MAX_EXP` − +/// `f32::MANTISSA_DIGITS` − 1)</sup>, the result is ∞ or −∞ (preserving the +/// true value's sign). +/// /// For more information on floating point numbers, see [Wikipedia][wikipedia]. /// /// *[See also the `std::f32::consts` module](crate::f32::consts).* diff --git a/library/std/src/primitive_docs.rs b/library/std/src/primitive_docs.rs index ac4e668112b..631cc313fa0 100644 --- a/library/std/src/primitive_docs.rs +++ b/library/std/src/primitive_docs.rs @@ -994,6 +994,19 @@ mod prim_tuple {} /// surprising results upon inspecting the bit patterns, /// as the same calculations might produce NaNs with different bit patterns. /// +/// When the number resulting from a primitive operation (addition, +/// subtraction, multiplication, or division) on this type is not exactly +/// representable as `f32`, it is rounded according to the roundTiesToEven +/// direction defined in IEEE 754-2008. That means: +/// +/// - The result is the representable value closest to the true value, if there +/// is a unique closest representable value. +/// - If the true value is exactly half-way between two representable values, +/// the result is the one with an even least-significant binary digit. +/// - If the true value's magnitude is ≥ `f32::MAX` + 2<sup>(`f32::MAX_EXP` − +/// `f32::MANTISSA_DIGITS` − 1)</sup>, the result is ∞ or −∞ (preserving the +/// true value's sign). +/// /// For more information on floating point numbers, see [Wikipedia][wikipedia]. /// /// *[See also the `std::f32::consts` module](crate::f32::consts).* |