Document round-off error in `.mod_euc()`-method, see issue #50179

diff --git a/src/libstd/f32.rs b/src/libstd/f32.rs
index ae30321f46dfca4ed02c039e88b7ce28028c62d5..242046702298aa5cb62e1314446dd046714cf178 100644 (file)
--- a/src/libstd/f32.rs
+++ b/src/libstd/f32.rs
@@ -254,7 +254,10 @@ pub fn div_euc(self, rhs: f32) -> 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 @@ pub fn div_euc(self, rhs: f32) -> 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 7950d434b77e67a5c7302fdafc42c855965e0527..bd7ef2eb1a4ff81cf8dcf2a8dbf80a4b2028a7b7 100644 (file)
--- a/src/libstd/f64.rs
+++ b/src/libstd/f64.rs
@@ -230,7 +230,10 @@ pub fn div_euc(self, rhs: f64) -> 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 @@ pub fn div_euc(self, rhs: f64) -> 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")]