NAME

Tie::Hash::MultiValueOrdered - hash with multiple values per key, and ordered keys

SYNOPSIS

   use Test::More;
   use Tie::Hash::MultiValueOrdered;
   
   my $tied = tie my %hash, "Tie::Hash::MultiValueOrdered";
   
   $hash{a} = 1;
   $hash{b} = 2;
   $hash{a} = 3;
   $hash{b} = 4;
   
   # Order of keys is predictable
   is_deeply(
      [ keys %hash ],
      [ qw( a b ) ],
   );
   
   # Order of values is predictable
   # Note that the last values of 'a' and 'b' are returned.
   is_deeply(
      [ values %hash ],
      [ qw( 3 4 ) ],
   );
   
   # Can retrieve list of all key-value pairs
   is_deeply(
      [ $tied->pairs ],
      [ qw( a 1 b 2 a 3 b 4 ) ],
   );
   
   # Switch the retrieval mode for the hash.
   $tied->fetch_first;
   
   # Now the first values of 'a' and 'b' are returned.
   is_deeply(
      [ values %hash ],
      [ qw( 1 2 ) ],
   );
   
   # Switch the retrieval mode for the hash.
   $tied->fetch_list;
   
   # Now arrayrefs are returned.
   is_deeply(
      [ values %hash ],
      [ [1,3], [2,4] ],
   );
   
   # Restore the default retrieval mode for the hash.
   $tied->fetch_last;
   
   done_testing;

DESCRIPTION

A hash tied to this class acts more or less like a standard hash, except that when you assign a new value to an existing key, the old value is retained underneath. An explicit delete deletes all values associated with a key.

By default, the old values are inaccessible through the hash interface, but can be retrieved via the tied object:

   my @values = tied(%hash)->get($key);

However, the fetch_* methods provide a means to alter the behaviour of the hash.

Tied Object Methods

pairs

Returns all the hash's key-value pairs (including duplicates) as a flattened list.

pair_refs

Returns all the hash's key-value pairs (including duplicates) as a list of two item arrayrefs.

get($key)

Returns the list of all values associated with a key.

keys

The list of all hash keys in their original order. Where a key is duplicated, only the first occurance is returned.

rr_keys

The list of all hash keys in their original order. Where a key is duplicated, only the last occurance is returned.

all_keys

The list of all hash keys in their original order, including duplicates.

values

The values correponding to keys.

rr_values

The values correponding to rr_keys.

all_values

The values correponding to all_keys.

Fetch Styles

fetch_last

This is the default style of fetching.

   tie my %hash, "Tie::Hash::MultiValueOrdered";
   
   $hash{a} = 1;
   $hash{b} = 2;
   $hash{b} = 3;
   
   tied(%hash)->fetch_last;
   
   is($hash{a}, 1);
   is($hash{b}, 3);

fetch_first

   tie my %hash, "Tie::Hash::MultiValueOrdered";
   
   $hash{a} = 1;
   $hash{b} = 2;
   $hash{b} = 3;
   
   tied(%hash)->fetch_first;
   
   is($hash{a}, 1);
   is($hash{b}, 2);

fetch_list

   tie my %hash, "Tie::Hash::MultiValueOrdered";
   
   $hash{a} = 1;
   $hash{b} = 2;
   $hash{b} = 3;
   
   tied(%hash)->fetch_first;
   
   is_deeply($hash{a}, [1]);
   is_deeply($hash{b}, [2, 3]);

fetch_iterator

This fetch style is experimental and subject to change.

   tie my %hash, "Tie::Hash::MultiValueOrdered";
   
   $hash{a} = 1;
   $hash{b} = 2;
   $hash{b} = 3;
   
   tied(%hash)->fetch_iterator;
   
   my $A = $hash{a};
   my $B = $hash{b};
   
   is($A->(), 1);
   is($B->(), 2);
   is($B->(), 3);

BUGS

Please report any bugs to http://rt.cpan.org/Dist/Display.html?Queue=JSON-MultiValueOrdered.

SEE ALSO

JSON::Tiny::Subclassable, JSON::Tiny, Mojo::JSON.

AUTHOR

Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

This software is copyright (c) 2012-2013 by Toby Inkster.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

DISCLAIMER OF WARRANTIES

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.