File Coverage

blib/lib/Hash/SafeKeys.pm

Criterion	Covered	Total	%
statement	23	23	100.0
branch			n/a
condition			n/a
subroutine	7	7	100.0
pod	3	3	100.0
total	33	33	100.0

=head1 NAME

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

=head1 VERSION

Version 0.03

=cut

=head1 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;
       }
    }

=head1 DESCRIPTION

Every hash variable in Perl has its own internal iterator,
accessed by the builtin C, C, and C
functions. The iterator is also implicitly used whenever
the hash is evaluated in list context.  The iterator is
"reset" whenever C or C 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 C loop:

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

C 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
    }

=head1 FUNCTIONS

=head2 LIST = safekeys HASH

Like the builtin L 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 C,
calling C does not reset the HASH's internal iterator
(see L).

=head2 LIST = safevalues HASH

Like the builtin L 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 C,
calling C does not reset the HASH's internal iterator
(see L).

=head2 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.

=head1 EXPORT

L<"safekeys">, L<"safevalues">, and L<"safecopy"> are all
exported by default. Invoke L with the empty arg list

    use Hash::SafeKeys ();

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

=head1 AUTHOR

Marty O'Brien, C<<  >>

=head1 BUGS

Please report any bugs or feature requests to C, or through
the web interface at L.  I will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.

=head1 SUPPORT

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

    perldoc Hash::SafeKeys


You can also look for information at:

=over 4

=item * RT: CPAN's request tracker (report bugs here)

L

=item * AnnoCPAN: Annotated CPAN documentation

L

=item * CPAN Ratings

L

=item * Search CPAN

L

=back


=head1 ACKNOWLEDGEMENTS

The C method in the L module demonstrated how
to save and restore internal hash iterator state.
This module is indebted to the authors of this module and to
L<< user C at stackoverflow.com|http://stackoverflow.com/a/10921567/168857 >>
for directing me to it.

=head1 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.

=cut

package Hash::SafeKeys;

use strict;
use warnings;
use base qw(Exporter);
our @EXPORT = qw(safekeys safevalues safecopy);
our $VERSION = '0.03';

# crutch for creating the XS code ...
#use Inline (Config => CLEAN_AFTER_BUILD => 0, FORCE_BUILD => 1, BUILD_NOISY => 1);
#use Inline 'C';

# crutches off
use base qw(DynaLoader); bootstrap Hash::SafeKeys $VERSION;

sub safekeys (\%) {
    my $hash = shift;
    my $state = save_iterator_state($hash);
    my @keys = keys %$hash;
    restore_iterator_state($hash,$state);
    return @keys;
}

sub safevalues (\%) {
    my $hash = shift;
    return map { $hash->{$_} } safekeys(%$hash);
}

sub safecopy (\%) {
    my $hash = shift;
    return map { ($_,$hash->{$_}) } safekeys(%$hash);
}

1;

__DATA__