Hash::Util(3pm)

1Hash::Util(3pm)        Perl Programmers Reference Guide        Hash::Util(3pm)
2
3
4

NAME

6       Hash::Util - A selection of general-utility hash subroutines
7

SYNOPSIS

9         use Hash::Util qw(lock_keys   unlock_keys
10                           lock_value  unlock_value
11                           lock_hash   unlock_hash
12                           hash_seed);
13
14         %hash = (foo => 42, bar => 23);
15         lock_keys(%hash);
16         lock_keys(%hash, @keyset);
17         unlock_keys(%hash);
18
19         lock_value  (%hash, 'foo');
20         unlock_value(%hash, 'foo');
21
22         lock_hash  (%hash);
23         unlock_hash(%hash);
24
25         my $hashes_are_randomised = hash_seed() != 0;
26

DESCRIPTION

28       "Hash::Util" contains special functions for manipulating hashes that
29       don't really warrant a keyword.
30
31       By default "Hash::Util" does not export anything.
32
33       Restricted hashes
34
35       5.8.0 introduces the ability to restrict a hash to a certain set of
36       keys.  No keys outside of this set can be added.  It also introduces
37       the ability to lock an individual key so it cannot be deleted and the
38       value cannot be changed.
39
40       This is intended to largely replace the deprecated pseudo-hashes.
41
42       lock_keys
43       unlock_keys
44             lock_keys(%hash);
45             lock_keys(%hash, @keys);
46
47           Restricts the given %hash's set of keys to @keys.  If @keys is not
48           given it restricts it to its current keyset.  No more keys can be
49           added. delete() and exists() will still work, but will not alter
50           the set of allowed keys. Note: the current implementation prevents
51           the hash from being bless()ed while it is in a locked state. Any
52           attempt to do so will raise an exception. Of course you can still
53           bless() the hash before you call lock_keys() so this shouldn't be a
54           problem.
55
56             unlock_keys(%hash);
57
58           Removes the restriction on the %hash's keyset.
59
60       lock_value
61       unlock_value
62             lock_value  (%hash, $key);
63             unlock_value(%hash, $key);
64
65           Locks and unlocks an individual key of a hash.  The value of a
66           locked key cannot be changed.
67
68           %hash must have already been locked for this to have useful effect.
69
70       lock_hash
71       unlock_hash
72               lock_hash(%hash);
73
74           lock_hash() locks an entire hash, making all keys and values read‐
75           only.  No value can be changed, no keys can be added or deleted.
76
77               unlock_hash(%hash);
78
79           unlock_hash() does the opposite of lock_hash().  All keys and val‐
80           ues are made read/write.  All values can be changed and keys can be
81           added and deleted.
82
83       hash_seed
84               my $hash_seed = hash_seed();
85
86           hash_seed() returns the seed number used to randomise hash order‐
87           ing.  Zero means the "traditional" random hash ordering, non-zero
88           means the new even more random hash ordering introduced in Perl
89           5.8.1.
90
91           Note that the hash seed is sensitive information: by knowing it one
92           can craft a denial-of-service attack against Perl code, even
93           remotely, see "Algorithmic Complexity Attacks" in perlsec for more
94           information.  Do not disclose the hash seed to people who don't
95           need to know it.  See also "PERL_HASH_SEED_DEBUG" in perlrun.
96

CAVEATS

98       Note that the trapping of the restricted operations is not atomic: for
99       example
100
101           eval { %hash = (illegal_key => 1) }
102
103       leaves the %hash empty rather than with its original contents.
104

AUTHOR

106       Michael G Schwern <schwern@pobox.com> on top of code by Nick Ing-Sim‐
107       mons and Jeffrey Friedl.
108

NAME

SYNOPSIS

DESCRIPTION

CAVEATS

AUTHOR

SEE ALSO