Syntax-K

Know-How für Ihr Projekt

Perl Documentation

NAME

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

SYNOPSIS

# Restricted hashes
use Hash::Util qw(
                   fieldhash fieldhashes
all_keys
lock_keys unlock_keys
lock_value unlock_value
lock_hash unlock_hash
lock_keys_plus
hash_locked hash_unlocked
hashref_locked hashref_unlocked
hidden_keys legal_keys
lock_ref_keys unlock_ref_keys
lock_ref_value unlock_ref_value
lock_hashref unlock_hashref
lock_ref_keys_plus
hidden_ref_keys legal_ref_keys
hash_seed hash_value hv_store
bucket_stats bucket_info bucket_array
lock_hash_recurse unlock_hash_recurse
lock_hashref_recurse unlock_hashref_recurse
  hash_traversal_mask
);
%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;
my $int_hash_value = hash_value( 'string' );
my $mask= hash_traversal_mask(%hash);
hash_traversal_mask(%hash,1234);

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.

Operating on references to hashes.

Most subroutines documented in this module have equivalent versions that operate on references to hashes instead of native hashes. The following is a list of these subs. They are identical except in name and in that instead of taking a %hash they take a $hashref, and additionally are not prototyped.

CAVEATS

Note that the trapping of the restricted operations is not atomic: for example

eval { %hash = (illegal_key => 1) }

leaves the %hash empty rather than with its original contents.

BUGS

The interface exposed by this module is very close to the current implementation of restricted hashes. Over time it is expected that this behavior will be extended and the interface abstracted further.

AUTHOR

Michael G Schwern <schwern@pobox.com> on top of code by Nick Ing-Simmons and Jeffrey Friedl.

hv_store() is from Array::RefElem, Copyright 2000 Gisle Aas.

Additional code by Yves Orton.

SEE ALSO

Scalar::Util, List::Util and "Algorithmic Complexity Attacks" in perlsec.

Hash::Util::FieldHash.