1Hash::Util(3pm) Perl Programmers Reference Guide Hash::Util(3pm)
2
6 Hash::Util - A selection of general-utility hash subroutines
7
9 # Restricted hashes
10 use Hash::Util qw(
12 hash_seed all_keys
13 lock_keys unlock_keys
14 lock_value unlock_value
15 lock_hash unlock_hash
16 lock_keys_plus hash_locked
17 hidden_keys legal_keys
18 );
19 %hash = (foo => 42, bar => 23);
21 # Ways to restrict a hash
22 lock_keys(%hash);
23 lock_keys(%hash, @keyset);
24 lock_keys_plus(%hash, @additional_keys);
25 # Ways to inspect the properties of a restricted hash
27 my @legal = legal_keys(%hash);
28 my @hidden = hidden_keys(%hash);
29 my $ref = all_keys(%hash,@keys,@hidden);
30 my $is_locked = hash_locked(%hash);
31 # Remove restrictions on the hash
33 unlock_keys(%hash);
34 # Lock individual values in a hash
36 lock_value (%hash, 'foo');
37 unlock_value(%hash, 'foo');
38 # Ways to change the restrictions on both keys and values
40 lock_hash (%hash);
41 unlock_hash(%hash);
42 my $hashes_are_randomised = hash_seed() != 0;
44
46 "Hash::Util" and "Hash::Util::FieldHash" contain special functions for
47 manipulating hashes that don't really warrant a keyword.
48 "Hash::Util" contains a set of functions that support restricted
50 hashes. These are described in this document. "Hash::Util::FieldHash"
51 contains an (unrelated) set of functions that support the use of hashes
52 in inside-out classes, described in Hash::Util::FieldHash.
53 By default "Hash::Util" does not export anything.
55 Restricted hashes
57 5.8.0 introduces the ability to restrict a hash to a certain set of
58 keys. No keys outside of this set can be added. It also introduces
59 the ability to lock an individual key so it cannot be deleted and the
60 ability to ensure that an individual value cannot be changed.
61 This is intended to largely replace the deprecated pseudo-hashes.
63 lock_keys
65 unlock_keys
66 lock_keys(%hash);
67 lock_keys(%hash, @keys);
68 Restricts the given %hash's set of keys to @keys. If @keys is not
70 given it restricts it to its current keyset. No more keys can be
71 added. delete() and exists() will still work, but will not alter
72 the set of allowed keys. Note: the current implementation prevents
73 the hash from being bless()ed while it is in a locked state. Any
74 attempt to do so will raise an exception. Of course you can still
75 bless() the hash before you call lock_keys() so this shouldn't be a
76 problem.
77 unlock_keys(%hash);
79 Removes the restriction on the %hash's keyset.
81 Note that if any of the values of the hash have been locked they
83 will not be unlocked after this sub executes.
84 Both routines return a reference to the hash operated on.
86 lock_keys_plus
88 lock_keys_plus(%hash,@additional_keys)
89 Similar to "lock_keys()", with the difference being that the
91 optional key list specifies keys that may or may not be already in
92 the hash. Essentially this is an easier way to say
93 lock_keys(%hash,@additional_keys,keys %hash);
95 Returns a reference to %hash
97 lock_value
99 unlock_value
100 lock_value (%hash, $key);
101 unlock_value(%hash, $key);
102 Locks and unlocks the value for an individual key of a hash. The
104 value of a locked key cannot be changed.
105 Unless %hash has already been locked the key/value could be deleted
107 regardless of this setting.
108 Returns a reference to the %hash.
110 lock_hash
112 unlock_hash
113 lock_hash(%hash);
114 lock_hash() locks an entire hash, making all keys and values read-
116 only. No value can be changed, no keys can be added or deleted.
117 unlock_hash(%hash);
119 unlock_hash() does the opposite of lock_hash(). All keys and
121 values are made writable. All values can be changed and keys can
122 be added and deleted.
123 Returns a reference to the %hash.
125 lock_hash_recurse
127 unlock_hash_recurse
128 lock_hash_recurse(%hash);
129 lock_hash() locks an entire hash and any hashes it references
131 recursively, making all keys and values read-only. No value can be
132 changed, no keys can be added or deleted.
133 Only recurses into hashes that are referenced by another hash. Thus
135 a Hash of Hashes (HoH) will all be restricted, but a Hash of Arrays
136 of Hashes (HoAoH) will only have the top hash restricted.
137 unlock_hash_recurse(%hash);
139 unlock_hash_recurse() does the opposite of lock_hash_recurse().
141 All keys and values are made writable. All values can be changed
142 and keys can be added and deleted. Identical recursion restrictions
143 apply as to lock_hash_recurse().
144 Returns a reference to the %hash.
146 hash_unlocked
148 hash_unlocked(%hash) and print "Hash is unlocked!\n";
149 Returns true if the hash and its keys are unlocked.
151 legal_keys
153 my @keys = legal_keys(%hash);
154 Returns the list of the keys that are legal in a restricted hash.
156 In the case of an unrestricted hash this is identical to calling
157 keys(%hash).
158 hidden_keys
160 my @keys = hidden_keys(%hash);
161 Returns the list of the keys that are legal in a restricted hash
163 but do not have a value associated to them. Thus if 'foo' is a
164 "hidden" key of the %hash it will return false for both "defined"
165 and "exists" tests.
166 In the case of an unrestricted hash this will return an empty list.
168 NOTE this is an experimental feature that is heavily dependent on
170 the current implementation of restricted hashes. Should the
171 implementation change, this routine may become meaningless, in
172 which case it will return an empty list.
173 all_keys
175 all_keys(%hash,@keys,@hidden);
176 Populates the arrays @keys with the all the keys that would pass an
178 "exists" tests, and populates @hidden with the remaining legal keys
179 that have not been utilized.
180 Returns a reference to the hash.
182 In the case of an unrestricted hash this will be equivalent to
184 $ref = do {
186 @keys = keys %hash;
187 @hidden = ();
188 \%hash
189 };
190 NOTE this is an experimental feature that is heavily dependent on
192 the current implementation of restricted hashes. Should the
193 implementation change this routine may become meaningless in which
194 case it will behave identically to how it would behave on an
195 unrestricted hash.
196 hash_seed
198 my $hash_seed = hash_seed();
199 hash_seed() returns the seed number used to randomise hash
201 ordering. Zero means the "traditional" random hash ordering, non-
202 zero means the new even more random hash ordering introduced in
203 Perl 5.8.1.
204 Note that the hash seed is sensitive information: by knowing it one
206 can craft a denial-of-service attack against Perl code, even
207 remotely, see "Algorithmic Complexity Attacks" in perlsec for more
208 information. Do not disclose the hash seed to people who don't
209 need to know it. See also "PERL_HASH_SEED_DEBUG" in perlrun.
210 hv_store
212 my $sv = 0;
213 hv_store(%hash,$key,$sv) or die "Failed to alias!";
214 $hash{$key} = 1;
215 print $sv; # prints 1
216 Stores an alias to a variable in a hash instead of copying the
218 value.
219 Operating on references to hashes.
221 Most subroutines documented in this module have equivalent versions
222 that operate on references to hashes instead of native hashes. The
223 following is a list of these subs. They are identical except in name
224 and in that instead of taking a %hash they take a $hashref, and
225 additionally are not prototyped.
226 lock_ref_keys
228 unlock_ref_keys
229 lock_ref_keys_plus
230 lock_ref_value
231 unlock_ref_value
232 lock_hashref
233 unlock_hashref
234 lock_hashref_recurse
235 unlock_hashref_recurse
236 hash_ref_unlocked
237 legal_ref_keys
238 hidden_ref_keys
239
241 Note that the trapping of the restricted operations is not atomic: for
242 example
243 eval { %hash = (illegal_key => 1) }
245 leaves the %hash empty rather than with its original contents.
247
249 The interface exposed by this module is very close to the current
250 implementation of restricted hashes. Over time it is expected that this
251 behavior will be extended and the interface abstracted further.
252
254 Michael G Schwern <schwern@pobox.com> on top of code by Nick Ing-
255 Simmons and Jeffrey Friedl.
256 hv_store() is from Array::RefElem, Copyright 2000 Gisle Aas.
258 Additional code by Yves Orton.
260
262 Scalar::Util, List::Util and "Algorithmic Complexity Attacks" in
263 perlsec.
264 Hash::Util::FieldHash.
266perl v5.16.3 2013-03-04 Hash::Util(3pm)