From af6f0f2e1011b359cca0d16d9430e293d21ff707 Mon Sep 17 00:00:00 2001 From: Fabian Kössel Date: Mon, 30 Apr 2018 16:06:53 +0200 Subject: Document round-off error in `.mod_euc()`-method, see issue #50179 --- src/libstd/f32.rs | 7 ++++++- src/libstd/f64.rs | 7 ++++++- 2 files changed, 12 insertions(+), 2 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/f32.rs b/src/libstd/f32.rs index ae30321f46d..24204670229 100644 --- a/src/libstd/f32.rs +++ b/src/libstd/f32.rs @@ -254,7 +254,10 @@ impl f32 { /// Calculates the Euclidean modulo (self mod rhs), which is never negative. /// - /// In particular, the result `n` satisfies `0 <= n < rhs.abs()`. + /// In particular, the return value `r` satisfies `0.0 <= r < rhs.abs()` in + /// most cases. However, due to a floating point round-off error it can + /// result in `r == rhs.abs()`, violating the mathematical definition, if + /// `self` is much smaller than `rhs.abs()` in magnitude and `self < 0.0`. /// /// # Examples /// @@ -266,6 +269,8 @@ impl f32 { /// assert_eq!((-a).mod_euc(b), 1.0); /// assert_eq!(a.mod_euc(-b), 3.0); /// assert_eq!((-a).mod_euc(-b), 1.0); + /// // limitation due to round-off error + /// assert!((-std::f32::EPSILON).mod_euc(3.0) != 0.0); /// ``` #[inline] #[unstable(feature = "euclidean_division", issue = "49048")] diff --git a/src/libstd/f64.rs b/src/libstd/f64.rs index 7950d434b77..bd7ef2eb1a4 100644 --- a/src/libstd/f64.rs +++ b/src/libstd/f64.rs @@ -230,7 +230,10 @@ impl f64 { /// Calculates the Euclidean modulo (self mod rhs), which is never negative. /// - /// In particular, the result `n` satisfies `0 <= n < rhs.abs()`. + /// In particular, the return value `r` satisfies `0.0 <= r < rhs.abs()` in + /// most cases. However, due to a floating point round-off error it can + /// result in `r == rhs.abs()`, violating the mathematical definition, if + /// `self` is much smaller than `rhs.abs()` in magnitude and `self < 0.0`. /// /// # Examples /// @@ -242,6 +245,8 @@ impl f64 { /// assert_eq!((-a).mod_euc(b), 1.0); /// assert_eq!(a.mod_euc(-b), 3.0); /// assert_eq!((-a).mod_euc(-b), 1.0); + /// // limitation due to round-off error + /// assert!((-std::f64::EPSILON).mod_euc(3.0) != 0.0); /// ``` #[inline] #[unstable(feature = "euclidean_division", issue = "49048")] -- cgit 1.4.1-3-g733a5