Instantiation

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 = Number::Tolerant->new( $x => $method => $y);

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

The meaning of $x and $y are dependent 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
  more_than         | x to Inf, not x
  less_than         | x to -Inf, not x
  to                | x to y
  infinite          | -Inf to Inf
  offset            | (x + y1) to (x + y2)

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. The first two arguments can be reversed for "more_than" and "less_than", to be more English-like.

Offset tolerances are slightly unusual. Here is an example:

  my $offset_tolerance = tolerance(10 => offset => (-3, 5));
  # stringifies to: 10 (-3 +5)

An offset is very much like a "plus_or_minus" tolerance, but its center value is not necessarily the midpoint between its extremes. This is significant for comparisons and numifications of the tolerance. Given the following two tolerances:

  my $pm_dice = tolerance(10.5 => plus_or_minus => 7.5);
  my $os_dice = tolerance(11 => offset => (-8, 7));

The first will sort as numerically less than the second.

If the given arguments can't be formed into a tolerance, an exception will be raised.

from_string

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.)

If a string can't be parsed, an exception is raised.

stringify_as

  my $string = $tolerance->stringify_as($type);

This method does nothing! Someday, it will stringify the given tolerance as a different type, if possible. "10 +/- 1" will "stringify_as('plus_or_minus_pct')" to "10 +/- 10%" for example.

numify

  my $n = $tolerance->numify;

This returns the numeric form of a tolerance. If a tolerance has both a minimum and a maximum, and they are the same, then that is the numification. Otherwise, numify returns undef.

Overloading

boolean

Tolerances are always true.

numify

Most tolerances numify to undef; see "numify".

stringify

A tolerance stringifies to a short description of itself, generally something like "m < x < n"

 infinite  - "any number"
 to        - "m <= x <= n"
 or_more   - "m <= x"
 or_less   - "x <= n"
 more_than - "m < x"
 less_than - "x < n"
 offset    - "x (-y1 +y2)"
 constant  - "x"
 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).

smart match

Same as equality.

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.

" enable_plugin "

  Number::Tolerant->enable_plugin($class_name);

This method enables the named class, so that attempts to create new tolerances will check against this class. Classes are checked against "validate_plugin" before being enabled. An exception is thrown if the class does not appear to provide the Number::Tolerant::Type interface.

" disable_plugin "

  Number::Tolerant->disable_plugin($class_name);

This method will disable the named class, so that future attempts to create new tolerances will not check against this class.

" validate_plugin "

  Number::Tolerant->validate_plugin($class_name);

This method checks (naively) that the given class provides the interface defined in Number::Tolerant::Type. If it does not, an exception is thrown.