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 occurrence is returned.
"rr_keys": The list of all hash keys in their original order. Where a key is duplicated, only the last occurrence is returned.
"all_keys": The list of all hash keys in their original order, including duplicates.
"values": The values corresponding to "keys".
"rr_values": The values corresponding to "rr_keys".
"all_values": The values corresponding 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>.

AUTHOR

Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

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.

2022-11-20

perl v5.36.0