From 5dbdfc53752cd050b171f416ea3625b18e4018b8 Mon Sep 17 00:00:00 2001
From: Gianni Ceccarelli <dakkar@thenautilus.net>
Date: Mon, 14 Nov 2011 14:48:16 +0000
Subject: some docs

---
 dist.ini                              |   2 +
 lib/Data/MultiValued.pod              |  70 +++++++++++++++++++++++
 lib/Data/MultiValued/Ranges.pm        | 101 +++++++++++++++++++++++++++++++++-
 lib/Data/MultiValued/Tags.pm          |  67 +++++++++++++++++++++-
 lib/Data/MultiValued/TagsAndRanges.pm |  60 ++++++++++++++++++++
 5 files changed, 298 insertions(+), 2 deletions(-)
 create mode 100644 lib/Data/MultiValued.pod

diff --git a/dist.ini b/dist.ini
index a84f6f2..8ac2925 100644
--- a/dist.ini
+++ b/dist.ini
@@ -6,6 +6,8 @@ copyright_year   = 2011
 
 abstract = Handle values with tags and validity ranges
 
+main_module = lib/Data/MultiValued.pod
+
 [GatherDir]
 
 [PodWeaver]
diff --git a/lib/Data/MultiValued.pod b/lib/Data/MultiValued.pod
new file mode 100644
index 0000000..ebae360
--- /dev/null
+++ b/lib/Data/MultiValued.pod
@@ -0,0 +1,70 @@
+# PODNAME: Data::MultiValued
+# ABSTRACT: store tag- and range-dependant data in a scalar or Moose attribute
+
+=head1 SYNOPSIS
+
+  use Data::MultiValued::Tags;
+
+  my $obj = Data::MultiValued::Tags->new();
+  $obj->set({
+    tag => 'tag1',
+    value => 'a string',
+  });
+  say $obj->get({tag=>'tag1'}); # prints 'a string'
+  say $obj->get({tag=>'tag2'}); # dies
+
+Also:
+
+  package My::Class;
+  use Moose;
+  use Data::MultiValued::AttributeTrait::Tags;
+
+  has stuff => (
+    is => 'rw',
+    isa => 'Int',
+    traits => ['MultiValued::Tags'],
+  );
+
+  # later
+
+  my $obj = My::Class->new();
+  $obj->stuff_multi({tag=>'tag1'},123);
+  say $obj->stuff_multi({tag=>'tag1'}); # prints 123
+
+=head1 DESCRIPTION
+
+This set of classes allows you to store different values inside a
+single object, and access them by tag and / or by a numeric value.
+
+Yes, you could do the same with hashes and some clever use of
+arrays. Or you could use L<Array::IntSpan>. Or some other CPAN
+module. Why use these?
+
+=over 4
+
+=item *
+
+they are optimised for serialisation, see
+L<Data::MultiValued::UglySerializationHelperRole> and F<t/json.t>.
+
+=item *
+
+you get accessors generated for your Moose attributes just by setting
+a trait
+
+=item *
+
+tags and ranges interact in sensible ways, including clearing ranges
+
+=back
+
+=head1 Where to go from here
+
+Look at the tests for detailed examples of usage. Look at
+L<Data::MultiValued::Tags>, L<Data::MultiValued::Ranges> and
+L<Data::MultiValued::TagsAndRanges> for the containers
+themselves. Look at L<Data::MultiValued::AttributeTrait::Tags>,
+L<Data::MultiValued::AttributeTrait::Ranges> and
+L<Data::MultiValued::AttributeTrait::TagsAndRanges> for the Moose
+attribute traits.
+
diff --git a/lib/Data/MultiValued/Ranges.pm b/lib/Data/MultiValued/Ranges.pm
index 9c69626..21898af 100644
--- a/lib/Data/MultiValued/Ranges.pm
+++ b/lib/Data/MultiValued/Ranges.pm
@@ -6,7 +6,24 @@ 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
+
+=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
+
+=cut
 
 has _storage => (
     is => 'rw',
@@ -32,6 +49,39 @@ sub _as_hash {
     return {_storage=>\%ret};
 }
 
+=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.
+
+=cut
+
 sub set {
     my ($self,%args) = validated_hash(
         \@_,
@@ -44,6 +94,23 @@ sub set {
          ->{value} = $args{value};
 }
 
+=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.
+
+=cut
+
 sub get {
     my ($self,%args) = validated_hash(
         \@_,
@@ -54,6 +121,33 @@ sub get {
          ->{value};
 }
 
+=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
+
+=cut
+
 sub clear {
     my ($self,%args) = validated_hash(
         \@_,
@@ -64,5 +158,10 @@ sub clear {
     $self->_storage->clear(\%args);
 }
 
+=head1 SEE ALSO
+
+L<Data::MultiValued::RangeContainer>, L<Data::MultiValued::Exceptions>
+
+=cut
 
 1;
diff --git a/lib/Data/MultiValued/Tags.pm b/lib/Data/MultiValued/Tags.pm
index fbf7948..083bbb8 100644
--- a/lib/Data/MultiValued/Tags.pm
+++ b/lib/Data/MultiValued/Tags.pm
@@ -6,7 +6,23 @@ use MooseX::Types::Moose qw(Num Str Undef Any);
 use Data::MultiValued::Exceptions;
 use Data::MultiValued::TagContainer;
 
-# ABSTRACT: Handle values with tags and validity ranges
+# ABSTRACT: Handle values with tags
+
+=head1 SYNOPSIS
+
+  use Data::MultiValued::Tags;
+
+  my $obj = Data::MultiValued::Tags->new();
+  $obj->set({
+    tag => 'tag1',
+    value => 'a string',
+  });
+  say $obj->get({tag=>'tag1'}); # prints 'a string'
+  say $obj->get({tag=>'tag2'}); # dies
+
+=head1 METHODS
+
+=cut
 
 has _storage => (
     is => 'rw',
@@ -32,6 +48,21 @@ sub _as_hash {
     return {_storage=>\%ret};
 }
 
+=head2 C<set>
+
+  $obj->set({ tag => $the_tag, value => $the_value });
+
+Stores the given value for the given tag. Replaces existing
+values. Does not throw exceptions.
+
+Not passing in a C<tag> is equivalent to passing in C<< tag => undef
+>>.
+
+No cloning is done: if you pass in a reference, the reference is
+just stored.
+
+=cut
+
 sub set {
     my ($self,%args) = validated_hash(
         \@_,
@@ -43,6 +74,22 @@ sub set {
          ->{value} = $args{value};
 }
 
+=head2 C<get>
+
+  my $value = $obj->get({ tag => $the_tag });
+
+Retrieves the value for the given tag. Throws a
+L<Data::MultiValued::Exceptions::TagNotFound> exception if the tag
+does not exists in this object.
+
+Not passing in a C<tag> is equivalent to passing in C<< tag => undef
+>>.
+
+No cloning is done: if a reference was stored, you get it back
+untouched.
+
+=cut
+
 sub get {
     my ($self,%args) = validated_hash(
         \@_,
@@ -53,6 +100,18 @@ sub get {
          ->{value};
 }
 
+=head2 C<clear>
+
+  $obj->clear({ tag => $the_tag });
+
+Deletes the given tag and all data associated with it. Does not throw
+exceptions: if the tag does not exist, nothing happens.
+
+Not passing in a C<tag> clears everything. Yes, this means that there
+is no way to just clear the value for the C<undef> tag.
+
+=cut
+
 sub clear {
     my ($self,%args) = validated_hash(
         \@_,
@@ -62,4 +121,10 @@ sub clear {
     $self->_storage->clear(\%args);
 }
 
+=head1 SEE ALSO
+
+L<Data::MultiValued::TagContainer>, L<Data::MultiValued::Exceptions>
+
+=cut
+
 1;
diff --git a/lib/Data/MultiValued/TagsAndRanges.pm b/lib/Data/MultiValued/TagsAndRanges.pm
index 6208435..32e2acb 100644
--- a/lib/Data/MultiValued/TagsAndRanges.pm
+++ b/lib/Data/MultiValued/TagsAndRanges.pm
@@ -8,6 +8,25 @@ use Data::MultiValued::TagContainerForRanges;
 
 # ABSTRACT: Handle values with tags and validity ranges
 
+=head1 SYNOPSIS
+
+  use Data::MultiValued::TagsAndRanges;
+
+  my $obj = Data::MultiValued::TagsAndRanges->new();
+  $obj->set({
+    tag => 'tag1',
+    from => 10,
+    to => 20,
+    value => 'foo',
+  });
+  say $obj->get({tag => 'tag1', at => 15}); # prints 'foo'
+  say $obj->get({tag => 'tag1', at => 35}); # dies
+  say $obj->get({tag => 'tag2', at => 15}); # dies
+
+=head1 METHODS
+
+=cut
+
 has _storage => (
     is => 'rw',
     isa => class_type('Data::MultiValued::TagContainerForRanges'),
@@ -33,6 +52,18 @@ sub _as_hash {
     return {_storage=>$ret};
 }
 
+=head2 C<set>
+
+  $obj->set({ tag => $the_tag, from => $min, to => $max, value => $the_value });
+
+Stores the given value for the given tag and range. Does not throw
+exceptions.
+
+See L<Data::MultiValued::Tags/set> and
+L<Data::MultiValued::Ranges/set> for more details.
+
+=cut
+
 sub set {
     my ($self,%args) = validated_hash(
         \@_,
@@ -47,6 +78,21 @@ sub set {
          ->{value} = $args{value};
 }
 
+=head2 C<get>
+
+  my $value = $obj->get({ tag => $the_tag, at => $point });
+
+Retrieves the value for the given tag and point. Throws a
+L<Data::MultiValued::Exceptions::RangeNotFound> exception if no ranges
+exist in this object that include the point, and
+L<Data::MultiValued::Exceptions::TagNotFound> exception if the tag
+does not exists in this object.
+
+See L<Data::MultiValued::Tags/get> and
+L<Data::MultiValued::Ranges/get> for more details.
+
+=cut
+
 sub get {
     my ($self,%args) = validated_hash(
         \@_,
@@ -59,6 +105,20 @@ sub get {
          ->{value};
 }
 
+=head2 C<clear>
+
+  $obj->clear({ tag => $the_tag, from => $min, to => $max });
+
+If a range is specified, deletes all values for the given range and
+tag. If no range is specified, delete all values for the given tag.
+
+Does not throw exceptions.
+
+See L<Data::MultiValued::Tags/clear> and
+L<Data::MultiValued::Ranges/clear> for more details.
+
+=cut
+
 sub clear {
     my ($self,%args) = validated_hash(
         \@_,
-- 
cgit v1.2.3


From cc7e65cafe5b423e72f5939947d3989aaeeaefcd Mon Sep 17 00:00:00 2001
From: Gianni Ceccarelli <dakkar@thenautilus.net>
Date: Mon, 14 Nov 2011 15:06:47 +0000
Subject: fix tags&ranges ser bug (w/ test)

---
 lib/Data/MultiValued/TagContainerForRanges.pm | 9 +++++++--
 t/json.t                                      | 3 +++
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/lib/Data/MultiValued/TagContainerForRanges.pm b/lib/Data/MultiValued/TagContainerForRanges.pm
index d3cd4b9..604dcb7 100644
--- a/lib/Data/MultiValued/TagContainerForRanges.pm
+++ b/lib/Data/MultiValued/TagContainerForRanges.pm
@@ -20,14 +20,19 @@ sub _create_new_inferior {
 
 sub _rebless_storage {
     my ($self) = @_;
-    bless $self->{_storage},'Data::MultiValued::RangeContainer';
+    bless $_,'Data::MultiValued::RangeContainer'
+        for values %{$self->{_storage}};
     bless $self->{_default_tag},'Data::MultiValued::RangeContainer';
     return;
 }
 
 sub _as_hash {
     my ($self) = @_;
-    my %st = %{$self->_storage};
+    my %st;
+    for my $k (keys %{$self->_storage}) {
+        my %v = %{$self->_storage->{$k}};
+        $st{$k}=\%v;
+    }
     my %dt = %{$self->_default_tag};
     return {
         _storage => \%st,
diff --git a/t/json.t b/t/json.t
index 5e00080..d1162b3 100644
--- a/t/json.t
+++ b/t/json.t
@@ -43,10 +43,12 @@ use Data::Printer;
 use JSON::XS;
 
 my $opts={tag=>'something'};
+my $ropts={tag=>'something',from=>10,to=>20};
 
 my $json = JSON::XS->new->utf8;
 my $obj = Foo->new(rr=>'foo');
 $obj->tt_multi($opts,1234);
+$obj->ttrr_multi($ropts,777);
 my $hash = $obj->as_hash;
 note p $hash;
 my $str = $json->encode($hash);
@@ -60,6 +62,7 @@ note p $obj2;
 
 is($obj2->tt,$obj->tt,'tt');
 is($obj2->tt_multi($opts),$obj->tt_multi($opts),'tt tagged');
+is($obj2->ttrr_multi({at => 15}),$obj->ttrr_multi({at => 15}),'ttrr');
 is($obj2->rr,$obj->rr,'rr');
 
 done_testing;
-- 
cgit v1.2.3


From bd84f294c8d5c8b3680c726b67b6de6391f497cd Mon Sep 17 00:00:00 2001
From: Gianni Ceccarelli <dakkar@thenautilus.net>
Date: Mon, 14 Nov 2011 15:06:52 +0000
Subject: more docs

---
 lib/Data/MultiValued/TagContainer.pm          | 66 +++++++++++++++++++++++++++
 lib/Data/MultiValued/TagContainerForRanges.pm | 32 +++++++++++++
 2 files changed, 98 insertions(+)

diff --git a/lib/Data/MultiValued/TagContainer.pm b/lib/Data/MultiValued/TagContainer.pm
index cdd0456..b7a9b13 100644
--- a/lib/Data/MultiValued/TagContainer.pm
+++ b/lib/Data/MultiValued/TagContainer.pm
@@ -4,6 +4,26 @@ use Moose::Util::TypeConstraints;
 use MooseX::Types::Moose qw(HashRef);
 use Data::MultiValued::Exceptions;
 
+# ABSTRACT: container for tagged values
+
+=head1 DESCRIPTION
+
+Please don't use this module directly, use L<Data::MultiValued::Tags>.
+
+This module implements the storage for tagged data. It's almost
+exactly a hash, the main difference being that C<undef> is a valid key
+and it's distinct from the empty string.
+
+Another difference is that you get an exception if you try to access a
+tag that's not there.
+
+Data is kept in "storage cells", as created by
+L</_create_new_inferior> (by default, a hashref).
+
+=head1 METHODS
+
+=cut
+
 has _storage => (
     is => 'rw',
     isa => HashRef,
@@ -25,6 +45,19 @@ has _default_tag => (
     clearer => '_clear_default_tag',
 );
 
+=head2 C<get>
+
+  my $value = $obj->get({ tag => $the_tag });
+
+Retrieves the "storage cell" for the given tag. Throws a
+L<Data::MultiValued::Exceptions::TagNotFound> exception if the tag
+does not exists in this object.
+
+Not passing in a C<tag> is equivalent to passing in C<< tag => undef
+>>.
+
+=cut
+
 sub get {
     my ($self,$args) = @_;
 
@@ -48,6 +81,19 @@ sub get {
     return $self->_get_tag($tag);
 }
 
+=head2 C<get_or_create>
+
+  $obj->get_or_create({ tag => $the_tag });
+
+Retrieves the "storage cell" for the given tag. If the tag does not
+exist, creates a new cell (see L</_create_new_inferior>), sets it for
+the tag, and returns it.
+
+Not passing in a C<tag> is equivalent to passing in C<< tag => undef
+>>.
+
+=cut
+
 sub get_or_create {
     my ($self,$args) = @_;
 
@@ -76,6 +122,19 @@ sub _clear_storage {
     $self->_storage({});
 }
 
+=head2 C<clear>
+
+  $obj->clear({ tag => $the_tag });
+
+Deletes the given tag and all data associated with it. Does not throw
+exceptions: if the tag does not exist, nothing happens.
+
+Not passing in a C<tag>, or passing C<< tag => undef >>, clears
+everything. If you want to only clear the C<undef> tag, you may call
+C<_clear_default_tag> (which is considered a "protected" method).
+
+=cut
+
 sub clear {
     my ($self,$args) = @_;
 
@@ -91,6 +150,13 @@ sub clear {
     return;
 }
 
+=head2 C<_create_new_inferior>
+
+Returns a new "storage cell", by default an empty hashref. See
+L<Data::MultiValued::TagContainerForRanges> for an example of use.
+
+=cut
+
 sub _create_new_inferior {
     my ($self) = @_;
     return {};
diff --git a/lib/Data/MultiValued/TagContainerForRanges.pm b/lib/Data/MultiValued/TagContainerForRanges.pm
index 604dcb7..9cfc617 100644
--- a/lib/Data/MultiValued/TagContainerForRanges.pm
+++ b/lib/Data/MultiValued/TagContainerForRanges.pm
@@ -4,6 +4,21 @@ use MooseX::Types::Moose qw(HashRef);
 use Moose::Util::TypeConstraints;
 use Data::MultiValued::RangeContainer;
 
+# ABSTRACT: container for tagged values that are ranged containers
+
+=head1 DESCRIPTION
+
+Please don't use this module directly, use
+L<Data::MultiValued::TagsAndRanges>.
+
+This module is a subclass of L<Data::MultiValued::TagContainer>, which
+only allows instances of L<Data::MultiValued::RangeContainer> as
+"storage cells".
+
+=head1 METHODS
+
+=cut
+
 extends 'Data::MultiValued::TagContainer';
 
 has '+_storage' => (
@@ -14,10 +29,27 @@ has '+_default_tag' => (
     isa => class_type('Data::MultiValued::RangeContainer'),
 );
 
+=head2 C<_create_new_inferior>
+
+Returns a new L<Data::MultiValued::RangeContainer> instance.
+
+=cut
+
 sub _create_new_inferior {
     Data::MultiValued::RangeContainer->new();
 }
 
+=head1 Serialisation helpers
+
+These are used through
+L<Data::MultiValued::UglySerializationHelperRole>.
+
+=head2 C<_rebless_storage>
+
+Blesses the "storage cells"
+
+=cut
+
 sub _rebless_storage {
     my ($self) = @_;
     bless $_,'Data::MultiValued::RangeContainer'
-- 
cgit v1.2.3


From 6edfeb6fcbfe718fb13288060307f919e10d607a Mon Sep 17 00:00:00 2001
From: Gianni Ceccarelli <dakkar@thenautilus.net>
Date: Mon, 14 Nov 2011 15:52:01 +0000
Subject: more docs

---
 lib/Data/MultiValued/RangeContainer.pm        | 83 +++++++++++++++++++++++++--
 lib/Data/MultiValued/Ranges.pm                | 53 +++++++++++------
 lib/Data/MultiValued/TagContainerForRanges.pm |  9 ++-
 lib/Data/MultiValued/Tags.pm                  | 44 +++++++++-----
 lib/Data/MultiValued/TagsAndRanges.pm         | 50 +++++++++++-----
 5 files changed, 190 insertions(+), 49 deletions(-)

diff --git a/lib/Data/MultiValued/RangeContainer.pm b/lib/Data/MultiValued/RangeContainer.pm
index e9b1b62..0bfe8cd 100644
--- a/lib/Data/MultiValued/RangeContainer.pm
+++ b/lib/Data/MultiValued/RangeContainer.pm
@@ -5,6 +5,27 @@ use MooseX::Types::Moose qw(Num Str Any Undef ArrayRef);
 use MooseX::Types::Structured qw(Dict);
 use Data::MultiValued::Exceptions;
 
+# ABSTRACT: container for ranged values
+
+=head1 DESCRIPTION
+
+Please don't use this module directly, use L<Data::MultiValued::Ranges>.
+
+This module implements the storage for ranged data. It's similar to
+L<Array::IntSpan>, but simpler (and slower).
+
+A range is defined by a pair of numbers, C<from> and C<to>, and it
+contains C<< Num $x : $min <= $x < $max >>. C<undef> is treated as
+"inf" (negative infinity if used as C<from> or C<at>, positive
+infinity if used as C<to>).
+
+The internal representation of a range is a hash with three keys,
+C<from> C<to> C<value>.
+
+=head1 METHODS
+
+=cut
+
 has _storage => (
     is => 'rw',
     isa => ArrayRef[
@@ -18,6 +39,16 @@ has _storage => (
     default => sub { [ ]  },
 );
 
+=head2 C<get>
+
+  my $value = $obj->get({ at => $point });
+
+Retrieves the range that includes the given point. Throws a
+L<Data::MultiValued::Exceptions::RangeNotFound> exception if no range
+includes the point.
+
+=cut
+
 sub get {
     my ($self,$args) = @_;
 
@@ -45,6 +76,8 @@ sub _cmp {
     return $a <=> $b;
 }
 
+# a binary search would be a good idea.
+
 sub _get_slot_at {
     my ($self,$at) = @_;
 
@@ -56,6 +89,10 @@ sub _get_slot_at {
     return;
 }
 
+# this is quite probably uselessly slow: we don't really need all of
+# @before and @after, we just need to know if they're not empty; also,
+# a binary search would be a good idea.
+
 sub _partition_slots {
     my ($self,$from,$to) = @_;
 
@@ -80,7 +117,18 @@ sub _partition_slots {
     return \@before,\@overlap,\@after;
 }
 
-sub set_or_create {
+=head2 C<get_or_create>
+
+  $obj->get_or_create({ from => $min, to => $max });
+
+Retrieves the range that has the given extremes. If no such range
+exists, creates a new range, splicing any existing overlapping range,
+and returns it. Throws L<Data::MultiValued::Exceptions::BadRange> if
+C<< $min > $max >>.
+
+=cut
+
+sub get_or_create {
     my ($self,$args) = @_;
 
     my $from = $args->{from};
@@ -103,6 +151,19 @@ sub set_or_create {
     return $range;
 }
 
+=head2 C<clear>
+
+  $obj->clear({ from => $min, to => $max });
+
+Removes the range that has the given extremes. If no such range
+exists, splices any existing overlapping range so that C<<
+$obj->get({at => $point }) >> for any C<< $min <= $point < $max >>
+will die.
+
+Throws L<Data::MultiValued::Exceptions::BadRange> if C<< $min > $max >>.
+
+=cut
+
 sub clear {
     my ($self,$args) = @_;
 
@@ -133,10 +194,16 @@ sub _clear_slot {
     $self->_splice_slot($from,$to);
 }
 
+# Most of the splicing mechanics is here. Given a range and something
+# to put in it, do "the right thing"
+
 sub _splice_slot {
     my ($self,$from,$to,$new) = @_;
 
-    if (!@{$self->_storage}) { # empty
+    # if !$new, it's like C<splice> without a replacement list: we
+    # just delete the range
+
+    if (!@{$self->_storage}) { # empty, just store
         push @{$self->_storage},$new if $new;
         return $new;
     }
@@ -144,27 +211,33 @@ sub _splice_slot {
     my ($before,$overlap,$after) = $self->_partition_slots($from,$to);
 
     if (!@$before && !@$overlap) {
+        # nothing before, nothing overlapping: put $new at the beginning
         unshift @{$self->_storage},$new if $new;
         return $new;
     }
     if (!@$after && !@$overlap) {
+        # nothing after, nothing overlapping: put $new at the end
         push @{$self->_storage},$new if $new;
         return $new;
     }
 
-    # by costruction, the first and the last may have to be split, all
-    # others must be removed
+    # ok, we have to insert in the middle of things, and maybe we have
+    # to trim existing ranges
+
     my $first_to_replace;
     my $how_many = @$overlap;
 
     my @replacement = $new ? ($new) : ();
 
     if ($how_many > 0) { # we have to splice
+        # by costruction, the first and the last may have to be split, all
+        # others must be removed
         $first_to_replace = $overlap->[0];
         my $last_to_replace = $overlap->[-1];
         my $first = $self->_storage->[$first_to_replace];
         my $last = $self->_storage->[$last_to_replace];
 
+        # does the first overlapping range need trimming?
         if (_cmp($first->{from},$from,0,0)<0
             && _cmp($first->{to},$from,1,0)>=0) {
             unshift @replacement, {
@@ -173,6 +246,7 @@ sub _splice_slot {
                 value => $first->{value},
             }
         }
+        # does the last overlapping range need trimming?
         if (_cmp($last->{from},$to,0,1)<=0
             && _cmp($last->{to},$to,1,1)>0) {
             push @replacement, {
@@ -183,6 +257,7 @@ sub _splice_slot {
         }
     }
     else {
+        # no overlaps, just insert between @before and @after
         $first_to_replace = $before->[-1]+1;
     }
 
diff --git a/lib/Data/MultiValued/Ranges.pm b/lib/Data/MultiValued/Ranges.pm
index 21898af..7193df6 100644
--- a/lib/Data/MultiValued/Ranges.pm
+++ b/lib/Data/MultiValued/Ranges.pm
@@ -36,24 +36,12 @@ sub _build__storage {
     Data::MultiValued::RangeContainer->new();
 }
 
-sub _rebless_storage {
-    my ($self) = @_;
-
-    bless $self->{_storage},'Data::MultiValued::RangeContainer';
-}
-
-sub _as_hash {
-    my ($self) = @_;
-
-    my %ret = %{$self->_storage};
-    return {_storage=>\%ret};
-}
-
 =head2 C<set>
 
   $obj->set({ from => $min, to => $max, value => $the_value });
 
-Stores the given value for the given range. Does not throw exceptions.
+Stores the given value for the given range. Throws
+L<Data::MultiValued::Exceptions::BadRange> if C<< $min > $max >>.
 
 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
@@ -90,7 +78,7 @@ sub set {
         value => { isa => Any, },
     );
 
-    $self->_storage->set_or_create(\%args)
+    $self->_storage->get_or_create(\%args)
          ->{value} = $args{value};
 }
 
@@ -125,7 +113,8 @@ sub get {
 
   $obj->clear({ from => $min, to => $max });
 
-Deletes all values for the given range. Does not throw exceptions.
+Deletes all values for the given range. Throws
+L<Data::MultiValued::Exceptions::BadRange> if C<< $min > $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
@@ -158,6 +147,38 @@ sub clear {
     $self->_storage->clear(\%args);
 }
 
+=head1 Serialisation helpers
+
+These are used through
+L<Data::MultiValued::UglySerializationHelperRole>.
+
+=head2 C<_rebless_storage>
+
+Blesses the storage into L<Data::MultiValued::RangeContainer>.
+
+=cut
+
+sub _rebless_storage {
+    my ($self) = @_;
+
+    bless $self->{_storage},'Data::MultiValued::RangeContainer';
+}
+
+
+=head2 C<_as_hash>
+
+Returns the internal representation with no blessed hashes, with as
+few copies as possible.
+
+=cut
+
+sub _as_hash {
+    my ($self) = @_;
+
+    my %ret = %{$self->_storage};
+    return {_storage=>\%ret};
+}
+
 =head1 SEE ALSO
 
 L<Data::MultiValued::RangeContainer>, L<Data::MultiValued::Exceptions>
diff --git a/lib/Data/MultiValued/TagContainerForRanges.pm b/lib/Data/MultiValued/TagContainerForRanges.pm
index 9cfc617..826df9d 100644
--- a/lib/Data/MultiValued/TagContainerForRanges.pm
+++ b/lib/Data/MultiValued/TagContainerForRanges.pm
@@ -46,7 +46,7 @@ L<Data::MultiValued::UglySerializationHelperRole>.
 
 =head2 C<_rebless_storage>
 
-Blesses the "storage cells"
+Blesses the "storage cells" into L<Data::MultiValued::RangeContainer>.
 
 =cut
 
@@ -58,6 +58,13 @@ sub _rebless_storage {
     return;
 }
 
+=head2 C<_as_hash>
+
+Returns the internal representation with no blessed hashes, with as
+few copies as possible.
+
+=cut
+
 sub _as_hash {
     my ($self) = @_;
     my %st;
diff --git a/lib/Data/MultiValued/Tags.pm b/lib/Data/MultiValued/Tags.pm
index 083bbb8..9c52510 100644
--- a/lib/Data/MultiValued/Tags.pm
+++ b/lib/Data/MultiValued/Tags.pm
@@ -35,19 +35,6 @@ sub _build__storage {
     Data::MultiValued::TagContainer->new();
 }
 
-sub _rebless_storage {
-    my ($self) = @_;
-
-    bless $self->{_storage},'Data::MultiValued::TagContainer';
-}
-
-sub _as_hash {
-    my ($self) = @_;
-
-    my %ret = %{$self->_storage};
-    return {_storage=>\%ret};
-}
-
 =head2 C<set>
 
   $obj->set({ tag => $the_tag, value => $the_value });
@@ -121,6 +108,37 @@ sub clear {
     $self->_storage->clear(\%args);
 }
 
+=head1 Serialisation helpers
+
+These are used through
+L<Data::MultiValued::UglySerializationHelperRole>.
+
+=head2 C<_rebless_storage>
+
+Blesses the storage into L<Data::MultiValued::TagContainer>.
+
+=cut
+
+sub _rebless_storage {
+    my ($self) = @_;
+
+    bless $self->{_storage},'Data::MultiValued::TagContainer';
+}
+
+=head2 C<_as_hash>
+
+Returns the internal representation with no blessed hashes, with as
+few copies as possible.
+
+=cut
+
+sub _as_hash {
+    my ($self) = @_;
+
+    my %ret = %{$self->_storage};
+    return {_storage=>\%ret};
+}
+
 =head1 SEE ALSO
 
 L<Data::MultiValued::TagContainer>, L<Data::MultiValued::Exceptions>
diff --git a/lib/Data/MultiValued/TagsAndRanges.pm b/lib/Data/MultiValued/TagsAndRanges.pm
index 32e2acb..204f858 100644
--- a/lib/Data/MultiValued/TagsAndRanges.pm
+++ b/lib/Data/MultiValued/TagsAndRanges.pm
@@ -38,20 +38,6 @@ sub _build__storage {
     Data::MultiValued::TagContainerForRanges->new();
 }
 
-sub _rebless_storage {
-    my ($self) = @_;
-
-    bless $self->{_storage},'Data::MultiValued::TagContainerForRanges';
-    $self->_storage->_rebless_storage;
-}
-
-sub _as_hash {
-    my ($self) = @_;
-
-    my $ret = $self->_storage->_as_hash;
-    return {_storage=>$ret};
-}
-
 =head2 C<set>
 
   $obj->set({ tag => $the_tag, from => $min, to => $max, value => $the_value });
@@ -74,7 +60,7 @@ sub set {
     );
 
     $self->_storage->get_or_create(\%args)
-         ->set_or_create(\%args)
+         ->get_or_create(\%args)
          ->{value} = $args{value};
 }
 
@@ -136,4 +122,38 @@ sub clear {
     }
 }
 
+=head1 Serialisation helpers
+
+These are used through
+L<Data::MultiValued::UglySerializationHelperRole>.
+
+=head2 C<_rebless_storage>
+
+Blesses the storage into L<Data::MultiValued::TagContainerForRanges>,
+then calls C<_rebless_storage> on it.
+
+=cut
+
+sub _rebless_storage {
+    my ($self) = @_;
+
+    bless $self->{_storage},'Data::MultiValued::TagContainerForRanges';
+    $self->_storage->_rebless_storage;
+}
+
+=head2 C<_as_hash>
+
+Returns the internal representation with no blessed hashes, with as
+few copies as possible. Depends on
+L<Data::MultiValued::TagContainerForRanges/_as_hash>.
+
+=cut
+
+sub _as_hash {
+    my ($self) = @_;
+
+    my $ret = $self->_storage->_as_hash;
+    return {_storage=>$ret};
+}
+
 1;
-- 
cgit v1.2.3