Hash::Util(3pm) Perl Programmers Reference Guide Hash::Util(3pm)

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

SYNOPSIS
         use Hash::Util qw(lockkeys   unlockkeys
                           lockvalue  unlockvalue
                           lockhash   unlockhash
                           hashseed);

         %hash = (foo => 42, bar => 23);
         lockkeys(%hash);
         lockkeys(%hash, @keyset);
         unlockkeys(%hash);

         lockvalue  (%hash, 'foo');
         unlockvalue(%hash, 'foo');

         lockhash  (%hash);
         unlockhash(%hash);

         my $hashesarerandomised = hashseed() != 0;

DESCRIPTION
       "Hash::Util" contains special functions for manipulating hashes that
       don't really warrant a keyword.

       By default "Hash::Util" does not export anything.

       RReessttrriicctteedd hhaasshheess

       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
       value cannot be changed.

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

       lockkeys
       unlockkeys
             lockkeys(%hash);
             lockkeys(%hash, @keys);

           Restricts the given %hash's set of keys to @keys.  If @keys is not
           given it restricts it to its current keyset.  No more keys can be
           added. delete() and exists() will still work, but will not alter
           the set of allowed keys. NNoottee: the current implementation prevents
           the hash from being bless()ed while it is in a locked state. Any
           attempt to do so will raise an exception. Of course you can still
           bless() the hash before you call lockkeys() so this shouldn't be a
           problem.

             unlockkeys(%hash);

           Removes the restriction on the %hash's keyset.

       lockvalue
       unlockvalue
             lockvalue  (%hash, $key);
             unlockvalue(%hash, $key);

           Locks and unlocks an individual key of a hash.  The value of a
           locked key cannot be changed.

           %hash must have already been locked for this to have useful effect.

       lloocckkhhaasshh
       uunnlloocckkhhaasshh
               lockhash(%hash);

           lockhash() locks an entire hash, making all keys and values read-
           only.  No value can be changed, no keys can be added or deleted.

               unlockhash(%hash);

           unlockhash() does the opposite of lockhash().  All keys and val-
           ues are made read/write.  All values can be changed and keys can be
           added and deleted.

       hhaasshhsseeeedd
               my $hashseed = hashseed();

           hashseed() returns the seed number used to randomise hash order-
           ing.  Zero means the "traditional" random hash ordering, non-zero
           means the new even more random hash ordering introduced in Perl
           5.8.1.

           NNoottee tthhaatt tthhee hhaasshh sseeeedd iiss sseennssiittiivvee iinnffoorrmmaattiioonn: by knowing it one
           can craft a denial-of-service attack against Perl code, even
           remotely, see "Algorithmic Complexity Attacks" in perlsec for more
           information.  DDoo nnoott ddiisscclloossee tthhee hhaasshh sseeeedd to people who don't
           need to know it.  See also "PERLHASHSEEDDEBUG" in perlrun.

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

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

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

AUTHOR
       Michael G Schwern  on top of code by Nick Ing-Sim-
       mons and Jeffrey Friedl.

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



perl v5.8.8                       2001-09-21                   Hash::Util(3pm)