Hash::SafeKeys - get hash contents without resetting each iterator
Version 0.03
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; } }
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:
each
keys
values
while ... each
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:
Hash::SafeKeys
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 }
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).
safekeys
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).
safevalues
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.
"safekeys", "safevalues", and "safecopy" are all exported by default. Invoke Hash::SafeKeys with the empty arg list
use Hash::SafeKeys ();
if you don't want these functions to be imported into the calling package.
Marty O'Brien, <mob at cpan.org>
<mob at cpan.org>
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?Queue=Hash-SafeKeys. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-hash-safekeys at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Hash::SafeKeys
You can also look for information at:
RT: CPAN's request tracker (report bugs here)
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Hash-SafeKeys
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Hash-SafeKeys
CPAN Ratings
http://cpanratings.perl.org/d/Hash-SafeKeys
Search CPAN
http://search.cpan.org/dist/Hash-SafeKeys/
The dclone method in the Storable 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.
dclone
gpojd
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.
To install Hash::SafeKeys, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Hash::SafeKeys
CPAN shell
perl -MCPAN -e shell install Hash::SafeKeys
For more information on module installation, please visit the detailed CPAN module installation guide.