Hash::SafeKeys - get hash contents without resetting each iterator
Version 0.04
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
Low-level functions to manipulate the iterator of a hash reference. The use cases for directly using these functions are
The absolute fastest way to safely access the keys of a hash is:
$handle = Hash::Safekeys::save_iterator_state( \%hash ); @keys = keys %hash; Hash::Safekeys::restore_iterator_state( \%hash, $handle );
This is an improvement over @keys = safekeys %hash because it eliminates the O(n) list copy operation on return from the safekeys function.
@keys = safekeys %hash
The builtin values function returns aliases to the internal hash values, allowing you to modify the contents of the hash with constructions like
s/foo/bar/g for values %hash
As safevalues %hash returns a copy of the hash values, s/foo/bar/g for safevalues %hash will not modify the contents of the hash.
safevalues %hash
s/foo/bar/g for safevalues %hash
To safely modify the values of the hash, a workaround with the low-level iterator functions is
$handle = Hash::SafeKeys::save_iterator_state( \%hash ); for (values %hash) { ... modify($_) ... } Hash::SafeKeys::restore_iterator_state( \%hash, $handle );
This construction will not work if $hash1 and $hash2 refer to the same hash:
$hash1
$hash2
while (($key1,$val1) = each %$hash1) { while (($key2,$val2) = each %$hash2) { ... } }
but this construction is safe:
while (($key1,$val1) = each %$hash1) { $handle = Hash::SafeKeys::save_iterator_state($hash2); while (($key2,$val2) = each %$hash2) { ... } Hash::SafeKeys::restore_iterator_state($hash2, $handle); }
The HANDLE that is returned by save_iterator_state and used as an input to restore_iterator_state is currently implemented as an integer that can be mapped internally to an original hash iterator. This implementation is subject to change in future releases and you should not rely on this value being an integer.
save_iterator_state
restore_iterator_state
It is a grave error to provide a different hash reference with the handle to the restore_iterator_state call than you provided to the save_iterator_state call that created the handle.
Calling save_iterator_state without later calling restore_iterator_state will leak memory.
"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.
The low-level iterator functions "save_iterator_state" and "restore_iterator_state" may also be exported by including them in the use call or by using the tag :all
use
:all
use Hash::SafeKeys ':all'; # also exports low-level iterator funcs
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
A helpful comment by <Alexandr Evstigneev> let to further improvements.
Copyright 2012-2016 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.