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

       Toby Inkster <tobyink@cpan.org>.

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

       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.

       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.

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

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

       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.

perl v5.36.0                                       2022-11-20                  Tie::Hash::MultiValueOrdered(3pm)

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

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

          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;