NAME

Data::MultiValued::Ranges - Handle values with validity ranges

VERSION

version 0.0.1_4

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

METHODS

set

  $obj->set({ from => $min, to => $max, value => $the_value });

Stores the given value for the given range. Throws Data::MultiValued::Exceptions::BadRange if $min > $max.

The range is defined as Num $x : $min <= $x < $max. A from => undef means "from -Inf", and a to => undef means "to +Inf". Not passing in from or to is equivalent to passing 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.

get

  my $value = $obj->get({ at => $point });

Retrieves the value for the given point. Throws a Data::MultiValued::Exceptions::RangeNotFound exception if no ranges exist in this object that include the point (remember that a range does not include its to point).

A at => undef means "at -Inf". Not passing in at is equivalent to passing undef.

No cloning is done: if a reference was stored, you get it back untouched.

clear

  $obj->clear({ from => $min, to => $max });

Deletes all values for the given range. Throws Data::MultiValued::Exceptions::BadRange if $min > $max.

A from => undef means "from -Inf", and a to => undef means "to +Inf". Not passing in from or to is equivalent to passing undef. Thus, $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

Serialisation helpers

These are used through Data::MultiValued::UglySerializationHelperRole.

_rebless_storage

Blesses the storage into Data::MultiValued::RangeContainer.

_as_hash

Returns the internal representation with no blessed hashes, with as few copies as possible.

SEE ALSO

Data::MultiValued::RangeContainer, Data::MultiValued::Exceptions

AUTHOR

Gianni Ceccarelli <dakkar@thenautilus.net>

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.

cpanm Data::MultiValued

perl -MCPAN -e shell
install Data::MultiValued