# 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](https://metacpan.org/pod/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 [http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Hash-MoreUtils](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. # 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 [http://rt.cpan.org/NoAuth/Bugs.html?Dist=Hash-MoreUtils](http://rt.cpan.org/NoAuth/Bugs.html?Dist=Hash-MoreUtils) - AnnoCPAN: Annotated CPAN documentation [http://annocpan.org/dist/Hash-MoreUtils](http://annocpan.org/dist/Hash-MoreUtils) - CPAN Ratings [http://cpanratings.perl.org/d/Hash-MoreUtils](http://cpanratings.perl.org/d/Hash-MoreUtils) - Search CPAN [http://search.cpan.org/dist/Hash-MoreUtils/](http://search.cpan.org/dist/Hash-MoreUtils/) # 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.