Tie::Ha...ltiValue(3)

💖 NAME 💖

Tie::Hash::MultiValue — store multiple values per key 🎀

okay so this is Tie::Hash::MultiValue(3), from the User Contributed Perl Documentation corner of the manual, and it is literally the bestie who lets your hash hold a whole squad of values under one key instead of ghosting all but the last one 💅

---

✨ SYNOPSIS ✨

use Tie::Hash::MultiValue;
my $controller = tie %hash, 'Tie::Hash::MultiValue';
$hash{'foo'} = 'one';
$hash{'bar'} = 'two';
$hash{'bar'} = 'three';

# Fetch the values as references to arrays.
$controller->refs;
my @values  = @{$hash{'foo'}};   # @values = ('one');
my @more    = @{$hash{'bar'}};   # @more   = ('two', 'three');
my @nothing = @{$hash{'baz'}};   # empty list if nothing there

# You can tie an anonymous hash as well.
my $hashref = {};
tie %$hashref, 'Tie::Hash::MultiValue';
$hashref->{'sample'} = 'one';
$hashref->{'sample'} = 'two';
# $hashref->{'sample'} now contains ['one','two']

# Iterate over the items stored under a key.
$controller->iterators;
while(my $value = $hash{bar}) {
  print "bar: $value\n";
}
# prints
#   bar: two
#   bar: three

like, look at that. foo keeps its one lil value, bar is holding two AND three at the same time, and baz is just out here being empty and unbothered 🦋

---

🌸 DESCRIPTION 🌸

Tie::Hash::MultiValue lets you have hashes which store their values in anonymous arrays, appending any new value to the already-existing ones.

This means that you can store as many items as you like under a single key, and access them all at once by accessing the value stored under the key.

translation: every time you assign to a key, it doesn't overwrite, it adds. your hash is a group chat, not a DM 💬

---

🫶 USAGE 🫶

See the synopsis for a typical usage.

(yeah bestie, the vibes up top ARE the tutorial ✨)

---

💀 BUGS 💀

None currently known.

not a single one. flawless. no notes. periodt 👑

---

🎀 SUPPORT 🎀

Contact the author for support.

---

🌈 AUTHOR 🌈

        Joe McMahon
        CPAN ID: MCMAHON
        mcmahon@ibiblio.org
        http://ibiblio.org/mcmahon

shoutout to Joe, the main character who built this 🫡

---

⭐ COPYRIGHT ⭐

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

---

🦋 SEE ALSO 🦋

• Tie::Hash
• perl(1)
• Perl Cookbook (1st version) recipe 13.15, program 13-5.

---

👑 METHODS 👑

This class is a subclass of Tie::ExtraHash; it needs to override the TIEHASH method to save the instance data (in $self->[1]), and the STORE method to actually save the values in an anonymous array.

so yeah, it's inheriting from Tie::ExtraHash and doing a lil custom footwork on top 💅

🧚 TIEHASH 🧚

If the 'unique' argument is supplied, we check to see if it supplies a subroutine reference to be used to compare items. If it does, we store that reference in the object describing this tie; if not, we supply a function which simply uses 'eq' to test for equality.

🌸 The 'unique' function 🌸

This funtion will receive two scalar arguments. No assumption is made about whether or not either argument is defined, nor whether these are simple scalars or references. You can make any of these assumptions if you choose, but you are responsible for checking your input.

You can perform whatever tests you like in your routine; you should return a true value if the arguments are determined to be equal, and a false one if they are not.

(yes, "funtion" — that's a typo in the original, we're keeping it, it's canon now 🙈)

so basically: your compare function gets two scalars, it does NOT get to assume anything about them (defined? reference? scalar? who knows), and you are the one on the hook for checking. return true if they're equal, false if they're not. that's the whole job 🫶

💖 STORE 💖

Push the value(s) supplied onto the list of values stored here. The anonymous array is created automatically if it doesn't yet exist.

If the 'unique' argument was supplied at the time the hash was tied, we will use the associated function (either yours, if you supplied one; or ours, if you didn't) and only add the item or items that are not present.

tl;dr — no dupes, no drama, the array spawns itself on demand ✨

🔥 FETCH 🔥

Fetches the current value(s) for a key, depending on the current mode we're in.

• 'refs' mode

Always returns an anonymous array containing the values stored under this key, or an empty anonymous array if there are none.

• 'iterators' mode

If there is a single entry, acts just like a normal hash fetch. If there are multiple entries for a key, we automatically iterate over the items stored under the key, returning undef when the last item under that key has been fetched.

Storing more elements into a key while you're iterating over it will result in the new elements being returned at the end of the list. If you've turned on 'unique', remember that they won't be stored if they're already in the value list for the key.

NOTE: If you store undef in your hash, and then store other values, the iterator will, when it sees your undef, return it as a normal value. This means that you won't be able to tell whether that's your undef, or the 'I have no more data here' undef. Using 'list' or 'refs' mode is strongly suggested if you need to store data that may include undefs.

Note that every key has its own iterator, so you can mix accesses across keys and still get all the values:

  my $controller = tie %hash, 'Tie::Hash::MultiValue';
  $controller->iterators;
  $hash{x} = $_ for qw(a b c);
  $hash{y} = $_ for qw(d e f);
  while ( my($x, $y) = ($hash{x}, $hash{y}) {
     # gets (a,d) (b,e) (c,f)
  }

lowkey scary part: if you stash an undef in there and then stash more stuff, the iterator hands you your undef back like a totally normal value — so you literally can't tell if it's your undef or the "I have no more data here" undef. if your data might contain undefs, use 'list' or 'refs' mode, fr fr. don't do it to yourself 😭

🎀 iterators 🎀

Called on the object returned from tie(). Tells FETCH to return elements one at a time each time the key is accessed until no more element remain.

one at a time, bestie. take your time. no need to rush the buffet 🍓

💅 refs 💅

Tells FETCH to always return the reference associated with a key. (This allows you to, for instance, replace all of the values at once with different ones.)

give me the WHOLE array or give me nothing. and yes you can swap the entire list out in one move — iconic 🦋

🌈 mode 🌈

Tells you what mode you're currently in. Does not let you change it!

read-only. it's a vibe check, not a settings menu. look but don't touch 💀

---

and that's the whole page, bestie ✨ this was perl v5.42.0, dated 2025-07-25, from the fine folks at Tie::Ha...ltiValue(3) — mwah, go forth and store multiple values per key, you absolute legend 💖🎀🦋💅