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();
  $r = new Number::Interval( Max => 5 );

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.

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.

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.

contains

Determine whether a supplied value is within the defined intervals.

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

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.

COPYRIGHT

Copyright (C) 2002-2004 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>.