Hash::SafeKeys(3pm)

📦
version 0.04 · 5 versions
, in ubuntu stonking

💖 Hash::SafeKeys 💖

okay bestie, welcome to Hash::SafeKeys, which lives in the User Contributed Perl Documentation zone (it's a 3pm page, iykyk 💅). short version: it lets you peek at what's inside a hash without messing up the iterator you're currently walking. and like, if you've ever had a while ... each loop spin forever, this module is your emotional support bestie. 🫶

🌸 VERSION 🌸

Version 0.04 — lil baby but mighty ✨

🎀 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 🦋

okay so here's the tea, and it's important tea ☕

every single hash variable in Perl has its own internal iterator, and it gets used by the builtins each, keys, and values. plot twist: that iterator is ALSO used implicitly any time the hash gets evaluated in list context. no escape. 🙈

and whenever you call keys or values on a hash — including those sneaky implicit calls from list context — the iterator gets reset. which means doing certain hash operations inside a while ... each loop is genuinely dangerous territory:

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

literally run away, bestie, don't look back 💀

Hash::SafeKeys said "not on my watch" and provides alternate functions to access the keys, the values, or the entire contents of a hash in a way that does not reset the iterator — so they're totally safe to use in those exact 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
}

periodt. 👑

✨ FUNCTIONS ✨

🍓 safekeys

LIST = safekeys HASH

just like the builtin keys function — it hands you a list of all the keys of the named hash, in the same order the builtin would give them to you. unlike keys though, calling safekeys does not reset the HASH's internal iterator (see each). iconic behavior. 💅

🧚 safevalues

LIST = safevalues HASH

like the builtin values function, it returns a list of all the values of the named hash, same order as the builtin would return them in. and unlike values, calling safevalues does not reset the HASH's internal iterator (see each). slay. ✨

🌈 safecopy

LIST = safecopy HASH

in list context, this 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, which would reset any existing state — and we simply do not do that here. 🚫

💜 save_iterator_state

💜 restore_iterator_state

HANDLE = save_iterator_state($hashref)
restore_iterator_state($hashref, HANDLE)

low-level functions for manipulating the iterator of a hash reference. the use cases for reaching for these directly are… let me count them on my sparkly nails:

  1. Performance 🏎️

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. no notes, it just eats. 🔥

  1. Access to aliased values 🪞

the builtin values function returns aliases to the internal hash values, which means you can modify the contents of the hash with constructions like

s/foo/bar/g for values %hash

but 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. sad but true 😭

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 );
  1. Nested each calls on the same hash 🪆

this construction will not work if $hash1 and $hash2 refer to the same hash:

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 gets 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. 👀

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. do not do this. i am begging. 😭
calling save_iterator_state without later calling restore_iterator_state will leak memory. that's not a vibe, that's a leak, bestie. 💀

🌟 EXPORT 🌟

safekeys, safevalues, and safecopy are all exported by default. if you don't want these functions imported into the calling package, invoke Hash::SafeKeys with the empty arg list:

use Hash::SafeKeys ();

the low-level iterator functions save_iterator_state and restore_iterator_state may also be exported — either by including them in the use call, or by using the tag :all:

use Hash::SafeKeys ':all';   # also exports low-level iterator funcs

choose your fighter 🥊

🫶 AUTHOR 🫶

Marty O'Brien, "<mob at cpan.org>" — thank you for your service, king 👑

💀 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?Queue=Hash-SafeKeys. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. we love a feedback loop. ✨

🌸 SUPPORT 🌸

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/

🧚 ACKNOWLEDGEMENTS 🧚

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 that module, and to user gpojd at stackoverflow.com (http://stackoverflow.com/a/10921567/168857) for directing me to it. absolute legends, both. 🙌

a helpful comment by Alexandr Evstigneev (http://search.cpan.org/~hurricup/) led to further improvements. we stay improving. 💅

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.

and that's the whole page, bestie 🎀 this was perl v5.42.3, dated 2026-08-19, brought to you by the fine folks who write User Contributed Perl Documentation. mwah. 💖✨

📦 where this page comes from