Toby Inkster > JSON-MultiValueOrdered > Tie::Hash::MultiValueOrdered

Download:
JSON-MultiValueOrdered-0.005.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

New  3
Open  0
View/Report Bugs
Module Version: 0.005   Source  

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.

syntax highlighting: