NAME

Number::Interval - Implement a representation of a numeric interval

SYNOPSIS

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";

DESCRIPTION

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.

METHODS

Constructor

new

Create a new object. Can be populated when supplied with keys Max and Min.

$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

Copy the contents of the current object into a new object and return it.

$new = $r->copy;

Accessors

max

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.

min

Return (or set) the lower end of the interval.

$min = $r->min;
$r->min( undef );

undef indicates that the interval has no lower bound.

inc_max

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

inc_min

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

pos_def

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.

minmax

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.

minmax_hash

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.

min or max can be ommitted. The returned hash contains min and max keys but only if they have defined values.

sizeof

Returns the size of the interval.

$sizeof = $r->sizeof;

If either of the lower or upper ends are unbounded, then undef will be returned.

General

stringify

Convert the object into a string representation for display. Usually called via a stringify overload.

isinverted

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.

isbound

Returns true if the interval is bound by an upper and lower limit. An inverted interval would be bounded but inverted.

equate

Compare with another Interval object. Returns true if they are the same. False otherwise.

notequal

Inverse of equate. Used by the tied interface to implement !=.

$i1 != $i2

contains

Determine whether a supplied value is within the defined intervals.

$is = $i->contains( $value );

If both intervals are undefined, always returns true.

If the min == max, returns true if the supplied value is that value, regardless of IncMin and IncMax setttings.

If the interval is positive definite, always returns false if the supplied value is negative.

intersection

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.

NOTES

The default interval is not inclusive of the bounds.

COPYRIGHT

Copyright (C) 2009 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

AUTHOR

Tim Jenness <tjenness@cpan.org>.