`f32`/`f64` examples should not use `EPSILON` as an absolute tolerance value

[SludgePhD]

Many examples on the floating-point types incorrectly teach readers that EPSILON is an appropriate tolerance value for approximate comparisons. For instance, the example for f32::mul_add looks like this:

let m = 10.0_f32;
let x = 4.0_f32;
let b = 60.0_f32;

// 100.0
let abs_difference = (m.mul_add(x, b) - ((m * x) + b)).abs();

assert!(abs_difference <= f32::EPSILON);

The machine epsilon is unsuitable for this use case. It is not a general-purpose tolerance value for comparisons, and it should not be taught like it is one.

More in-depth information about how to properly deal with floats can be found here: https://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/

(I suppose ideally libstd would have some API for this built in so that the examples can make use of it)

[scottmcm]

Yes, something like assert_matches!(A.ulp_from(B), Some(-1..=1)); would be far superior here.

[Muon]

On top of checking absolute instead of relative error against f32::EPSILON, that's an absolutely horrid example, because it contains no rounding whatsoever, since m * x == 40.0f32 and 40.0f32 + b == 100.0f32 exactly.

[quaternic]

For mul_add specifically, something like this might be a better demonstration of what it can do:

let x = 2.0f32.powi(20);
let xp = x + 1.0;
let xm = x - 1.0;
let x2 = x * x;
// Algebraically, xp * xm == x2 - 1, but f32 does not
// have enough precision to hold that exact value:
assert_eq!(xp * xm, x2);
// However, mul_add allows computing the difference
// without the intermediate rounding:
// (xp * xm) - x2 == -1
assert_eq!(xp.mul_add(xm, -x2), -1.0);