.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Hash::SafeKeys 3pm" .TH Hash::SafeKeys 3pm 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME Hash::SafeKeys \- get hash contents without resetting each iterator .SH VERSION .IX Header "VERSION" Version 0.04 .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 10 \& use Hash::SafeKeys; \& while (my ($k,$v) = each %hash) { \& if (something_interesting_happens()) { \& # get keys, values of %hash without resetting \& # the \*(Aqeach\*(Aq iterator above \& my @k = safekeys %hash; \& my @v = safevalues %hash; \& my %copy = safecopy %hash; \& } \& } .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" Every hash variable in Perl has its own internal iterator, accessed by the builtin \f(CW\*(C`each\*(C'\fR, \f(CW\*(C`keys\*(C'\fR, and \f(CW\*(C`values\*(C'\fR functions. The iterator is also implicitly used whenever the hash is evaluated in list context. The iterator is "reset" whenever \f(CW\*(C`keys\*(C'\fR or \f(CW\*(C`values\*(C'\fR 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 \f(CW\*(C`while ... each\*(C'\fR loop: .PP .Vb 6 \& while (my($k,$v) = each %hash) { \& ... \& @k = sort keys %hash; # Infinite loop! \& @v = grep { /foo/ }, values %hash; # Ack! \& print join \*(Aq \*(Aq, %hash; # Run away! \& } .Ve .PP \&\f(CW\*(C`Hash::SafeKeys\*(C'\fR 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: .PP .Vb 6 \& while (my($k,$v) = each %hash) { \& ... \& @k = sort safekeys %hash; # Can do \& @v = grep { /foo/ }, safevalues %hash; # No problem \& print join \*(Aq \*(Aq, safecopy %hash; # Right away, sir \& } .Ve .SH FUNCTIONS .IX Header "FUNCTIONS" .SS safekeys .IX Subsection "safekeys" .SS "LIST = safekeys HASH" .IX Subsection "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 \f(CW\*(C`keys\*(C'\fR, calling \f(CW\*(C`safekeys\*(C'\fR does not reset the HASH's internal iterator (see each). .SS safevalues .IX Subsection "safevalues" .SS "LIST = safevalues HASH" .IX Subsection "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 \f(CW\*(C`values\*(C'\fR, calling \f(CW\*(C`safevalues\*(C'\fR does not reset the HASH's internal iterator (see each). .SS safecopy .IX Subsection "safecopy" .SS "LIST = safecopy HASH" .IX Subsection "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 .SS save_iterator_state .IX Subsection "save_iterator_state" .SS restore_iterator_state .IX Subsection "restore_iterator_state" .SS "HANDLE = save_iterator_state($hashref)" .IX Subsection "HANDLE = save_iterator_state($hashref)" .SS "restore_iterator_state($hashref, HANDLE)" .IX Subsection "restore_iterator_state($hashref, HANDLE)" Low-level functions to manipulate the iterator of a hash reference. The use cases for directly using these functions are .IP "1. Performance" 4 .IX Item "1. Performance" The absolute fastest way to \fIsafely\fR access the keys of a hash is: .Sp .Vb 3 \& $handle = Hash::Safekeys::save_iterator_state( \e%hash ); \& @keys = keys %hash; \& Hash::Safekeys::restore_iterator_state( \e%hash, $handle ); .Ve .Sp This is an improvement over \f(CW\*(C`@keys = safekeys %hash\*(C'\fR because it eliminates the O(n) list copy operation on return from the \&\f(CW\*(C`safekeys\*(C'\fR function. .IP "2. Access to aliased values" 4 .IX Item "2. Access to aliased values" The builtin \f(CW\*(C`values\*(C'\fR function returns aliases to the internal hash values, allowing you to modify the contents of the hash with constructions like .Sp .Vb 1 \& s/foo/bar/g for values %hash .Ve .Sp As \f(CW\*(C`safevalues %hash\*(C'\fR returns a copy of the hash values, \&\f(CW\*(C`s/foo/bar/g for safevalues %hash\*(C'\fR will \fBnot\fR modify the contents of the hash. .Sp To \fIsafely\fR modify the values of the hash, a workaround with the low-level iterator functions is .Sp .Vb 3 \& $handle = Hash::SafeKeys::save_iterator_state( \e%hash ); \& for (values %hash) { ... modify($_) ... } \& Hash::SafeKeys::restore_iterator_state( \e%hash, $handle ); .Ve .IP "3. Nested each calls on the same hash" 4 .IX Item "3. Nested each calls on the same hash" This construction will not work if \f(CW$hash1\fR and \f(CW$hash2\fR refer to the same hash: .Sp .Vb 3 \& while (($key1,$val1) = each %$hash1) { \& while (($key2,$val2) = each %$hash2) { ... } \& } .Ve .Sp but this construction is \fIsafe\fR: .Sp .Vb 5 \& while (($key1,$val1) = each %$hash1) { \& $handle = Hash::SafeKeys::save_iterator_state($hash2); \& while (($key2,$val2) = each %$hash2) { ... } \& Hash::SafeKeys::restore_iterator_state($hash2, $handle); \& } .Ve .Sp The HANDLE that is returned by \f(CW\*(C`save_iterator_state\*(C'\fR and used as an input to \f(CW\*(C`restore_iterator_state\*(C'\fR 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. .Sp It is a grave error to provide a different hash reference with the handle to the \f(CW\*(C`restore_iterator_state\*(C'\fR call than you provided to the \&\f(CW\*(C`save_iterator_state\*(C'\fR call that created the handle. .Sp Calling \f(CW\*(C`save_iterator_state\*(C'\fR without later calling \&\f(CW\*(C`restore_iterator_state\*(C'\fR will leak memory. .SH EXPORT .IX Header "EXPORT" "safekeys", "safevalues", and "safecopy" are all exported by default. Invoke Hash::SafeKeys with the empty arg list .PP .Vb 1 \& use Hash::SafeKeys (); .Ve .PP if you don't want these functions to be imported into the calling package. .PP The low-level iterator functions "save_iterator_state" and "restore_iterator_state" may also be exported by including them in the \f(CW\*(C`use\*(C'\fR call or by using the tag \f(CW\*(C`:all\*(C'\fR .PP .Vb 1 \& use Hash::SafeKeys \*(Aq:all\*(Aq; # also exports low\-level iterator funcs .Ve .SH AUTHOR .IX Header "AUTHOR" Marty O'Brien, \f(CW\*(C`\*(C'\fR .SH BUGS .IX Header "BUGS" Please report any bugs or feature requests to \&\f(CW\*(C`bug\-hash\-safekeys at rt.cpan.org\*(C'\fR, or through the web interface at . I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. .SH SUPPORT .IX Header "SUPPORT" You can find documentation for this module with the perldoc command. .PP .Vb 1 \& perldoc Hash::SafeKeys .Ve .PP You can also look for information at: .IP \(bu 4 RT: CPAN's request tracker (report bugs here) .Sp .IP \(bu 4 AnnoCPAN: Annotated CPAN documentation .Sp .IP \(bu 4 CPAN Ratings .Sp .IP \(bu 4 Search CPAN .Sp .SH ACKNOWLEDGEMENTS .IX Header "ACKNOWLEDGEMENTS" The \f(CW\*(C`dclone\*(C'\fR 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 \f(CW\*(C`gpojd\*(C'\fR at stackoverflow.com for directing me to it. .PP A helpful comment by > let to further improvements. .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright 2012\-2016 Marty O'Brien. .PP 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. .PP See http://dev.perl.org/licenses/ for more information.