Hash::SafeKeys - get hash contents without resetting each iterator

NAME

Hash::SafeKeys - get hash contents without resetting each iterator

VERSION

Version 0.03

SYNOPSIS

    use Hash::SafeKeys;
    while (my ($k,$v) = each %hash) {
       if (something_interesting_happens()) {
          # get keys, values of %hash without resetting
          # the 'each' iterator above
          my @k = safekeys %hash;
          my @v = safevalues %hash;
          my %copy = safecopy %hash;
       }
    }

DESCRIPTION

Every hash variable in Perl has its own internal iterator, accessed by the builtin each, keys, and values functions. The iterator is also implicitly used whenever the hash is evaluated in list context. The iterator is ``reset'' whenever keys or values is called on a hash, including the implicit calls when the hash is evaluated in list context. That makes it dangerous to do certain hash operations inside a while ... each loop:

    while (my($k,$v) = each %hash) {
       ...
       @k = sort keys %hash;               # Infinite loop!
       @v = grep { /foo/ }, values %hash;  # Ack!
       print join ' ', %hash;              # Run away!
    }

Hash::SafeKeys provides alternate functions to access the keys, values, or entire contents of a hash in a way that does not reset the iterator, making them safe to use in such contexts:

    while (my($k,$v) = each %hash) {
       ...
       @k = sort safekeys %hash;               # Can do
       @v = grep { /foo/ }, safevalues %hash;  # No problem
       print join ' ', safecopy %hash;         # Right away, sir
    }

FUNCTIONS

LIST = safekeys HASH

Like the builtin keys function, returns a list consisting of all the keys of the named hash, in the same order that the builtin function would return them in. Unlike keys, calling safekeys does not reset the HASH's internal iterator (see each).

LIST = safevalues HASH

Like the builtin values function, returns a list consisting of all the values of the named hash, in the same order that the builtin function would return them in. Unlike values, calling safevalues does not reset the HASH's internal iterator (see each).

LIST = safecopy HASH

In list context, returns a shallow copy of the named HASH without resetting the HASH's internal iterator. Usually, evaluating a HASH in list context implicitly uses the internal iterator, resetting any existing state.

EXPORT

safekeys, safevalues, and safecopy are all exported by default. Invoke the Hash::SafeKeys manpage with the empty arg list

    use Hash::SafeKeys ();

if you don't want these functions to be imported into the calling package.

AUTHOR

Marty O'Brien, <mob at cpan.org>

BUGS

Please report any bugs or feature requests to bug-hash-safekeys at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Hash::SafeKeys

You can also look for information at:

ACKNOWLEDGEMENTS

The dclone method in the the Storable manpage module demonstrated how to save and restore internal hash iterator state. This module is indebted to the authors of this module and to user gpojd at stackoverflow.com for directing me to it.

LICENSE AND COPYRIGHT

Copyright 2012 Marty O'Brien.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

 Hash::SafeKeys - get hash contents without resetting each iterator