mirror of
https://github.com/catchorg/Catch2.git
synced 2025-08-03 05:45:39 +02:00
Centralize and update docs for floating point comparisons
The new docs mention that Approx is deprecated and should not be used, and explain the reasons behind it. Closes #1444
This commit is contained in:
@@ -150,49 +150,8 @@ are:
|
||||
|
||||
> `WithinRel` matcher was introduced in Catch2 2.10.0
|
||||
|
||||
|
||||
`WithinAbs` creates a matcher that accepts floating point numbers whose
|
||||
difference with `target` is less than the `margin`.
|
||||
|
||||
`WithinULP` creates a matcher that accepts floating point numbers that
|
||||
are no more than `maxUlpDiff`
|
||||
[ULPs](https://en.wikipedia.org/wiki/Unit_in_the_last_place)
|
||||
away from the `target` value. The short version of what this means
|
||||
is that there is no more than `maxUlpDiff - 1` representable floating
|
||||
point numbers between the argument for matching and the `target` value.
|
||||
|
||||
**Important**: The WithinULP matcher requires the platform to use the
|
||||
[IEEE-754](https://en.wikipedia.org/wiki/IEEE_754) representation for
|
||||
floating point numbers.
|
||||
|
||||
|
||||
`WithinRel` creates a matcher that accepts floating point numbers that
|
||||
are _approximately equal_ with the `target` with tolerance of `eps.`
|
||||
Specifically, it matches if
|
||||
`|arg - target| <= eps * max(|arg|, |target|)` holds. If you do not
|
||||
specify `eps`, `std::numeric_limits<FloatingPoint>::epsilon * 100`
|
||||
is used as the default.
|
||||
|
||||
|
||||
In practice, you will often want to combine multiple of these matchers,
|
||||
together for an assertion, because all 3 options have edge cases where
|
||||
they behave differently than you would expect. As an example, under
|
||||
the `WithinRel` matcher, a `0.` only ever matches a `0.` (or `-0.`),
|
||||
regardless of the relative tolerance specified. Thus, if you want to
|
||||
handle numbers that are "close enough to 0 to be 0", you have to combine
|
||||
it with the `WithinAbs` matcher.
|
||||
|
||||
For example, to check that our computation matches known good value
|
||||
within 0.1%, or is close enough (no different to 5 decimal places)
|
||||
to zero, we would write this assertion:
|
||||
```cpp
|
||||
REQUIRE_THAT( computation(input),
|
||||
Catch::Matchers::WithinRel(expected, 0.001)
|
||||
|| Catch::Matchers::WithinAbs(0, 0.000001) );
|
||||
```
|
||||
|
||||
|
||||
> floating point matchers live in `catch2/matchers/catch_matchers_floating.hpp`
|
||||
For more details, read [the docs on comparing floating point
|
||||
numbers](comparing-floating-point-numbers.md#floating-point-matchers).
|
||||
|
||||
|
||||
### Miscellaneous matchers
|
||||
|
Reference in New Issue
Block a user