NAME

Number::Tolerant -- tolerance ranges for inexact numbers

VERSION

$Id$

SYNOPSIS

use Number::Tolerant;

my $range  = tolerance(10 => to => 12);
my $random = 10 + rand(2);

die "I shouldn't die" unless $random == $range;

print "This line will always print.\n";

DESCRIPTION

Number::Tolerant creates a number-like object whose value refers to a range of possible values, each equally acceptable. It overloads comparison operations to reflect this.

I use this module to simplify the comparison of measurement results to specified tolerances.

reject $product unless $measurement == $specification;

METHODS

Instantiation

Number::Tolerance->new( ... )

tolerance( ... )

There is a new method on the Number::Tolerant class, but it also exports a simple function, tolerance, which will return an object of the Number::Tolerant class. Both use the same syntax:

my $range = tolerance( $x => $method => $y);

The meaning of $x and $y are dependant on the value of $method, which describes the nature of the tolerance. Tolerances can be defined in five ways, at present:

 method              range
-------------------+---------------
 plus_or_minus     | x ± y
 plus_or_minus_pct | x ± (y% of x)
 or_more           | x to Inf
 or_less           | x to -Inf
 to                | x to y
 infinite          | -Inf to Inf

For or_less and or_more, $y is ignored if passed. For infinite, neither $x nor $y is used; "infinite" should be the sole argument.

from_string($stringification)

A new tolerance can be instantiated from the stringification of an old tolerance. For example:

my $range = Number::Tolerant->from_string("10 to 12");

die "Everything's OK!" if 11 == $range; # program dies of joy

This will not yet parse stringified unions, but that will be implemented in the future. (I just don't need it yet.)

Overloading

Tolerances overload a few operations, mostly comparisons.

numification

Tolerances with finite ranges numify to their center values. Tolerances with infinite ranges numify to their fixed end.

stringification

A tolerance stringifies to a short description of itself.

infinite - "any number"
to       - "x to y"
or_more  - "x or more"
or_less  - "x or less"
plus_or_minus     - "x +/- y"
plus_or_minus_pct - "x +/- y%"

equality

A number is equal to a tolerance if it is neither less than nor greater than it. (See below).

comparison

A number is greater than a tolerance if it is greater than its maximum value.

A number is less than a tolerance if it is less than its minimum value.

No number is greater than an "or_more" tolerance or less than an "or_less" tolerance.

"...or equal to" comparisons include the min/max values in the permissible range, as common sense suggests.

tolerance intersection

A tolerance & a tolerance or number is the intersection of the two ranges. Intersections allow you to quickly narrow down a set of tolerances to the most stringent intersection of values.

tolerance(5 => to => 6) & tolerance(5.5 => to => 6.5);
# this yields: tolerance(5.5 => to => 6)

If the given values have no intersection, () is returned.

An intersection with a normal number will yield that number, if it is within the tolerance.

tolerance union

A tolerance | a tolerance or number is the union of the two. Unions allow multiple tolerances, whether they intersect or not, to be treated as one. See Number::Tolerant::Union for more information.

TODO

Extend from_string to cover unions.

Allow translation into forms not originally used:

$range = tolerance(9 => to => 17); 
$range->convert_to('plus_minus');
$range->stringify_as('plus_minus_pct');

SEE ALSO

The module Number::Range provides another way to deal with ranges of numbers. The major differences are: N::R is set-like, not range-like; N::R does not overload any operators. Number::Tolerant will not (like N::R) attempt to parse a textual range specification like "1..2,5,7..10"

The Number::Range code:

$range = Number::Range->new("10..15","20..25");

Is equivalent to the Number::Tolerant code:

$range = Number::Tolerant::Union->new(10..15,20..25);

...while the following code expresses an actual range:

$range = tolerance(10 => to => 15) | tolerance(20 => to => 25);

AUTHOR

Ricardo SIGNES, <rjbs@cpan.org>

COPYRIGHT

(C) 2004, Ricardo SIGNES. Number::Tolerant is available under the same terms as Perl itself.

cpanm Number::Tolerant

perl -MCPAN -e shell
install Number::Tolerant