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 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);

AUTHOR

Toby Inkster <[email protected]>.

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.