Documentation for sub is-approx assembled from the following types:

module Test

From Test

(Test) sub is-approx

Defined as:

multi sub is-approx(Numeric $got, Numeric $expected, $desc = '')

multi sub is-approx(Numeric $got, Numeric $expected, Numeric $abs-tol,
                    $desc = '')

multi sub is-approx(Numeric $got, Numeric $expected, $desc = '',
                    Numeric :$rel-tol is required)

multi sub is-approx(Numeric $got, Numeric $expected, $desc = '',
                    Numeric :$abs-tol is required)

multi sub is-approx(Numeric $got, Numeric $expected, $desc = '',
                    Numeric :$rel-tol is required,
                    Numeric :$abs-tol is required)

Marks a test as passed if the $value and $expected numerical values are approximately equal to each other. The subroutine can be called in numerous ways that let you test using relative tolerance ($rel-tol) or absolute tolerance ($abs-tol) of different values.

If no tolerance is set, the function will base the tolerance on the absolute value of $expected: if it's smaller than 1e-6, use absolute tolerance of 1e-5; if it's larger, use relative tolerance of 1e-6.

    my Numeric ($value, $expected, $abs-tol, $rel-tol) = ...
 
    is-approx $value, $expected;
    is-approx $value, $expected, 'test description';
 
    is-approx $value, $expected, $abs-tol;
    is-approx $value, $expected, $abs-tol, 'test description';
 
    is-approx $value, $expected, :$rel-tol;
    is-approx $value, $expected, :$rel-tol, 'test description';
 
    is-approx $value, $expected, :$abs-tol;
    is-approx $value, $expected, :$abs-tol, 'test description';
 
    is-approx $value, $expected, :$abs-tol, :$rel-tol;
    is-approx $value, $expected, :$abs-tol, :$rel-tol, 'test description';

Absolute tolerance

When an absolute tolerance is set, it's used as the actual maximum value by which the $value and $expected can differ. For example:

    is-approx 3, 4, 2; # success 
    is-approx 3, 6, 2; # fail 
 
    is-approx 300, 302, 2; # success 
    is-approx 300, 400, 2; # fail 
    is-approx 300, 600, 2; # fail 

Regardless of values given, the difference between them cannot be more than 2.

Relative tolerance

When a relative tolerance is set, the test checks the relative difference between values. Given the same tolerance, the larger the numbers given, the larger the value they can differ by can be.

For example:

    is-approx 10, 10.5, :rel-tol<0.1>; # success 
    is-approx 10, 11.5, :rel-tol<0.1>; # fail 
 
    is-approx 100, 105, :rel-tol<0.1>; # success 
    is-approx 100, 115, :rel-tol<0.1>; # fail 

Both versions use 0.1 for relative tolerance, yet the first can differ by about 1 while the second can differ by about 10. The function used to calculate the difference is:

              |value - expected|
⁣rel-diff = ────────────────────────
           max(|value|, |expected|)

and the test will fail if rel-diff is higher than $rel-tol.

Both absolute and relative tolerance specified

is-approx $value, $expected, :rel-tol<.5>, :abs-tol<10>;

When both absolute and relative tolerances are specified, each will be tested independently, and the is-approx test will succeed only if both pass.