Hash::MoreUtils(3pm)

📦
version 0.06 · 5 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

Hash::MoreUtils 💖

okay bestie, so this is Hash::MoreUtils, a lil Perl module from the User Contributed Perl Documentation collection, and it's literally here to give you all the hash stuff that Hash::Util forgot to include. we're doing group-chat vibes but the facts are ✨sacred✨, so buckle up 🎀

✨ NAME ✨

Hash::MoreUtils — it's giving you all the stuff missing in Hash::Util, no cap 🫶

🦋 SYNOPSIS 🦋

okay so here's the whole vibe in one glance:

use Hash::MoreUtils qw(:all);

my %h = (foo => "bar", FOO => "BAR", true => 1, false => 0);
my %s = slice \%h, qw(true false); # (true => 1, false => 0)
my %f = slice_false \%h; # (false => 0)
my %u = slice_grep { $_ =~ m/^[A-Z]/ }, \%h; # (FOO => "BAR")

my %r = safe_reverse \%h; # (bar => "foo", BAR => "FOO", 0 => "false", 1 => "true")

see how easy that was? main character energy fr fr 💅

🌸 DESCRIPTION 🌸

So, just like its bestie List::MoreUtils, Hash::MoreUtils is packed with trivial-but-constantly-needed hash functionality. The way that the primary focus right now is giving you a common API — speeding things up with XS is, like, far away at the moment 🙈. So we're keeping it pure Perl, and honestly? iconic.

👑 FUNCTIONS 👑

every single one, no skips, we don't do that here 💖

slice HASHREF[, LIST]

Hands you back a hash with the (key, value) pair for every key that's in LIST.

If you don't give it a LIST, then all keys are assumed as LIST. all of them. the whole squad. 🫶

slice_def HASHREF[, LIST]

Same energy as slice, except it only includes keys whose values are defined.

If no LIST is given, all keys are assumed as LIST.

slice_exists HASHREF[, LIST]

As slice, but it only includes keys which actually exist in the hashref.

If no LIST is given, all keys are assumed as LIST.

slice_without HASHREF[, LIST ]

As slice, but without any (key/value) pair whose key is in LIST. it's the "not invited to the party" version 💀

If no LIST is given — and this is the opposite of slice, okay, pay attention bestie — an empty list is assumed, so nothing will be deleted.

slice_missing HASHREF[, LIST]

Returns a HASH containing the (key => undef) pair for every LIST element (as key) that does not exist in the hashref.

If no LIST is given, there are obviously no non-existent keys in HASHREF, so the returned HASH is empty. makes sense, it's giving logic ✨

slice_notdef HASHREF[, LIST]

Searches for undefined slices with the given LIST elements as keys in the given HASHREF. Returns a HASHREF containing the slices (key -> undef) for every undefined item.

To search for undefined slices, slice_notdef needs a LIST with items to search for (as keys). If no LIST is given it returns an empty HASHREF, even when the given HASHREF contains undefined slices. no list, no search, periodt.

slice_true HASHREF[, LIST]

A special slice_grep which returns only those elements of the hash whose values evaluate to TRUE.

If no LIST is given, all keys are assumed as LIST.

slice_false HASHREF[, LIST]

A special slice_grep which returns only those elements of the hash whose values evaluate to FALSE.

If no LIST is given, all keys are assumed as LIST.

slice_grep BLOCK, HASHREF[, LIST]

As slice, with an arbitrary condition. you bring the vibe check, we bring the hash 🧚

If no LIST is given, all keys are assumed as LIST.

Unlike grep, the condition is not given aliases to elements of anything. Instead, %_ is set to the contents of the hashref, so you avoid accidentally auto-vivifying when checking keys or values. Also, 'uninitialized' warnings are turned off in the enclosing scope. thoughtful, right? 💅

slice_map HASHREF[, MAP]

Returns a hash containing the (key, value) pair for every key in MAP.

If no MAP is given, all keys of HASHREF are assumed mapped to themselves. self-love fr 💖

slice_def_map HASHREF[, MAP]

As slice_map, but it only includes keys whose values are defined.

If no MAP is given, all keys of HASHREF are assumed mapped to themselves.

slice_exists_map HASHREF[, MAP]

As slice_map, but only includes keys which exist in the hashref.

If no MAP is given, all keys of HASHREF are assumed mapped to themselves.

slice_missing_map HASHREF[, MAP]

As slice_missing, but it checks for missing keys (of MAP) and maps to the value (of MAP) as key in the returned HASH. The slices of the returned HASHREF are always undefined.

If no MAP is given, slice_missing will be used on HASHREF, which will return an empty HASH.

slice_notdef_map HASHREF[, MAP]

As slice_notdef, but it checks for undefined keys (of MAP) and maps to the value (of MAP) as key in the returned HASH.

If no MAP is given, slice_notdef will be used on HASHREF, which will return an empty HASH.

slice_true_map HASHREF[, MAP]

As slice_map, but only includes pairs whose values are TRUE.

If no MAP is given, all keys of HASHREF are assumed mapped to themselves.

slice_false_map HASHREF[, MAP]

As slice_map, but only includes pairs whose values are FALSE.

If no MAP is given, all keys of HASHREF are assumed mapped to themselves.

slice_grep_map BLOCK, HASHREF[, MAP]

As slice_map, with an arbitrary condition. bring your own filter, bestie ✨

If no MAP is given, all keys of HASHREF are assumed mapped to themselves.

Unlike grep, the condition is not given aliases to elements of anything. Instead, %_ is set to the contents of the hashref, so you avoid accidentally auto-vivifying when checking keys or values. Also, 'uninitialized' warnings are turned off in the enclosing scope.

hashsort [BLOCK,] HASHREF

my @array_of_pairs  = hashsort \%hash;
my @pairs_by_length = hashsort sub { length($a) <=> length($b) }, \%hash;

Returns the (key, value) pairs of the hash, sorted by some property of the keys. By default (if no sort block is given), it sorts the keys with cmp.

Honestly? I'm not convinced this is useful yet. If you can think of some way it could be more so, please let me know. 🥺

safe_reverse [BLOCK,] HASHREF

my %dup_rev = safe_reverse \%hash

sub croak_dup {
    my ($k, $v, $r) = @_;
    exists( $r->{$v} ) and
      croak "Cannot safe reverse: $v would be mapped to both $k and $r->{$v}";
    $v;
};
my %easy_rev = safe_reverse \&croak_dup, \%hash

Returns a safely reversed hash (value, key pairs of the original hash). If no BLOCK is given, the following routine will be used:

sub merge_dup {
    my ($k, $v, $r) = @_;
    return exists( $r->{$v} )
           ? ( ref($r->{$v}) ? [ @{$r->{$v}}, $k ] : [ $r->{$v}, $k ] )
           : $k;
};

The BLOCK will be called with 3 arguments:

  • key — The key from the ( key, value ) pair in the original hash
  • value — The value from the ( key, value ) pair in the original hash
  • ref-hash — Reference to the reversed hash (read-only)

The BLOCK is expected to return the value which will be used for the resulting hash. that's the whole dealio 💜

🫶 AUTHOR 🫶

Hans Dieter Pearcey, "<hdp@cpan.org>", and Jens Rehsack, "<rehsack@cpan.org>". legends, honestly 👑

💀 BUGS 💀

Please report any bugs or feature requests to "bug-hash-moreutils@rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Hash-MoreUtils>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. so like, we're both in the loop, bestie 🦋

🌈 SUPPORT 🌈

You can find documentation for this module with the perldoc command.

perldoc Hash::MoreUtils

You can also look for information at:

🎀 ACKNOWLEDGEMENTS 🎀

...okay so this section is literally empty. nothing here. a blank canvas. we love a mystery 💅✨

Copyright 2005 Hans Dieter Pearcey, all rights reserved. Copyright 2010-2018 Jens Rehsack.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See <http://dev.perl.org/licenses/> for more information.

and that's the whole page, bestie 🍓 this was Hash::MoreUtils(3pm) from perl v5.36.0, dated 2022-12-06 — go forth and slice your hashes, you absolute icon 💖🦋✨

📦 where this page comes from