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) = @_;
74 Internals::hv_clear_placeholders %$hash;
76 my %keys = map { ($_ => 1) } @keys;
77 my %original_keys = map { ($_ => 1) } keys %$hash;
78 foreach my $k (keys %original_keys) {
79 die sprintf "Hash has key '$k' which is not in the new key ".
80 "set at %s line %d\n", (caller)[1,2]
84 foreach my $k (@keys) {
85 $hash->{$k} = undef unless exists $hash->{$k};
87 Internals::SvREADONLY %$hash, 1;
89 foreach my $k (@keys) {
90 delete $hash->{$k} unless $original_keys{$k};
94 Internals::SvREADONLY %$hash, 1;
100 sub unlock_keys (\%) {
103 Internals::SvREADONLY %$hash, 0;
111 lock_value (%hash, $key);
112 unlock_value(%hash, $key);
114 Locks and unlocks an individual key of a hash. The value of a locked
115 key cannot be changed.
117 %hash must have already been locked for this to have useful effect.
121 sub lock_value (\%$) {
122 my($hash, $key) = @_;
123 carp "Cannot usefully lock values in an unlocked hash"
124 unless Internals::SvREADONLY %$hash;
125 Internals::SvREADONLY $hash->{$key}, 1;
128 sub unlock_value (\%$) {
129 my($hash, $key) = @_;
130 Internals::SvREADONLY $hash->{$key}, 0;
140 lock_hash() locks an entire hash, making all keys and values readonly.
141 No value can be changed, no keys can be added or deleted.
145 unlock_hash() does the opposite of lock_hash(). All keys and values
146 are made read/write. All values can be changed and keys can be added
156 foreach my $key (keys %$hash) {
157 lock_value(%$hash, $key);
163 sub unlock_hash (\%) {
166 foreach my $key (keys %$hash) {
167 unlock_value(%$hash, $key);
180 Michael G Schwern <schwern@pobox.com> on top of code by Nick
181 Ing-Simmons and Jeffrey Friedl.
185 L<Scalar::Util>, L<List::Util>, L<Hash::Util>