| 1 |
NAME |
| 2 |
Test::Number::Delta - Compare the difference between numbers against a |
| 3 |
given tolerance |
| 4 |
|
| 5 |
VERSION |
| 6 |
version 1.06 |
| 7 |
|
| 8 |
SYNOPSIS |
| 9 |
# Import test functions |
| 10 |
use Test::Number::Delta; |
| 11 |
|
| 12 |
# Equality test with default tolerance |
| 13 |
delta_ok( 1e-5, 2e-5, 'values within 1e-6'); |
| 14 |
|
| 15 |
# Inequality test with default tolerance |
| 16 |
delta_not_ok( 1e-5, 2e-5, 'values not within 1e-6'); |
| 17 |
|
| 18 |
# Provide specific tolerance |
| 19 |
delta_within( 1e-3, 2e-3, 1e-4, 'values within 1e-4'); |
| 20 |
delta_not_within( 1e-3, 2e-3, 1e-4, 'values not within 1e-4'); |
| 21 |
|
| 22 |
# Compare arrays or matrices |
| 23 |
@a = ( 3.14, 1.41 ); |
| 24 |
@b = ( 3.15, 1.41 ); |
| 25 |
delta_ok( \@a, \@b, 'compare @a and @b' ); |
| 26 |
|
| 27 |
# Set a different default tolerance |
| 28 |
use Test::Number::Delta within => 1e-5; |
| 29 |
delta_ok( 1.1e-5, 2e-5, 'values within 1e-5'); # ok |
| 30 |
|
| 31 |
# Set a relative tolerance |
| 32 |
use Test::Number::Delta relative => 1e-3; |
| 33 |
delta_ok( 1.01, 1.0099, 'values within 1.01e-3'); |
| 34 |
|
| 35 |
DESCRIPTION |
| 36 |
At some point or another, most programmers find they need to compare |
| 37 |
floating-point numbers for equality. The typical idiom is to test if the |
| 38 |
absolute value of the difference of the numbers is within a desired |
| 39 |
tolerance, usually called epsilon. This module provides such a function |
| 40 |
for use with Test::More. Usage is similar to other test functions |
| 41 |
described in Test::More. Semantically, the "delta_within" function |
| 42 |
replaces this kind of construct: |
| 43 |
|
| 44 |
ok ( abs($p - $q) < $epsilon, '$p is equal to $q' ) or |
| 45 |
diag "$p is not equal to $q to within $epsilon"; |
| 46 |
|
| 47 |
While there's nothing wrong with that construct, it's painful to type it |
| 48 |
repeatedly in a test script. This module does the same thing with a |
| 49 |
single function call. The "delta_ok" function is similar, but either |
| 50 |
uses a global default value for epsilon or else calculates a 'relative' |
| 51 |
epsilon on the fly so that epsilon is scaled automatically to the size |
| 52 |
of the arguments to "delta_ok". Both functions are exported |
| 53 |
automatically. |
| 54 |
|
| 55 |
Because checking floating-point equality is not always reliable, it is |
| 56 |
not possible to check the 'equal to' boundary of 'less than or equal to |
| 57 |
epsilon'. Therefore, Test::Number::Delta only compares if the absolute |
| 58 |
value of the difference is less than epsilon (for equality tests) or |
| 59 |
greater than epsilon (for inequality tests). |
| 60 |
|
| 61 |
USAGE |
| 62 |
use Test::Number::Delta; |
| 63 |
With no arguments, epsilon defaults to 1e-6. (An arbitrary choice on the |
| 64 |
author's part.) |
| 65 |
|
| 66 |
use Test::Number::Delta within => 1e-9; |
| 67 |
To specify a different default value for epsilon, provide a "within" |
| 68 |
parameter when importing the module. The value must be non-zero. |
| 69 |
|
| 70 |
use Test::Number::Delta relative => 1e-3; |
| 71 |
As an alternative to using a fixed value for epsilon, provide a |
| 72 |
"relative" parameter when importing the module. This signals that |
| 73 |
"delta_ok" should test equality with an epsilon that is scaled to the |
| 74 |
size of the arguments. Epsilon is calculated as the relative value times |
| 75 |
the absolute value of the argument with the greatest magnitude. |
| 76 |
Mathematically, for arguments 'x' and 'y': |
| 77 |
|
| 78 |
epsilon = relative * max( abs(x), abs(y) ) |
| 79 |
|
| 80 |
For example, a relative value of "0.01" would mean that the arguments |
| 81 |
are equal if they differ by less than 1% of the larger of the two |
| 82 |
values. A relative value of 1e-6 means that the arguments must differ by |
| 83 |
less than 1 millionth of the larger value. The relative value must be |
| 84 |
non-zero. |
| 85 |
|
| 86 |
Combining with a test plan |
| 87 |
use Test::Number::Delta 'no_plan'; |
| 88 |
|
| 89 |
# or |
| 90 |
|
| 91 |
use Test::Number::Delta within => 1e-9, tests => 1; |
| 92 |
|
| 93 |
If a test plan has not already been specified, the optional parameter |
| 94 |
for Test::Number::Delta may be followed with a test plan (see Test::More |
| 95 |
for details). If a parameter for Test::Number::Delta is given, it must |
| 96 |
come first. |
| 97 |
|
| 98 |
FUNCTIONS |
| 99 |
delta_within |
| 100 |
delta_within( $p, $q, $epsilon, '$p and $q are equal within $epsilon' ); |
| 101 |
delta_within( \@p, \@q, $epsilon, '@p and @q are equal within $epsilon' ); |
| 102 |
|
| 103 |
This function tests for equality within a given value of epsilon. The |
| 104 |
test is true if the absolute value of the difference between $p and $q |
| 105 |
is less than epsilon. If the test is true, it prints an "OK" statement |
| 106 |
for use in testing. If the test is not true, this function prints a |
| 107 |
failure report and diagnostic. Epsilon must be non-zero. |
| 108 |
|
| 109 |
The values to compare may be scalars or references to arrays. If the |
| 110 |
values are references to arrays, the comparison is done pairwise for |
| 111 |
each index value of the array. The pairwise comparison is recursive, so |
| 112 |
matrices may be compared as well. |
| 113 |
|
| 114 |
For example, this code sample compares two matrices: |
| 115 |
|
| 116 |
my @a = ( [ 3.14, 6.28 ], |
| 117 |
[ 1.41, 2.84 ] ); |
| 118 |
|
| 119 |
my @b = ( [ 3.14, 6.28 ], |
| 120 |
[ 1.42, 2.84 ] ); |
| 121 |
|
| 122 |
delta_within( \@a, \@b, 1e-6, 'compare @a and @b' ); |
| 123 |
|
| 124 |
The sample prints the following: |
| 125 |
|
| 126 |
not ok 1 - compare @a and @b |
| 127 |
# At [1][0]: 1.4100000 and 1.4200000 are not equal to within 0.000001 |
| 128 |
|
| 129 |
delta_ok |
| 130 |
delta_ok( $p, $q, '$p and $q are close enough to equal' ); |
| 131 |
delta_ok( \@p, \@q, '@p and @q are close enough to equal' ); |
| 132 |
|
| 133 |
This function tests for equality within a default epsilon value. See |
| 134 |
"USAGE" for details on changing the default. Otherwise, this function |
| 135 |
works the same as "delta_within". |
| 136 |
|
| 137 |
delta_not_within |
| 138 |
delta_not_within( $p, $q, '$p and $q are different' ); |
| 139 |
delta_not_within( \@p, \@q, $epsilon, '@p and @q are different' ); |
| 140 |
|
| 141 |
This test compares inequality in excess of a given value of epsilon. The |
| 142 |
test is true if the absolute value of the difference between $p and $q |
| 143 |
is greater than epsilon. For array or matrix comparisons, the test is |
| 144 |
true if *any* pair of values differs by more than epsilon. Otherwise, |
| 145 |
this function works the same as "delta_within". |
| 146 |
|
| 147 |
delta_not_ok |
| 148 |
delta_not_ok( $p, $q, '$p and $q are different' ); |
| 149 |
delta_not_ok( \@p, \@q, '@p and @q are different' ); |
| 150 |
|
| 151 |
This function tests for inequality in excess of a default epsilon value. |
| 152 |
See "USAGE" for details on changing the default. Otherwise, this |
| 153 |
function works the same as "delta_not_within". |
| 154 |
|
| 155 |
SEE ALSO |
| 156 |
* Number::Tolerant |
| 157 |
|
| 158 |
* Test::Deep::NumberTolerant |
| 159 |
|
| 160 |
SUPPORT |
| 161 |
Bugs / Feature Requests |
| 162 |
Please report any bugs or feature requests through the issue tracker at |
| 163 |
<https://github.com/dagolden/Test-Number-Delta/issues>. You will be |
| 164 |
notified automatically of any progress on your issue. |
| 165 |
|
| 166 |
Source Code |
| 167 |
This is open source software. The code repository is available for |
| 168 |
public review and contribution under the terms of the license. |
| 169 |
|
| 170 |
<https://github.com/dagolden/Test-Number-Delta> |
| 171 |
|
| 172 |
git clone https://github.com/dagolden/Test-Number-Delta.git |
| 173 |
|
| 174 |
AUTHOR |
| 175 |
David Golden <[email protected]> |
| 176 |
|
| 177 |
COPYRIGHT AND LICENSE |
| 178 |
This software is Copyright (c) 2014 by David Golden. |
| 179 |
|
| 180 |
This is free software, licensed under: |
| 181 |
|
| 182 |
The Apache License, Version 2.0, January 2004 |
| 183 |
|