Rollup merge of #47277 - tspiteri:log-correctness, r=frewsxcv

doc: show that `f32::log` and `f64::log` are not correctly rounded

Fixes #47273.

One thing I'm not sure about is whether the "calculated as `self.ln() / base.ln()`" bit is being too specific, maybe we do not want to make this such a strong commitment. I think it's fine, but we should not make commitments in the API documentation by accident.

In case that is removed, the added sentence "`self.log2()` can ... base 10." still makes it amply clear that the `log` methods can be more inaccurate than other methods. If the above clause is removed, this second sentence can be moved to the first paragraph, kind of like the accuracy comment for the [`mul_add`](https://doc.rust-lang.org/std/primitive.f32.html#method.mul_add) method.

diff --git a/src/libstd/f32.rs b/src/libstd/f32.rs
index 6d76c7e722c459b9253a0601578fdba5f2d58c9e..5e5695f15ac3faa526ebb33d7fe924d8c9f8b6fe 100644 (file)
--- a/src/libstd/f32.rs
+++ b/src/libstd/f32.rs
@@ -472,20 +472,19 @@ pub fn ln(self) -> f32 {
 
     /// Returns the logarithm of the number with respect to an arbitrary base.
     ///
+    /// The result may not be correctly rounded owing to implementation details;
+    /// `self.log2()` can produce more accurate results for base 2, and
+    /// `self.log10()` can produce more accurate results for base 10.
+    ///
     /// ```
     /// use std::f32;
     ///
-    /// let ten = 10.0f32;
-    /// let two = 2.0f32;
-    ///
-    /// // log10(10) - 1 == 0
-    /// let abs_difference_10 = (ten.log(10.0) - 1.0).abs();
+    /// let five = 5.0f32;
     ///
-    /// // log2(2) - 1 == 0
-    /// let abs_difference_2 = (two.log(2.0) - 1.0).abs();
+    /// // log5(5) - 1 == 0
+    /// let abs_difference = (five.log(5.0) - 1.0).abs();
     ///
-    /// assert!(abs_difference_10 <= f32::EPSILON);
-    /// assert!(abs_difference_2 <= f32::EPSILON);
+    /// assert!(abs_difference <= f32::EPSILON);
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     #[inline]

diff --git a/src/libstd/f64.rs b/src/libstd/f64.rs
index dee9566f1fc688f3dcd49992103088be67c1048b..e4eea745bb77c17bde809aceb03504427b57eca6 100644 (file)
--- a/src/libstd/f64.rs
+++ b/src/libstd/f64.rs
@@ -432,18 +432,17 @@ pub fn ln(self) -> f64 {
 
     /// Returns the logarithm of the number with respect to an arbitrary base.
     ///
-    /// ```
-    /// let ten = 10.0_f64;
-    /// let two = 2.0_f64;
+    /// The result may not be correctly rounded owing to implementation details;
+    /// `self.log2()` can produce more accurate results for base 2, and
+    /// `self.log10()` can produce more accurate results for base 10.
     ///
-    /// // log10(10) - 1 == 0
-    /// let abs_difference_10 = (ten.log(10.0) - 1.0).abs();
+    /// ```
+    /// let five = 5.0_f64;
     ///
-    /// // log2(2) - 1 == 0
-    /// let abs_difference_2 = (two.log(2.0) - 1.0).abs();
+    /// // log5(5) - 1 == 0
+    /// let abs_difference = (five.log(5.0) - 1.0).abs();
     ///
-    /// assert!(abs_difference_10 < 1e-10);
-    /// assert!(abs_difference_2 < 1e-10);
+    /// assert!(abs_difference < 1e-10);
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     #[inline]