NAME
    Tie::RangeHash - Implements "range hashes" in Perl

REQUIREMENTS
    `Tie::RangeHash' is written for Perl 5.005_62 or 5.6.0 and tested on the
    latter. It should work in Perl 5.005, although I have not tested it.

    It uses the following modules:

      Carp
      Tie::Hash

    The test suite will use `Time::HiRes' if it is available.

  Installation

    Installation is pretty standard:

      perl Makefile.PL
      make
      make test
      make install

HISTORY
    Changes since Tie::RangeHash v0.30:

    0.40 11 Dec 2000
	- fixed bug where EXISTS method missed $hash{'low,high'} = undef
	- some minor optimizations
	- corrected outdated descriptions in the comments
	- added DELETE method
	- _find_node() become _find_node_parent for use w/DELETE method
	- fixed bug with adding undef node
	- warnings are now disabled unless Perl is run with the -w flag
	- test.pl will only use Time::HiRes if it is available
	- other misc. changes to test.pl

SYNOPSIS
      use Tie::RangeHash;

      tie %hash, Tie::RangeHash;

      $hash{'A,C'} = 1;
      $hash{'D,F'} = 2;
      $hash{'G,K'} = 3;

      $hash{'E'};           # returns '2'
      $hash{'BB'};          # returns '1'

      $hash{'KL'};          # returns nothing ('undef')

DESCRIPTION
    This module allows hashes to associate a value with a *range* of keys
    rather than a single key.

    For example, you could pass date ranges to the hash and then query it
    with a specific date, like so:

      $cost{'1999-12-15,2000-01-14'} = 150;
      $cost{'2000-01-15,2000-02-14'} = 103;
      $cost{'2000-02-15,2000-03-14'} =  97;

    and then query the cost on a specific date:

      $this_cost = $cost{'2000-02-08'};

    Numeric key ranges can also be used:

      tie %hash, 'Tie::RangeHash', {
        Type => Tie::RangeHash::TYPE_NUMBER
      };

      $hash{'1.4,1.8'}      = 'Jim';
      $hash{'1.0,1.399999'} = 'Ned';
      $hash{'1.800001,2.0'} = 'Boo';

    If string or numeric comparisons are not appropriate for the keys you
    need, a custom comparison routine can be specified:

      sub reverse_compare {
        my ($A, $B) = @_;
        return ($B cmp $A);
      }

      tie %hash, 'Tie::RangeHash', {
        Comparison => \&reverse_compare
      };

    The comparison routine should work the same as custom sort subroutines
    do (A < B returns -1, A=B returns 0, A > B returns 1). Your keys must
    also be representable as a string (a future version of this module may
    add filters to overcome that limitation).

    If you need to define your own separator, you can do so:

      tie %hash, 'Tie::RangeHash', {
        Separator => '..'
       };

    or

      tie %hash, 'Tie::RangeHash', {
        Separator => qr/\s/
       };

    Note that if you define it as a regular expression, warnings and errors
    will use the default comma ',' separator (since there is no way to
    "reverse" a regular expression).

    Duplicate and overlapping ranges are not supported. Once a range is
    defined, it exists for the lifetime of the hash. (Future versions may
    allow you to change this behavior.)

    Warnings are now disabled by default unless you run Perl with the -W
    flag. In theory, you should also be able to say

      use warnings 'Tie::RangeHash';

    but this does not always seem to work. (Apparently something is broken
    with warnings.)

    Internally, the hash is actually a binary tree. Values are retrieved by
    searching the tree for nodes that where the key is within range.

CAVEATS
    The binary-tree code is spontaneously written and has a very simple
    tree-banacing scheme. (It needs some kind of scheme since sorted data
    will produce a very lopsided tree which is no more efficient than an
    array.) It appears to work, but has not been fully tested.

    A future version of this module may use an improved binary-tree
    algorithm. Or it may use something else.

    This module is incomplete... It needs the FIRSTKEY, NEXTKEY, and (maybe)
    DESTROY methods.

AUTHOR
    Robert Rothenberg <rrwo@cpan.org>

LICENSE
    Copyright (c) 2000 Robert Rothenberg. All rights reserved. This program
    is free software; you can redistribute it and/or modify it under the
    same terms as Perl itself.