From e4f4335b07511589f4508527f9deaaa239f3c5ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20Ho=C5=99e=C5=88ovsk=C3=BD?= Date: Mon, 27 Feb 2017 14:22:17 +0100 Subject: [PATCH] Improved Approx documentation --- docs/assertions.md | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/docs/assertions.md b/docs/assertions.md index d3a9047..ff79f0e 100644 --- a/docs/assertions.md +++ b/docs/assertions.md @@ -53,13 +53,32 @@ Catch provides a way to perform tolerant comparisons of floating point values th REQUIRE( performComputation() == Approx( 2.1 ) ); ``` -By default a small epsilon value is used that covers many simple cases of rounding errors. When this is insufficent the epsilon value (the amount within which a difference either way is ignored) can be specified by calling the ```epsilon()``` method on the ```Approx``` instance. e.g.: +This way `Approx` is constructed with reasonable defaults, covering most simple cases of rounding errors. If these are insufficient, each `Approx` instance has 3 tuning knobs, that can be used to customize it for your computation. -``` -REQUIRE( 22/7 == Approx( 3.141 ).epsilon( 0.01 ) ); +* __epsilon__ - epsilon serves to set the percentage by which a result can be erroneous, before it is rejected. By default set to `std::numeric_limits::epsilon()*100`. +* __margin__ - margin serves to set the the absolute value by which a result can be erroneous before it is rejected. By default set to `0.0`. +* __scale__ - scale serves to adjust the base for comparison used by epsilon, can be used when By default set to `1.0`. + +#### epsilon example +```cpp +Approx target = Approx(100).epsilon(0.01); +100.0 == target; // Obviously true +200.0 == target; // Obviously still false +100.5 == target; // True, because we set target to allow up to 1% error ``` -When dealing with very large or very small numbers it can be useful to specify a scale, which can be achieved by calling the ```scale()``` method on the ```Approx``` instance. +#### margin example +_Margin check is used only if the relative (epsilon and scale based) check fails._ +```cpp +Approx target = Approx(100).margin(5); +100.0 == target; // Obviously true +200.0 == target; // Obviously still false +104.0 == target; // True, because we set target to allow absolute error up to 5 +``` + +#### scale +Scale can be useful if the computation leading to the result worked on different scale, than is used by the results (and thus expected errors are on a different scale than would be expected based on the results alone). + ## Exceptions