--- name: "Hash::MoreUtils" section: "3pm" platform: "linux" package: "libhash-moreutils-perl" version: "0.06-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Hash::MoreUtils" --- # Hash::MoreUtils(3pm) Provide the stuff missing in Hash::Util ## NAME Hash::MoreUtils - Provide the stuff missing in Hash::Util ## SYNOPSIS ``` 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") ``` ## DESCRIPTION Similar to List::MoreUtils, `"Hash::MoreUtils"` contains trivial but commonly-used functionality for hashes. The primary focus for the moment is providing a common API - speeding up by XS is far away at the moment. ## FUNCTIONS ### "slice" HASHREF\[, LIST\] Returns a hash containing the (key, value) pair for every key in LIST. If no `"LIST"` is given, all keys are assumed as `"LIST"`. ### "slice\_def" HASHREF\[, LIST\] As `"slice"`, but 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 only includes keys which 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. If no `"LIST"` is given, in opposite to slice an empty list is assumed, thus 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 hashref. If no `"LIST"` is given there are obviously no non-existent keys in `"HASHREF"` so the returned HASH is empty. ### "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. ### "slice\_true" HASHREF\[, LIST\] A special `"slice_grep"` which returns only those elements of the hash which's values evaluates 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 which's values evaluates to `"FALSE"`. If no `"LIST"` is given, all keys are assumed as `"LIST"`. ### "slice\_grep" BLOCK, HASHREF\[, LIST\] As `"slice"`, with an arbitrary condition. 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, to avoid accidentally auto-vivifying when checking keys or values. Also, 'uninitialized' warnings are turned off in the enclosing scope. ### "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. ### "slice\_def\_map" HASHREF\[, MAP\] As `"slice_map"`, but 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 checks for missing keys (of `"MAP"`) and map 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 checks for undefined keys (of `"MAP"`) and map 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. 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, to 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 given), sorts the keys with `"cmp"`. 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 safely reversed hash (value, key pairs of original hash). If no `"BLOCK"` is given, 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 used for the resulting hash. ## AUTHOR Hans Dieter Pearcey, `""`, Jens Rehsack, `""` ## BUGS Please report any bugs or feature requests to `"bug-hash-moreutils@rt.cpan.org"`, or through the web interface at \. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. ## SUPPORT You can find documentation for this module with the perldoc command. ``` perldoc Hash::MoreUtils ``` You can also look for information at: - • RT: CPAN's request tracker \ - • AnnoCPAN: Annotated CPAN documentation \ - • CPAN Ratings \ - • Search CPAN \ ## ACKNOWLEDGEMENTS ## COPYRIGHT & LICENSE 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.