1Hash::MoreUtils(3) User Contributed Perl Documentation Hash::MoreUtils(3)
2
6 Hash::MoreUtils - Provide the stuff missing in Hash::Util
7
9 use Hash::MoreUtils qw(:all);
10 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 my %r = safe_reverse \%h; # (bar => "foo", BAR => "FOO", 0 => "false", 1 => "true")
17
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
25 "slice" HASHREF[, LIST]
26 Returns a hash containing the (key, value) pair for every key in LIST.
27 If no "LIST" is given, all keys are assumed as "LIST".
29 "slice_def" HASHREF[, LIST]
31 As "slice", but only includes keys whose values are defined.
32 If no "LIST" is given, all keys are assumed as "LIST".
34 "slice_exists" HASHREF[, LIST]
36 As "slice" but only includes keys which exist in the hashref.
37 If no "LIST" is given, all keys are assumed as "LIST".
39 "slice_without" HASHREF[, LIST ]
41 As "slice" but without any (key/value) pair whose key is in LIST.
42 If no "LIST" is given, in opposite to slice an empty list is assumed,
44 thus nothing will be deleted.
45 "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 If no "LIST" is given there are obviously no non-existent keys in
51 "HASHREF" so the returned HASH is empty.
52 "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 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 "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 If no "LIST" is given, all keys are assumed as "LIST".
67 "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 If no "LIST" is given, all keys are assumed as "LIST".
73 "slice_grep" BLOCK, HASHREF[, LIST]
75 As "slice", with an arbitrary condition.
76 If no "LIST" is given, all keys are assumed as "LIST".
78 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 "slice_map" HASHREF[, MAP]
85 Returns a hash containing the (key, value) pair for every key in "MAP".
86 If no "MAP" is given, all keys of "HASHREF" are assumed mapped to
88 themselves.
89 "slice_def_map" HASHREF[, MAP]
91 As "slice_map", but only includes keys whose values are defined.
92 If no "MAP" is given, all keys of "HASHREF" are assumed mapped to
94 themselves.
95 "slice_exists_map" HASHREF[, MAP]
97 As "slice_map" but only includes keys which exist in the hashref.
98 If no "MAP" is given, all keys of "HASHREF" are assumed mapped to
100 themselves.
101 "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 If no "MAP" is given, "slice_missing" will be used on "HASHREF" which
108 will return an empty HASH.
109 "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 If no "MAP" is given, "slice_notdef" will be used on "HASHREF" which
115 will return an empty HASH.
116 "slice_true_map" HASHREF[, MAP]
118 As "slice_map", but only includes pairs whose values are "TRUE".
119 If no "MAP" is given, all keys of "HASHREF" are assumed mapped to
121 themselves.
122 "slice_false_map" HASHREF[, MAP]
124 As "slice_map", but only includes pairs whose values are "FALSE".
125 If no "MAP" is given, all keys of "HASHREF" are assumed mapped to
127 themselves.
128 "slice_grep_map" BLOCK, HASHREF[, MAP]
130 As "slice_map", with an arbitrary condition.
131 If no "MAP" is given, all keys of "HASHREF" are assumed mapped to
133 themselves.
134 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 "hashsort" [BLOCK,] HASHREF
141 my @array_of_pairs = hashsort \%hash;
142 my @pairs_by_length = hashsort sub { length($a) <=> length($b) }, \%hash;
143 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 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 "safe_reverse" [BLOCK,] HASHREF
152 my %dup_rev = safe_reverse \%hash
153 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 Returns safely reversed hash (value, key pairs of original hash). If no
163 "BLOCK" is given, following routine will be used:
164 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 The "BLOCK" will be called with 3 arguments:
173 "key" The key from the "( key, value )" pair in the original hash
175 "value" The value from the "( key, value )" pair in the original hash
177 "ref-hash"
179 Reference to the reversed hash (read-only)
180 The "BLOCK" is expected to return the value which will used for the
182 resulting hash.
183
185 Hans Dieter Pearcey, "<hdp@cpan.org>", Jens Rehsack,
186 "<rehsack@cpan.org>"
187
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
196 You can find documentation for this module with the perldoc command.
197 perldoc Hash::MoreUtils
199 You can also look for information at:
201 • RT: CPAN's request tracker
203 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Hash-MoreUtils>
205 • AnnoCPAN: Annotated CPAN documentation
207 <http://annocpan.org/dist/Hash-MoreUtils>
209 • CPAN Ratings
211 <http://cpanratings.perl.org/d/Hash-MoreUtils>
213 • Search CPAN
215 <http://search.cpan.org/dist/Hash-MoreUtils/>
217
220 Copyright 2005 Hans Dieter Pearcey, all rights reserved. Copyright
221 2010-2018 Jens Rehsack
222 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 See http://dev.perl.org/licenses/ for more information.
228perl v5.38.0 2023-07-20 Hash::MoreUtils(3)