NAME

       Hash::MoreUtils - Provide the stuff missing in Hash::Util

SYNOPSIS

         use Hash::MoreUtils qw(slice slice_def slice_exists slice_grep
                                hashsort
                               );

DESCRIPTION

       Similar to "List::MoreUtils", "Hash::MoreUtils" contains trivial but commonly-used functionality for
       hashes.

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_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 theirself.

   "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 theirself.

   "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 theirself.

   "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 theirself.

       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 = save_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, "<hdp@cpan.org>", Jens Rehsack, "<rehsack@cpan.org>"

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.

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>

       •   AnnoCPAN: Annotated CPAN documentation

           <http://annocpan.org/dist/Hash-MoreUtils>

       •   CPAN Ratings

           <http://cpanratings.perl.org/d/Hash-MoreUtils>

       •   Search CPAN

           <http://search.cpan.org/dist/Hash-MoreUtils/>

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

       Copyright 2005 Hans Dieter Pearcey, all rights reserved.  Copyright 2010-2013 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.