1Hash::MoreUtils(3)    User Contributed Perl Documentation   Hash::MoreUtils(3)
2
3
4

NAME

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

SYNOPSIS

9         use Hash::MoreUtils qw(:all);
10
11         my %h = (foo => "bar", FOO => "BAR", true => 1, false => 0);
12         my %s = slice \%h, qw(true false); # (true => 1, false => 0)
13         my %f = slice_false \%h; # (false => 0)
14         my %u = slice_grep { $_ =~ m/^[A-Z]/ }, \%h; # (FOO => "BAR")
15
16         my %r = safe_reverse \%h; # (bar => "foo", BAR => "FOO", 0 => "false", 1 => "true")
17

DESCRIPTION

19       Similar to List::MoreUtils, "Hash::MoreUtils" contains trivial but
20       commonly-used functionality for hashes. The primary focus for the
21       moment is providing a common API - speeding up by XS is far away at the
22       moment.
23

FUNCTIONS

25   "slice" HASHREF[, LIST]
26       Returns a hash containing the (key, value) pair for every key in LIST.
27
28       If no "LIST" is given, all keys are assumed as "LIST".
29
30   "slice_def" HASHREF[, LIST]
31       As "slice", but only includes keys whose values are defined.
32
33       If no "LIST" is given, all keys are assumed as "LIST".
34
35   "slice_exists" HASHREF[, LIST]
36       As "slice" but only includes keys which exist in the hashref.
37
38       If no "LIST" is given, all keys are assumed as "LIST".
39
40   "slice_without" HASHREF[, LIST ]
41       As "slice" but without any (key/value) pair whose key is in LIST.
42
43       If no "LIST" is given, in opposite to slice an empty list is assumed,
44       thus nothing will be deleted.
45
46   "slice_missing" HASHREF[, LIST]
47       Returns a HASH containing the (key => undef) pair for every "LIST"
48       element (as key) that does not exist hashref.
49
50       If no "LIST" is given there are obviously no non-existent keys in
51       "HASHREF" so the returned HASH is empty.
52
53   "slice_notdef" HASHREF[, LIST]
54       Searches for undefined slices with the given "LIST" elements as keys in
55       the given "HASHREF".  Returns a "HASHREF" containing the slices (key ->
56       undef) for every undefined item.
57
58       To search for undefined slices "slice_notdef" needs a "LIST" with items
59       to search for (as keys). If no "LIST" is given it returns an empty
60       "HASHREF" even when the given "HASHREF" contains undefined slices.
61
62   "slice_true" HASHREF[, LIST]
63       A special "slice_grep" which returns only those elements of the hash
64       which's values evaluates to "TRUE".
65
66       If no "LIST" is given, all keys are assumed as "LIST".
67
68   "slice_false" HASHREF[, LIST]
69       A special "slice_grep" which returns only those elements of the hash
70       which's values evaluates to "FALSE".
71
72       If no "LIST" is given, all keys are assumed as "LIST".
73
74   "slice_grep" BLOCK, HASHREF[, LIST]
75       As "slice", with an arbitrary condition.
76
77       If no "LIST" is given, all keys are assumed as "LIST".
78
79       Unlike "grep", the condition is not given aliases to elements of
80       anything.  Instead, %_ is set to the contents of the hashref, to avoid
81       accidentally auto-vivifying when checking keys or values.  Also,
82       'uninitialized' warnings are turned off in the enclosing scope.
83
84   "slice_map" HASHREF[, MAP]
85       Returns a hash containing the (key, value) pair for every key in "MAP".
86
87       If no "MAP" is given, all keys of "HASHREF" are assumed mapped to
88       themselves.
89
90   "slice_def_map" HASHREF[, MAP]
91       As "slice_map", but only includes keys whose values are defined.
92
93       If no "MAP" is given, all keys of "HASHREF" are assumed mapped to
94       themselves.
95
96   "slice_exists_map" HASHREF[, MAP]
97       As "slice_map" but only includes keys which exist in the hashref.
98
99       If no "MAP" is given, all keys of "HASHREF" are assumed mapped to
100       themselves.
101
102   "slice_missing_map" HASHREF[, MAP]
103       As "slice_missing" but checks for missing keys (of "MAP") and map to
104       the value (of "MAP") as key in the returned HASH.  The slices of the
105       returned "HASHREF" are always undefined.
106
107       If no "MAP" is given, "slice_missing" will be used on "HASHREF" which
108       will return an empty HASH.
109
110   "slice_notdef_map" HASHREF[, MAP]
111       As "slice_notdef" but checks for undefined keys (of "MAP") and map to
112       the value (of "MAP") as key in the returned HASH.
113
114       If no "MAP" is given, "slice_notdef" will be used on "HASHREF" which
115       will return an empty HASH.
116
117   "slice_true_map" HASHREF[, MAP]
118       As "slice_map", but only includes pairs whose values are "TRUE".
119
120       If no "MAP" is given, all keys of "HASHREF" are assumed mapped to
121       themselves.
122
123   "slice_false_map" HASHREF[, MAP]
124       As "slice_map", but only includes pairs whose values are "FALSE".
125
126       If no "MAP" is given, all keys of "HASHREF" are assumed mapped to
127       themselves.
128
129   "slice_grep_map" BLOCK, HASHREF[, MAP]
130       As "slice_map", with an arbitrary condition.
131
132       If no "MAP" is given, all keys of "HASHREF" are assumed mapped to
133       themselves.
134
135       Unlike "grep", the condition is not given aliases to elements of
136       anything.  Instead, %_ is set to the contents of the hashref, to avoid
137       accidentally auto-vivifying when checking keys or values.  Also,
138       'uninitialized' warnings are turned off in the enclosing scope.
139
140   "hashsort" [BLOCK,] HASHREF
141         my @array_of_pairs  = hashsort \%hash;
142         my @pairs_by_length = hashsort sub { length($a) <=> length($b) }, \%hash;
143
144       Returns the (key, value) pairs of the hash, sorted by some property of
145       the keys.  By default (if no sort block given), sorts the keys with
146       "cmp".
147
148       I'm not convinced this is useful yet.  If you can think of some way it
149       could be more so, please let me know.
150
151   "safe_reverse" [BLOCK,] HASHREF
152         my %dup_rev = safe_reverse \%hash
153
154         sub croak_dup {
155             my ($k, $v, $r) = @_;
156             exists( $r->{$v} ) and
157               croak "Cannot safe reverse: $v would be mapped to both $k and $r->{$v}";
158             $v;
159         };
160         my %easy_rev = safe_reverse \&croak_dup, \%hash
161
162       Returns safely reversed hash (value, key pairs of original hash). If no
163       "BLOCK" is given, following routine will be used:
164
165         sub merge_dup {
166             my ($k, $v, $r) = @_;
167             return exists( $r->{$v} )
168                    ? ( ref($r->{$v}) ? [ @{$r->{$v}}, $k ] : [ $r->{$v}, $k ] )
169                    : $k;
170         };
171
172       The "BLOCK" will be called with 3 arguments:
173
174       "key"   The key from the "( key, value )" pair in the original hash
175
176       "value" The value from the "( key, value )" pair in the original hash
177
178       "ref-hash"
179               Reference to the reversed hash (read-only)
180
181       The "BLOCK" is expected to return the value which will used for the
182       resulting hash.
183

AUTHOR

185       Hans Dieter Pearcey, "<hdp@cpan.org>", Jens Rehsack,
186       "<rehsack@cpan.org>"
187

BUGS

189       Please report any bugs or feature requests to
190       "bug-hash-moreutils@rt.cpan.org", or through the web interface at
191       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Hash-MoreUtils>.  I
192       will be notified, and then you'll automatically be notified of progress
193       on your bug as I make changes.
194

SUPPORT

196       You can find documentation for this module with the perldoc command.
197
198           perldoc Hash::MoreUtils
199
200       You can also look for information at:
201
202       •   RT: CPAN's request tracker
203
204           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Hash-MoreUtils>
205
206       •   AnnoCPAN: Annotated CPAN documentation
207
208           <http://annocpan.org/dist/Hash-MoreUtils>
209
210       •   CPAN Ratings
211
212           <http://cpanratings.perl.org/d/Hash-MoreUtils>
213
214       •   Search CPAN
215
216           <http://search.cpan.org/dist/Hash-MoreUtils/>
217

ACKNOWLEDGEMENTS

220       Copyright 2005 Hans Dieter Pearcey, all rights reserved.  Copyright
221       2010-2018 Jens Rehsack
222
223       This program is free software; you can redistribute it and/or modify it
224       under the terms of either: the GNU General Public License as published
225       by the Free Software Foundation; or the Artistic License.
226
227       See http://dev.perl.org/licenses/ for more information.
228
229
230
231perl v5.32.1                      2021-01-27                Hash::MoreUtils(3)
Impressum