Hash::MultiValue(3)

💖 Hash::MultiValue(3) — the bestie edition 💖

okay so bestie, this is the manual page for Hash::MultiValue(3), and it's literally about storing multiple values per key without your code having a meltdown. periodt. 💅

✨ NAME ✨

Hash::MultiValue — Store multiple values per key. That's the whole vibe. 🎀

🌸 SYNOPSIS 🌸

  use Hash::MultiValue;

  my $hash = Hash::MultiValue->new(
      foo => 'a',
      foo => 'b',
      bar => 'baz',
  );

  # $hash is an object, but can be used as a hashref and DWIMs!
  my $foo = $hash->{foo};         # 'b' (the last entry)
  my $foo = $hash->get('foo');    # 'b' (always, regardless of context)
  my @foo = $hash->get_all('foo'); # ('a', 'b')

  keys %$hash; # ('foo', 'bar')    not guaranteed to be ordered
  $hash->keys; # ('foo', 'foo', 'bar') guaranteed to be ordered

🦋 DESCRIPTION 🦋

Hash::MultiValue is an object (and a plain hash reference) that may contain multiple values per key, inspired by MultiDict of WebOb. iykyk. 💜

💭 RATIONALE 💭

In a typical web application, the request parameters (a.k.a CGI parameters) can be single value or multi values. Using CGI.pm style param is one way to deal with this problem (and it is good, as long as you're aware of its list context gotcha), but there's another approach to convert parameters into a hash reference, like Catalyst's $c->req->parameters does, and it sucks. 😭

Why? Because the value could be just a scalar if there is one value and an array ref if there are multiple, depending on user input rather than how you code it. So your code should always be like this to be defensive:

  my $p = $c->req->parameters;
  my @maybe_multi = ref $p->{m} eq 'ARRAY' ? @{$p->{m}} : ($p->{m});
  my $must_single = ref $p->{m} eq 'ARRAY' ? $p->{m}->[0] : $p->{m};

Otherwise you'll get a random runtime exception of Can't use string as an ARRAY ref or get stringified array ARRAY(0xXXXXXXXXX) as a string, depending on user input and that is miserable and insecure. not cute, not slay, genuinely unsafe. 💀

This module provides a solution to this by making it behave like a single value hash reference, but also has an API to get multiple values on demand, explicitly. main character energy. 👑

🧚 HOW THIS WORKS 🧚

The object returned by new is a blessed hash reference that contains the last entry of the same key if there are multiple values, but it also keeps the original pair state in the object tracker (a.k.a inside out objects) and allows you to access the original pairs and multiple values via the method calls, such as get_all or flatten.

This module does not use tie or overload and is quite fast. ⚡

Yes, there is Tie::Hash::MultiValue and this module tries to solve exactly the same problem, but using a different implementation. same goal, different fit. 🎀

🛠️ UPDATING CONTENTS 🛠️

When you update the content of the hash, DO NOT UPDATE using the hash reference interface: this won't write through to the tracking object.

  my $hash = Hash::MultiValue->new(...);

  # WRONG
  $hash->{foo} = 'bar';
  delete $hash->{foo};

  # Correct
  $hash->add(foo => 'bar');
  $hash->remove('foo');

See below for the list of updating methods. 👇

💅 METHODS 💅

new

  $hash = Hash::MultiValue->new(@pairs);

Creates a new object that can be treated as a plain hash reference as well. iconic behavior. ✨

get

  $value = $hash->get($key);
  $value = $hash->{$key};

Returns a single value for the given $key. If there are multiple values, the last one (not first one) is returned. See below for why. 👀

Note that this always returns the single element as a scalar, regardless of its context, unlike CGI.pm's param method etc. No surprises, no context gremlins. 🫶

get_one

  $value = $hash->get_one($key);

Returns a single value for the given $key. This method croaks if there is no value or multiple values associated with the key, so you should wrap it with eval or modules like Try::Tiny. drama is built in, but at least it's explicit. 😭

get_all

  @values = $hash->get_all($key);

Returns a list of values for the given $key. This method always returns a list regardless of its context. If there is no value attached, the result will be an empty list. clean, predictable, slay. 🌈

keys

  @keys = $hash->keys;

Returns a list of all keys, including duplicates (see the example in the SYNOPSIS). Duplicates are literally the point, bestie. 💅

If you want only unique keys, use keys %$hash, as normal.

values

  @values = $hash->values;

Returns a list of all values, in the same order as $hash->keys. Order matters, and this method knows it. 🎀

set

  $hash->set($key [, $value ... ]);

Changes the stored value(s) of the given $key. This removes or adds pairs as necessary to store the new list but otherwise preserves order of existing pairs. $hash->{$key} is updated to point to the last value. controlled chaos. 🦋

add

  $hash->add($key, $value [, $value ... ]);

Appends a new value to the given $key. This updates the value of $hash->{$key} as well so it always points to the last value. 👑

remove

  $hash->remove($key);

Removes a key and associated values for the given $key. bye bye key, bye bye values. 👋

clear

  $hash->clear;

Clears the hash to be an empty hash reference. clean slate energy. ✨

flatten

  @pairs = $hash->flatten;

Gets pairs of keys and values. This should be exactly the same pairs which are given to new method unless you updated the data. original pairs, preserved. 🫶

each

  $hash->each($code);

  # e.g.
  $hash->each(sub { print "$_[0] = $_[1]\n" });

Calls $code once for each ($key, $value) pair. This is a more convenient alternative to calling flatten and then iterating over it two items at a time.

Inside $code, $_ contains the current iteration through the loop, starting at 0. For example:

  $hash = Hash::MultiValue->new(a => 1, b => 2, c => 3, a => 4);

  $hash->each(sub { print "$_: $_[0] = $_[1]\n" });
  # 0: a = 1
  # 1: b = 2
  # 2: c = 3
  # 3: a = 4

Be careful not to change @_ inside your coderef! It will update the tracking object but not the plain hash. In the future, this limitation may be removed. do not touch the @_, bestie. 😭

clone

  $new = $hash->clone;

Creates a new Hash::MultiValue object that represents the same data, but obviously not sharing the reference. It's identical to:

  $new = Hash::MultiValue->new($hash->flatten);

as_hashref

  $copy = $hash->as_hashref;

Creates a new plain (unblessed) hash reference where a value is a single scalar. It's identical to:

  $copy = +{%$hash};

as_hashref_mixed, mixed

  $mixed = $hash->as_hashref_mixed;
  $mixed = $hash->mixed;

Creates a new plain (unblessed) hash reference where the value is a single scalar, or an array ref when there are multiple values for a same key. Handy to create a hash reference that is often used in web application frameworks request objects such as Catalyst. This method does exactly the opposite of from_mixed. 🧚

as_hashref_multi, multi

  $multi = $hash->as_hashref_multi;
  $multi = $hash->multi;

Creates a new plain (unblessed) hash reference where values are all array references, regardless of there are single or multiple values for a same key. everything is an array now. 💅

from_mixed

  $hash = Hash::MultiValue->from_mixed({
      foo => [ 'a', 'b' ],
      bar => 'c',
  });

Creates a new object out of a hash reference where the value is single or an array ref depending on the number of elements. Handy to convert from those request objects used in web frameworks such as Catalyst. This method does exactly the opposite of as_hashref_mixed. 🦋

🤔 WHY LAST NOT FIRST? 🤔

You might wonder why this module uses the last value of the same key instead of first. There's no strong reasoning on this decision since one is as arbitrary as the other, but this is more consistent to what Perl does:

  sub x {
      return ('a', 'b', 'c');
  }

  my $x = x(); # $x = 'c'

  my %a = ( a => 1 );
  my %b = ( a => 2 );

  my %m = (%a, %b); # $m{a} = 2

When perl gets a list in a scalar context it gets the last entry. Also if you merge hashes having a same key, the last one wins. last one standing, periodt. 👑

🧐 NOTES ON ref 🧐

If you pass this MultiValue hash object to some upstream functions that you can't control and does things like:

  if (ref $args eq 'HASH') {
      ...
  }

because this is a blessed hash reference it doesn't match and would fail. To avoid that you should call as_hashref to get a finalized (= non-blessed) hash reference. unbless it before you send it. ✨

You can also use UNIVERSAL::ref to make it work magically:

  use UNIVERSAL::ref;    # before loading Hash::MultiValue
  use Hash::MultiValue;

and then all ref calls to Hash::MultiValue objects will return HASH. magic, but make it Perl. 🪄

🧵 THREAD SAFETY 🧵

Prior to version 0.09, this module wasn't safe in a threaded environment, including win32 fork() emulation. Versions newer than 0.09 is considered thread safe. thread-safe glow-up achieved. 💅

👑 AUTHOR 👑

• Tatsuhiko Miyagawa <miyagawa@bulknews.net>
• Aristotle Pagaltzis
• Hans Dieter Pearcey

Thanks to Michael Peters for the suggestion to use inside-out objects instead of tie. 🫶

📜 LICENSE 📜

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

👀 SEE ALSO 👀

• <http://pythonpaste.org/webob/#multidict>
• Tie::Hash::MultiValue

---

✨ cute sign-off: this page is from perl v5.42.0, dated 2015-04-14, and it's the Hash::MultiValue(3) manual. bye bestie, stay hydrated and may your hashes never collapse into a stringified ARRAY(0xXXXXXXXXX) 😭💖