Provide more context for what the {f32,f64}::EPSILON values represent. #50919
Conversation
pietroalbini
added
the
S-waiting-on-review
|
r? @steveklabnik (someone from docs) |
|
Ping from triage @steveklabnik! This PR needs your review. |
src/libcore/num/f32.rs
Outdated
| @@ -33,7 +33,10 @@ pub const MANTISSA_DIGITS: u32 = 24; | |||
| #[stable(feature = "rust1", since = "1.0.0")] | |||
| pub const DIGITS: u32 = 6; | |||
|
|
|||
| /// Difference between `1.0` and the next largest representable number. | |||
| /// [Machine epsilon] value for `f32`. Difference between `1.0` and the next | |||
| /// largest representable number. | |||
There was a problem hiding this comment.
Could you change this to
/// [Machine epsilon] value for `f32`.
///
/// This is the difference between `1.0` and the next largest representable number.
src/libcore/num/f64.rs
Outdated
| /// [Machine epsilon] value for `f64`. Difference between `1.0` and the next | ||
| /// largest representable number. | ||
| /// | ||
| /// [Machine epsilon]: https://en.wikipedia.org/wiki/Machine_epsilon |
frewsxcv
force-pushed
the
frewsxcv-epsilon
branch
from
ead4213 to
12878a7
Compare
frewsxcv
dismissed
steveklabnik’s stale review
comments addressed in the latest force push
|
@bors r=steveklabnik rollup |
|
📌 Commit 12878a7 has been approved by |
bors
added
S-waiting-on-bors
…labnik
Provide more context for what the {f32,f64}::EPSILON values represent.
Introduce the 'machine epsilon' term because if one googles 'epsilon', they might stumble upon https://en.wikipedia.org/wiki/Epsilon_numbers_(mathematics) instead of https://en.wikipedia.org/wiki/Machine_epsilon
Rollup of 6 pull requests Successful merges: - #50167 ( Add as_nanos function to Duration) - #50919 (Provide more context for what the {f32,f64}::EPSILON values represent.) - #51124 (Reword {ptr,mem}::replace docs.) - #51147 (Stabilize SliceIndex trait.) - #51291 (Fix typos of ‘ambiguous’) - #51302 (Permit building rustdoc without compiler artifacts) Failed merges:
| /// Difference between `1.0` and the next largest representable number. | ||
| /// [Machine epsilon] value for `f64`. | ||
| /// | ||
| /// This is the difference between `1.0` and the next largest representable number. |
There was a problem hiding this comment.
For me this does not parse correctly. Epsilon is the number which when added to 1.0 will yield a different number than 1.0. This sounds more correct to me:
This is the difference between
1.0and the next smallest representable number.
There was a problem hiding this comment.
Would it be clearer if it was "next larger representable number"? The usage of "large" is to indicate it's in the positive direction (above 1.0). Maybe it's sufficient to just say "next representable number"?
There was a problem hiding this comment.
@frewsxcv Yes, both would work for me. I'm not a mathematician but if I remember correctly the direction doesn't even matter.
There was a problem hiding this comment.
The direction does matter because floating point numbers < 1 have a smaller exponent (due to normalization) and therefore are more dense than those >= 1. The "epsilon" in the other direction would be half of the one in the positive direction.
There was a problem hiding this comment.
@rkruppe Oh right, I forgot about normalisation. Thanks for the reminder.
Clarify `{f32,f64}::EPSILON` docs
The doc for `EPSILON` says:
> This is the difference between `1.0` and the next **largest** representable number.
Which is a bit unclear.
[Wikipedia](https://en.wikipedia.org/wiki/Machine_epsilon) says
> Machine epsilon is defined as the difference between 1 and the next **larger** floating point number
So this PR update the docs to match the Wikipedia version.
The original PR also has this in a [comment](rust-lang#50919 (comment)).
Clarify `{f32,f64}::EPSILON` docs
The doc for `EPSILON` says:
> This is the difference between `1.0` and the next **largest** representable number.
Which is a bit unclear.
[Wikipedia](https://en.wikipedia.org/wiki/Machine_epsilon) says
> Machine epsilon is defined as the difference between 1 and the next **larger** floating point number
So this PR update the docs to match the Wikipedia version.
The original PR also has this in a [comment](rust-lang#50919 (comment)).
Introduce the 'machine epsilon' term because if one googles 'epsilon', they might stumble upon https://en.wikipedia.org/wiki/Epsilon_numbers_(mathematics) instead of https://en.wikipedia.org/wiki/Machine_epsilon