1 files changed, 126 insertions, 1 deletions
diff --git a/lib/Data/MultiValued/Ranges.pm b/lib/Data/MultiValued/Ranges.pm
index 9c69626..296ae76 100644
--- a/lib/Data/MultiValued/Ranges.pm
+++ b/lib/Data/MultiValued/Ranges.pm
@@ -1,4 +1,10 @@
 package Data::MultiValued::Ranges;
+BEGIN {
+  $Data::MultiValued::Ranges::VERSION = '0.0.1';
+}
+BEGIN {
+  $Data::MultiValued::Ranges::DIST = 'Data-MultiValued';
+}
 use Moose;
 use MooseX::Params::Validate;
 use Moose::Util::TypeConstraints;
@@ -6,7 +12,8 @@ use MooseX::Types::Moose qw(Num Str Undef Any);
 use Data::MultiValued::Exceptions;
 use Data::MultiValued::RangeContainer;
 
-# ABSTRACT: Handle values with tags and validity ranges
+# ABSTRACT: Handle values with validity ranges
+
 
 has _storage => (
     is => 'rw',
@@ -32,6 +39,7 @@ sub _as_hash {
     return {_storage=>\%ret};
 }
 
+
 sub set {
     my ($self,%args) = validated_hash(
         \@_,
@@ -44,6 +52,7 @@ sub set {
          ->{value} = $args{value};
 }
 
+
 sub get {
     my ($self,%args) = validated_hash(
         \@_,
@@ -54,6 +63,7 @@ sub get {
          ->{value};
 }
 
+
 sub clear {
     my ($self,%args) = validated_hash(
         \@_,
@@ -66,3 +76,118 @@ sub clear {
 
 
 1;
+
+__END__
+=pod
+
+=head1 NAME
+
+Data::MultiValued::Ranges - Handle values with validity ranges
+
+=head1 VERSION
+
+version 0.0.1
+
+=head1 SYNOPSIS
+
+  use Data::MultiValued::Ranges;
+
+  my $obj = Data::MultiValued::Ranges->new();
+  $obj->set({
+    from => 10,
+    to => 20,
+    value => 'foo',
+  });
+  say $obj->get({at => 15}); # prints 'foo'
+  say $obj->get({at => 35}); # dies
+
+=head1 METHODS
+
+=head2 C<set>
+
+  $obj->set({ from => $min, to => $max, value => $the_value });
+
+Stores the given value for the given range. Does not throw exceptions.
+
+The range is defined as C<< Num $x : $min <= $x < $max >>. A C<< from
+=> undef >> means "from -Inf", and a C<< to => undef >> means "to
++Inf". Not passing in C<from> or C<to> is equivalent to passing
+C<undef>.
+
+If the given range intersects existing ranges, these are spliced to
+avoid overlaps. In other words:
+
+  $obj->set({
+    from => 10,
+    to => 20,
+    value => 'foo',
+  });
+  $obj->set({
+    from => 15,
+    to => 25,
+    value => 'bar',
+  });
+  say $obj->get({at => 12}); # prints 'foo'
+  say $obj->get({at => 15}); # prints 'bar'
+  say $obj->get({at => 25}); # dies
+
+No cloning is done: if you pass in a reference, the reference is
+just stored.
+
+=head2 C<get>
+
+  my $value = $obj->get({ at => $point });
+
+Retrieves the value for the given point. Throws a
+L<Data::MultiValued::Exceptions::RangeNotFound> exception if no ranges
+exist in this object that include the point (remember that a range
+does not include its C<to> point).
+
+A C<< at => undef >> means "at -Inf". Not passing in C<at> is
+equivalent to passing C<undef>.
+
+No cloning is done: if a reference was stored, you get it back
+untouched.
+
+=head2 C<clear>
+
+  $obj->clear({ from => $min, to => $max });
+
+Deletes all values for the given range. Does not throw exceptions.
+
+A C<< from => undef >> means "from -Inf", and a C<< to => undef >>
+means "to +Inf". Not passing in C<from> or C<to> is equivalent to
+passing C<undef>. Thus, C<< $obj->clear() >> clears everything.
+
+If the given range intersects existing ranges, these are spliced. In
+other words:
+
+  $obj->set({
+    from => 10,
+    to => 20,
+    value => 'foo',
+  });
+  $obj->clear({
+    from => 15,
+    to => 25,
+  });
+  say $obj->get({at => 12}); # prints 'foo'
+  say $obj->get({at => 15}); # dies
+
+=head1 SEE ALSO
+
+L<Data::MultiValued::RangeContainer>, L<Data::MultiValued::Exceptions>
+
+=head1 AUTHOR
+
+Gianni Ceccarelli <dakkar@thenautilus.net>
+
+=head1 COPYRIGHT AND LICENSE
+
+This software is copyright (c) 2011 by Net-a-porter.com.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+=cut
+