MirOS Manual: Hash::Util(3p)


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

NAME

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

SYNOPSIS

       use Hash::Util qw(lock_keys   unlock_keys
                         lock_value  unlock_value
                         lock_hash   unlock_hash
                         hash_seed);

       %hash = (foo => 42, bar => 23);
       lock_keys(%hash);
       lock_keys(%hash, @keyset);
       unlock_keys(%hash);

       lock_value  (%hash, 'foo');
       unlock_value(%hash, 'foo');

       lock_hash  (%hash);
       unlock_hash(%hash);

       my $hashes_are_randomised = hash_seed() != 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.

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

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

     lock_keys
     unlock_keys
           lock_keys(%hash);
           lock_keys(%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. Note: 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
         lock_keys() so this shouldn't be a problem.

perl v5.8.8                2005-02-05                           1

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

           unlock_keys(%hash);

         Removes the restriction on the %hash's keyset.

     lock_value
     unlock_value
           lock_value  (%hash, $key);
           unlock_value(%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.

     lock_hash
     unlock_hash
             lock_hash(%hash);

         lock_hash() locks an entire hash, making all keys and
         values readonly. No value can be changed, no keys can be
         added or deleted.

             unlock_hash(%hash);

         unlock_hash() does the opposite of lock_hash().  All
         keys and values are made read/write.  All values can be
         changed and keys can be added and deleted.

     hash_seed
             my $hash_seed = hash_seed();

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

         Note that the hash seed is sensitive information: by
         knowing it one can craft a denial-of-service attack
         against Perl code, even remotely, see "Algorithmic Com-
         plexity Attacks" in perlsec for more information. Do not
         disclose the hash seed to people who don't need to know
         it. See also "PERL_HASH_SEED_DEBUG" in perlrun.

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 con-
     tents.

perl v5.8.8                2005-02-05                           2

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

AUTHOR

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

SEE ALSO

     Scalar::Util, List::Util, Hash::Util, and "Algorithmic Com-
     plexity Attacks" in perlsec.

perl v5.8.8                2005-02-05                           3

Generated on 2014-07-04 21:17:45 by $MirOS: src/scripts/roff2htm,v 1.79 2014/02/10 00:36:11 tg Exp $

These manual pages and other documentation are copyrighted by their respective writers; their source is available at our CVSweb, AnonCVS, and other mirrors. The rest is Copyright © 2002‒2014 The MirOS Project, Germany.
This product includes material provided by Thorsten Glaser.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report – diffs preferred.