array::intspan(3)
NAME
Array::IntSpan - a Module for handling arrays using
IntSpan techniques
SYNOPSIS
use Array::IntSpan;
my $foo = Array::IntSpan->new([0, 59, 'F'], [60, 69,
'D'], [80, 89, 'B']);
print "A score of 84% results in a
".$foo->lookup(84).".0;
unless (defined($foo->lookup(70))) {
print "The grade for the score 70% is currently undefined.0;
}
$foo->set_range(70, 79, 'C');
print "A score of 75% now results in a
".$foo->lookup(75).".0;
$foo->set_range(0, 59, undef);
unless (defined($foo->lookup(40))) {
print "The grade for the score 40% is now undefined.0;
}
$foo->set_range(87, 89, 'B+');
$foo->set_range(85, 100, 'A');
$foo->set_range(100, 1_000_000, 'A+');
DESCRIPTION
"Array::IntSpan" brings the speed advantages of
"Set::IntSpan" (written by Steven McDougall) to arrays.
Uses include manipulating grades, routing tables, or any
other situation where you have mutually exclusive ranges
of integers that map to given values.
"Array::IntSpan::IP" is also provided with the distribu
tion. It lets you use IP addresses in any of three forms
(dotted decimal, network string, and integer) for the
indices into the array. See the POD for that module for
more information.
Installation instructions
Standard "Make::Maker" approach or just copy
"Array/IntSpan.pm" into "site/lib/Array/IntSpan.pm" and
"Array/IntSpan/IP.pm" into "site/lib/Array/IntSpan/IP.pm".
METHODS
new
The "new" method takes an optional list of array elements.
The elements should be in the form "[start_index,
end_index, value]". They should be in sorted order and
there should be no overlaps. The internal method
"_check_structure" will be called to verify the data is
correct. If you wish to avoid the performance penalties
of checking the structure, you can use "Data::Dumper" to
dump an object and use that code to reconstitute it.
set_range
This method takes three parameters - the "start_index",
the "end_index", and the "value". If you wish to erase a
range, specify "undef" for the "value". It properly deals
with overlapping ranges and will replace existing data as
appropriate. If the new range lies after the last exist
ing range, the method will execute in O(1) time. If the
new range lies within the existing ranges, the method exe
cutes in O(n) time, where n is the number of ranges. The
code is not completely optimized and will make up to three
calls to "splice" if the new range intersects with exist
ing ranges. It does not consolidate contiguous ranges
that have the same "value".
If you have a large number of inserts to do, it would be
beneficial to sort them first. Sorting is O(n lg(n)), and
since appending is O(1), that will be considerably faster
than the O(n^2) time for inserting n unsorted elements.
The method returns 0 if there were no overlapping ranges
and 1 if there were.
lookup
This method takes as a single parameter the "index" to
look up. If there is an appropriate range, the method
will return the associated value. Otherwise, it returns
"undef".
AUTHOR
- Toby Everett, teverett@alascom.att.com