1Test::Number::Delta(3)User Contributed Perl DocumentationTest::Number::Delta(3)
2
6 Test::Number::Delta - Compare the difference between numbers against a
7 given tolerance
8
10 # Import test functions
11 use Test::Number::Delta;
12 # Equality test with default tolerance
14 delta_ok( 1e-5, 2e-5, 'values within 1e-6');
15 # Inequality test with default tolerance
17 delta_not_ok( 1e-5, 2e-5, 'values not within 1e-6');
18 # Provide specific tolerance
20 delta_within( 1e-3, 2e-3, 1e-4, 'values within 1e-4');
21 delta_not_within( 1e-3, 2e-3, 1e-4, 'values not within 1e-4');
22 # Compare arrays or matrices
24 @a = ( 3.14, 1.41 );
25 @b = ( 3.15, 1.41 );
26 delta_ok( \@a, \@b, 'compare @a and @b' );
27 # Set a different default tolerance
29 use Test::Number::Delta within => 1e-5;
30 delta_ok( 1.1e-5, 2e-5, 'values within 1e-5'); # ok
31 # Set a relative tolerance
33 use Test::Number::Delta relative => 1e-3;
34 delta_ok( 1.01, 1.0099, 'values within 1.01e-3');
35
37 At some point or another, most programmers find they need to compare
38 floating-point numbers for equality. The typical idiom is to test if
39 the absolute value of the difference of the numbers is within a desired
40 tolerance, usually called epsilon. This module provides such a
41 function for use with Test::Harness. Usage is similar to other test
42 functions described in Test::More. Semantically, the "delta_within"
43 function replaces this kind of construct:
44 ok ( abs($p - $q) < $epsilon, '$p is equal to $q' ) or
46 diag "$p is not equal to $q to within $epsilon";
47 While there's nothing wrong with that construct, it's painful to type
49 it repeatedly in a test script. This module does the same thing with a
50 single function call. The "delta_ok" function is similar, but either
51 uses a global default value for epsilon or else calculates a 'relative'
52 epsilon on the fly so that epsilon is scaled automatically to the size
53 of the arguments to "delta_ok". Both functions are exported
54 automatically.
55 Because checking floating-point equality is not always reliable, it is
57 not possible to check the 'equal to' boundary of 'less than or equal to
58 epsilon'. Therefore, Test::Number::Delta only compares if the absolute
59 value of the difference is less than epsilon (for equality tests) or
60 greater than epsilon (for inequality tests).
61
63 use Test::Number::Delta;
64 With no arguments, epsilon defaults to 1e-6. (An arbitrary choice on
65 the author's part.)
66 use Test::Number::Delta within => 1e-9;
68 To specify a different default value for epsilon, provide a "within"
69 parameter when importing the module. The value must be non-zero.
70 use Test::Number::Delta relative => 1e-3;
72 As an alternative to using a fixed value for epsilon, provide a
73 "relative" parameter when importing the module. This signals that
74 "delta_ok" should test equality with an epsilon that is scaled to the
75 size of the arguments. Epsilon is calculated as the relative value
76 times the absolute value of the argument with the greatest magnitude.
77 Mathematically, for arguments 'x' and 'y':
78 epsilon = relative * max( abs(x), abs(y) )
80 For example, a relative value of "0.01" would mean that the arguments
82 are equal if they differ by less than 1% of the larger of the two
83 values. A relative value of 1e-6 means that the arguments must differ
84 by less than 1 millionth of the larger value. The relative value must
85 be non-zero.
86 Combining with a test plan
88 use Test::Number::Delta 'no_plan';
89 # or
91 use Test::Number::Delta within => 1e-9, tests => 1;
93 If a test plan has not already been specified, the optional parameter
95 for Test::Number::Delta may be followed with a test plan (see
96 Test::More for details). If a parameter for Test::Number::Delta is
97 given, it must come first.
98
100 delta_within
101 delta_within( $p, $q, $epsilon, '$p and $q are equal within $epsilon' );
102 delta_within( \@p, \@q, $epsilon, '@p and @q are equal within $epsilon' );
103 This function tests for equality within a given value of epsilon. The
105 test is true if the absolute value of the difference between $p and $q
106 is less than epsilon. If the test is true, it prints an "OK" statement
107 for use in testing. If the test is not true, this function prints a
108 failure report and diagnostic. Epsilon must be non-zero.
109 The values to compare may be scalars or references to arrays. If the
111 values are references to arrays, the comparison is done pairwise for
112 each index value of the array. The pairwise comparison is recursive,
113 so matrices may be compared as well.
114 For example, this code sample compares two matrices:
116 my @a = ( [ 3.14, 6.28 ],
118 [ 1.41, 2.84 ] );
119 my @b = ( [ 3.14, 6.28 ],
121 [ 1.42, 2.84 ] );
122 delta_within( \@a, \@b, 1e-6, 'compare @a and @b' );
124 The sample prints the following:
126 not ok 1 - compare @a and @b
128 # At [1][0]: 1.4100000 and 1.4200000 are not equal to within 0.000001
129 delta_ok
131 delta_ok( $p, $q, '$p and $q are close enough to equal' );
132 delta_ok( \@p, \@q, '@p and @q are close enough to equal' );
133 This function tests for equality within a default epsilon value. See
135 "USAGE" for details on changing the default. Otherwise, this function
136 works the same as "delta_within".
137 delta_not_within
139 delta_not_within( $p, $q, '$p and $q are different' );
140 delta_not_within( \@p, \@q, $epsilon, '@p and @q are different' );
141 This test compares inequality in excess of a given value of epsilon.
143 The test is true if the absolute value of the difference between $p and
144 $q is greater than epsilon. For array or matrix comparisons, the test
145 is true if any pair of values differs by more than epsilon. Otherwise,
146 this function works the same as "delta_within".
147 delta_not_ok
149 delta_not_ok( $p, $q, '$p and $q are different' );
150 delta_not_ok( \@p, \@q, '@p and @q are different' );
151 This function tests for inequality in excess of a default epsilon
153 value. See "USAGE" for details on changing the default. Otherwise,
154 this function works the same as "delta_not_within".
155
157 Test::More, Test::Harness, Test::Builder
158
160 Please report any bugs or feature using the CPAN Request Tracker. Bugs
161 can be submitted by email to "bug-Test-Number-Delta@rt.cpan.org" or
162 through the web interface at
163 http://rt.cpan.org/Dist/Display.html?Queue=Test-Number-Delta
164 <http://rt.cpan.org/Dist/Display.html?Queue=Test-Number-Delta>
165 When submitting a bug or request, please include a test-file or a patch
167 to an existing test-file that illustrates the bug or desired feature.
168
170 David A Golden (DAGOLDEN)
171 dagolden@cpan.org
173 <http://dagolden.com/>
175
177 Copyright (c) 2005, 2006 by David A. Golden
178 This program is free software; you can redistribute it and/or modify it
180 under the same terms as Perl itself.
181 The full text of the license can be found in the LICENSE file included
183 with this module.
184
186 BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
187 FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
188 WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
189 PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
190 EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
191 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
192 ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
193 YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
194 NECESSARY SERVICING, REPAIR, OR CORRECTION.
195 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
197 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
198 REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
199 TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
200 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
201 SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
202 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
203 FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
204 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
205 DAMAGES.
206perl v5.12.0 2010-05-06 Test::Number::Delta(3)