8 our @ISA = qw(Exporter);
9 our @EXPORT_OK = qw(lock_keys unlock_keys lock_value unlock_value
16 Hash::Util - A selection of general-utility hash subroutines
20 use Hash::Util qw(lock_keys unlock_keys
21 lock_value unlock_value
22 lock_hash unlock_hash);
24 %hash = (foo => 42, bar => 23);
26 lock_keys(%hash, @keyset);
29 lock_value (%hash, 'foo');
30 unlock_value(%hash, 'foo');
37 C<Hash::Util> contains special functions for manipulating hashes that
38 don't really warrant a keyword.
40 By default C<Hash::Util> does not export anything.
42 =head2 Restricted hashes
44 5.8.0 introduces the ability to restrict a hash to a certain set of
45 keys. No keys outside of this set can be added. It also introduces
46 the ability to lock an individual key so it cannot be deleted and the
47 value cannot be changed.
49 This is intended to largely replace the deprecated pseudo-hashes.
58 lock_keys(%hash, @keys);
60 Restricts the given %hash's set of keys to @keys. If @keys is not
61 given it restricts it to its current keyset. No more keys can be
62 added. delete() and exists() will still work, but it does not effect
63 the set of allowed keys.
67 Removes the restriction on the %hash's keyset.
71 sub lock_keys (\%;@) {
72 my($hash, @keys) = @_;
75 my %keys = map { ($_ => 1) } @keys;
76 my %original_keys = map { ($_ => 1) } keys %$hash;
77 foreach my $k (keys %original_keys) {
78 die sprintf "Hash has key '$k' which is not in the new key ".
79 "set at %s line %d\n", (caller)[1,2]
83 foreach my $k (@keys) {
84 $hash->{$k} = undef unless exists $hash->{$k};
86 Internals::SvREADONLY %$hash, 1;
88 foreach my $k (@keys) {
89 delete $hash->{$k} unless $original_keys{$k};
93 Internals::SvREADONLY %$hash, 1;
99 sub unlock_keys (\%) {
102 Internals::SvREADONLY %$hash, 0;
110 lock_key (%hash, $key);
111 unlock_key(%hash, $key);
113 Locks and unlocks an individual key of a hash. The value of a locked
114 key cannot be changed.
116 %hash must have already been locked for this to have useful effect.
120 sub lock_value (\%$) {
121 my($hash, $key) = @_;
122 carp "Cannot usefully lock values in an unlocked hash"
123 unless Internals::SvREADONLY %$hash;
124 Internals::SvREADONLY $hash->{$key}, 1;
127 sub unlock_value (\%$) {
128 my($hash, $key) = @_;
129 Internals::SvREADONLY $hash->{$key}, 0;
139 lock_hash() locks an entire hash, making all keys and values readonly.
140 No value can be changed, no keys can be added or deleted.
144 unlock_hash() does the opposite of lock_hash(). All keys and values
145 are made read/write. All values can be changed and keys can be added
155 foreach my $key (keys %$hash) {
156 lock_value(%$hash, $key);
162 sub unlock_hash (\%) {
165 foreach my $key (keys %$hash) {
166 unlock_value(%$hash, $key);
179 Michael G Schwern <schwern@pobox.com> on top of code by Nick
180 Ing-Simmons and Jeffrey Friedl.
184 L<Scalar::Util>, L<List::Util>, L<Hash::Util>