CONTENTS

• NAME
• SYNOPSIS
• DESCRIPTION
  • Restricted hashes
  • Operating on references to hashes.
• CAVEATS
• BUGS
• AUTHOR
• SEE ALSO

#NAME

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

#SYNOPSIS

# Restricted hashes

use Hash::Util qw(
                   hash_seed all_keys
                   lock_keys unlock_keys
                   lock_value unlock_value
                   lock_hash unlock_hash
                   lock_keys_plus hash_locked
                   hidden_keys legal_keys
                 );

%hash = (foo => 42, bar => 23);
# Ways to restrict a hash
lock_keys(%hash);
lock_keys(%hash, @keyset);
lock_keys_plus(%hash, @additional_keys);

# Ways to inspect the properties of a restricted hash
my @legal = legal_keys(%hash);
my @hidden = hidden_keys(%hash);
my $ref = all_keys(%hash,@keys,@hidden);
my $is_locked = hash_locked(%hash);

# Remove restrictions on the hash
unlock_keys(%hash);

# Lock individual values in a hash
lock_value  (%hash, 'foo');
unlock_value(%hash, 'foo');

# Ways to change the restrictions on both keys and values
lock_hash  (%hash);
unlock_hash(%hash);

my $hashes_are_randomised = hash_seed() != 0;

#DESCRIPTION

Hash::Util and Hash::Util::FieldHash contain special functions for manipulating hashes that don't really warrant a keyword.

Hash::Util contains a set of functions that support restricted hashes. These are described in this document. Hash::Util::FieldHash contains an (unrelated) set of functions that support the use of hashes in inside-out classes, described in Hash::Util::FieldHash.

By default Hash::Util does not export anything.

#Restricted hashes

5.8.0 introduces the ability to restrict a hash to a certain set of keys. No keys outside of this set can be added. It also introduces the ability to lock an individual key so it cannot be deleted and the ability to ensure that an individual value cannot be changed.

This is intended to largely replace the deprecated pseudo-hashes.