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                  # this may change in the future
      Tie::Hash
      Time::HiRes           # for test.pl

  Installation

    Installation is pretty standard:

      perl Makefile.PL
      make
      make test
      make install

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.

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

    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 DELETE, 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.