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>.

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.