Number::Interval - Implement a representation of a numeric interval
use Number::Interval; $i = new Number::Interval( Min => -4, Max => 20); $i = new Number::Interval( Min => 0 ); $is = $i->contains( $value ); $status = $i->intersection( $i2 ); print "$i";
Simple class to implement a closed or open interval. Can be used to compare different intervals, determine set membership, calculate intersections and provide default stringification methods.
Intervals can be bound or unbound. If
max is less than
min the interval is inverted.
Create a new object. Can be populated when supplied with keys
$r = new Number::Interval();
This interval is Inf.
$r = new Number::Interval( Max => 5 );
This interval is > 5.
$r = new Number::Interval( Max => 5, Min => 22 );
This interval is > 22 and < 5.
By default the interval does not include the bounds themselves. They can be included by using the IncMax and IncMin keys.
$r = new Number::Interval( Max => 5, IncMax => 1 );
The above interval is >=5
Positive-definite intervals allow the stringification to ignore the lower bound if it is 0 (even if set explicitly).
$r = new Number::Interval( Max => 5, IncMax => 1, Min => 0, PosDef => 1);
The keys are case-insensitive.
Copy the contents of the current object into a new object and return it.
$new = $r->copy;
Return (or set) the upper end of the interval.
$max = $r->max; $r->max(22.0);
undef indicates that the interval has no upper bound.
Return (or set) the lower end of the interval.
$min = $r->min; $r->min( undef );
undef indicates that the interval has no lower bound.
Return (or set) the boolean indicating whether the maximum bound of the interval should be included in the bound definition. If true, the bounds will be >= max.
$inc = $r->inc_max; $r->inc_max( 1 );
Default is false (not included).
Return (or set) the boolean indicating whether the minimum bound of the interval should be included in the bound definition. If true, the bounds will be <= min.
$inc = $r->inc_min; $r->inc_min( 1 );
Default is false (not included).
Indicate that the interval is positive definite. This helps the stringification method to determine whether the lower bound should be included
$r->pos_def( 1 );
If set to true, automatically sets the lower bound to 0 if the lower bound is not explicitly defined.
Return (or set) the minimum and maximum values of the interval as an array.
$r->minmax( 1, 5 ); @interval = $r->minmax;
Returns reference to an array in a scalar context.
Return (or set) the minimum and maximum values of the interval as an hash.
$r->minmax_hash( min => 1, max => 5 ); %interval = $r->minmax_hash;
Returns reference to an hash in a scalar context.
max can be ommitted. The returned hash contains
max keys but only if they have defined values.
Returns the size of the interval.
$sizeof = $r->sizeof;
If either of the lower or upper ends are unbounded, then
undef will be returned.
Convert the object into a string representation for display. Usually called via a stringify overload.
Determine whether the interval is inverted. This is true if both max and min are supplied but max is less than min. For all other cases (including unbound single-sided intervals) this will return false.
Returns true if the interval is bound by an upper and lower limit. An inverted interval would be bounded but inverted.
Compare with another Interval object. Returns true if they are the same. False otherwise.
equate. Used by the tied interface to implement !=.
$i1 != $i2
Determine whether a supplied value is within the defined intervals.
$is = $i->contains( $value );
If both intervals are undefined, always returns true.
Note: If the min == max, returns true if the supplied value is that value, but only if either IncMin or IncMax is true. This is a change in version 0.06: previously this method returned true in this case regardless of IncMin and IncMax setttings.
If the interval is positive definite, always returns false if the supplied value is negative.
Given another Interval object, modify the existing interval to include the additional constraints. For example, if the current object has a interval of -3 to 10, and it is merged with an external object that has a interval of 0 to 20 then the interval of the current object will be converted to 0 to 10 since that is consistent with both intervals.
$status = $interval->intersection( $newinterval );
Returns true if the intersection was successful. If the intervals are incompatible (no intersection) or if no object was supplied returns false and the object is not modified.
Intersections of an inverted interval with a non-inverted interval can, in some circumstances, result in an intersection covering two distinct bound intervals. This class can not yet support multiple intervals (that would make the intersection method even more of a nightmare) so the routine dies if such a situation arises.
The default interval is not inclusive of the bounds.
Copyright (C) 2009-2011 Science and Technology Facilities Council. Copyright (C) 2002-2005 Particle Physics and Astronomy Research Council. All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307, USA
Tim Jenness <email@example.com>.