### RB.pod --- Document Tree::Range::RB  -*- POD -*-

### Copyright (C) 2013 Ivan Shmakov

## Permission to copy this software, to modify it, to redistribute it,
## to distribute modified versions, and to use it for any purpose is
## granted, subject to the following restrictions and understandings.

## 1.  Any copy made of this software must include this copyright notice
## in full.

## 2.  I have made no warranty or representation that the operation of
## this software will be error-free, and I am under no obligation to
## provide any services, by way of maintenance, update, or otherwise.

## 3.  In conjunction with products arising from the use of this
## material, there shall be no use of my name in any advertising,
## promotional, or sales literature without prior written consent in
## each case.

### Code:

=head1 NAME

Tree::Range::RB E<ndash> range tree implemented on top of
L<Tree::RB>

=head1 SYNOPSIS

    require Tree::Range::RB;

    sub ncmp { $_[0] <=> $_[1]; }
    my $nrt
        = Tree::Range::RB->new ({ "cmp" => \&ncmp });
    $nrt->range_set (100, 200, "foo");
    $nrt->range_set (200, 300, "bar");
    $nrt->range_set (150, 250, "baz");
    $nrt->range_set (400, 500, "qux");
    my $r100 = $nrt->get_range (100);
    ## now $r100 is  "foo"
    my @r200 = $nrt->get_range (200);
    ## now @r200 is ("baz", 150, 250)
    my @r300 = $nrt->get_range (300);
    ## now @r300 is (undef, 300, 400)

    sub cmp { $_[0] cmp $_[1]; }
    my $srt
        = Tree::Range::RB->new ({ "cmp" => \&cmp });
    $srt->range_set (qw (apple  peach   1));
    $srt->range_set (qw (banana cherry  2));
    my @rmango = $srt->get_range ("mango");
    ## now @rmango is (1, "cherry", "peach")

=head1 DESCRIPTION

This class implements a I<range tree>
(as described in L<Tree::Range::base>)
on top of the L<Tree::RB> red-black tree implementation.
It inherits from L<Tree::Range::base>.

=head1 INTERFACE

=over 4

=item C<< my $rat = Tree::Range::RB->new (\%options); >>

Create and return a new range tree object.

Available options are as follows.

=over 4

=item C<cmp>

Specifies the I<comparison> function for the range tree.
Possible values include
C<< sub { $_[0] cmp $_[1]; } >>
and C<< sub { $_[0] <=> $_[1]; } >>.

If not given, the C<cmp>
string comparison
operator will be used.

=item C<equal-p>

Specifies the optional I<value equality predicate.>

See the C<range_set> method description
in L<Tree::Range::base>
for more information.

=item C<leftmost>

Specifies the value the keys lower than the lowest bound are
mapped to.  If left unspecified, C<undef> will be used.

=back

=back

The following methods are inherited from L<Tree::Range::base>.
See the L<Tree::Range::base> documentation for more information.

=over 4

=item C<< my $v = $rat->get_range ($key) >>

=item C<< my ($v, $lower, $upper) = $rat->get_range ($key) >>

Return the value associated with the range C<$key> lies within.

In the list context, return also the rangeZ<>E<rsquo>s lower and
upper bounds.

=item C<< $rat->range_set ($lower, $upper, $value); >>

Associate the keys lying between C<$lower> (inclusive) and
C<$upper> (exclusive) with C<$value>.

Raise an exception (S<i. e.,> I<die.>) unless the upper bound is
greater than the lower one, as determined by the I<comparison>
function.

All the overlapping range associations, if any, are overwritten.

=back

The following methods are implemented in order to inherit from
L<Tree::Range::base>.
See the L<Tree::Range::base> documentation for more information.

=over 4

=item C<< my $cmp_fn      = $rat->cmp_fn (); >>

=item C<< my $equal_p_fn  = $rat->value_equal_p_fn (); >>

=item C<< my $leftmost    = $rat->leftmost_value (); >>

Return
the I<comparison> function,
the I<value equality predicate,>
or the value the keys lower than the lowest bound are mapped to,
respectively.

These values are the same as specified at the object creation
time, or the respective defaults.

=item C<< $rat->put ($key, $value) >>

=item C<< my $node = $rat->lookup_leq ($key) >>

=item C<< my $node = $rat->lookup_geq ($key) >>

=item C<< my $okay = $put->delete ($key) >>

Associate a (key, value) pair with the value of C<$key>,
perform a less-than-or-equal or greater-than-or-equal lookup
(returning a I<node> object),
or remove any such association, respectively.

The C<delete> method will return a true value upon
successful completion.

These methods are mapped to the
C<put>, C<lookup> and C<delete>
methods
of the underlying L<Tree::RB> object.

=back

=head1 SEE ALSO

L<Tree::Interval>,
L<Tree::RB>,
L<Tree::Range::base>

L<Scalar::Util>

=head1 AUTHOR

Ivan Shmakov <oneingray@gmail.com>

This library is free software; you can redistribute it and/or
modify it under the terms of the 3-clause BSD license, as
included within the code.

=cut

### Emacs trailer
## Local variables:
## coding: us-ascii
## fill-column: 64
## indent-tabs-mode: nil
## ispell-local-dictionary: "american"
## End:
### RB.pod ends here
