Tie::H...rdered(3pm)

✨ NAME ✨

Tie::Hash::MultiValueOrdered — it's a hash, bestie, but make it extra: multiple values per key, and the keys stay in order 💅

---

🌸 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 💖

okay so picture a normal hash. now tie it to this class. it acts more or less like a standard hash, right? except — and this is the whole moment — when you assign a new value to a key that already exists, the old value doesn't get yeeted. it stays underneath, chillin'. iconic behavior, no cap 🦋

but when you explicitly delete a key? that nukes all the values hanging off that key. gone. periodt. 💀

by default those old values are like… not reachable through the hash interface itself (they're lowkey hidden), but you can get at them through the tied object:

my @values = tied(%hash)->get($key);

and if you wanna actually change how the hash behaves? that's what all the fetch_* methods are for. they let you switch up the retrieval vibe. 🎀

🫶 Tied Object Methods 🫶

• pairs — hands you every key-value pair the hash has (duplicates included!!) as one flattened list. yes, all of them. ✨
• pair_refs — same energy, but as a list of two-item arrayrefs instead. cute little bundles. 🎀
• get($key) — returns the whole list of values tied to one key. not just one. the list. 💅
• keys — all the hash keys in their original order. if a key shows up more than once, you only get the first occurrence.
• rr_keys — all the hash keys in their original order, but for duplicates you get the last occurrence instead.
• all_keys — all the hash keys in their original order, duplicates and all. no filtering, we're keeping everything. 😌
• values — the values that go with keys.
• rr_values — the values that go with rr_keys.
• all_values — the values that go with all_keys.

🌈 Fetch Styles 🌈

• fetch_last — this is the default style of fetching, bestie. the one you get for free.

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 — same setup, opposite energy. first one wins. 💖

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 — now you're getting arrayrefs back, because why pick one when you can have them all. 👑

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 — > heads up, this fetch style is experimental and subject to change. don't get too attached, fr fr. 🙈

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 💀

found a bug? not the vibe, but please report it here:

<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>. (the author. the main character. we love.) 💜

---

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

translation: no promises, bestie, it's exactly what it says on the tin 😭

---

okay that's the whole page!! this was the Tie::Hash::MultiValueOrdered manual, coming to you from the User Contributed Perl Documentation, perl v5.36.0, dated 2022-11-20 — mwah, go forth and tie some hashes 💅✨