NAME

       Hash::StoredIterator - Functions for accessing a hashes internal iterator.

DESCRIPTION

       In perl all hashes have an internal iterator. This iterator is used by the "each()" function, as well as
       by "keys()" and "values()". Because these all share use of the same iterator, they tend to interact badly
       with each other when nested.

       Hash::StoredIterator gives you access to get, set, and init the iterator inside a hash. This allows you
       to store the current iterator, use each/keys/values/etc, and then restore the iterator, this helps you to
       ensure you do not interact badly with other users of the iterator.

       Along with low-level get/set/init functions, there are also 2 variations of "each()" which let you act
       upon each key/value pair in a safer way than vanilla "each()"

       This module can also export new implementations of "keys()" and "values()" which stash and restore the
       iterator so that they are safe to use within "each()".

SYNOPSIS

           use Hash::StoredIterator qw{
               hmap
               hkeys
               hvalues
               iterator
               hash_get_iterator
               hash_set_iterator
               hash_init_iterator
           };

           my %hash = map { $_ => uc( $_ )} 'a' .. 'z';

           my @keys = hkeys %hash;
           my @values = hvalues %hash;

       Each section below is functionally identical.

           my $iterator = iterator %hash;
           while( my ( $k, $v ) = $i->() ) {
               print "$k: $value\n";
           }

           hmap { print "$a: $b\n" } %hash;

           hamp { print "$_: $b\n" } %hash;

           hmap {
               my ( $key, $val ) = @_;
               print "$key: $val\n";
           } %hash;

       It is safe to nest calls to "hmap()", "iterator()", "hkeys()", and "hvalues()"

           hmap {
               my ( $key, $val ) = @_;
               print "$key: $val\n";
               my @keys = hkeys( %hash );
           } %hash;

       "hmap()" and "iterator()" will also properly handle calls to "CORE::each", "CORE::keys", and
       "Core::values" nested within them.

           hmap {
               my ( $key, $val ) = @_;
               print "$key: $val\n";

               # No infinite loop!
               my @keys = keys %hash;
           } %hash;

       Low Level:

           hash_init_iterator( \%hash );
           my $iter = hash_get_iterator( \%hash );
           # NOTE: Never manually specify an $iter value, ALWAYS use a value from
           # hash_get_iterator.
           hash_set_iterator( \%hash, $iter );

EXPORTS

       my $i = iterator %hash
           Get an iterator that can be used to retrieve key/value pairs.

               my $i = iterator %hash;
               while( my ($k, $v) = $i->() ) {
                   ...
               }

           The  iterator is a coderef, so you call it like this: "$i-"()>. You can also use the sub anywhere you
           would use any other coderef.

       hmap( \&callback, %hash )
       hmap { ... } %hash
           Iterate each key/pair calling "$callback-"( $key, $value )> for each set. In addition $a and  $_  are
           set  to  the  key,  and  $b  is set to the value.  This is done primarily for convenience of matching
           against the key, and short callbacks that will be cluttered by parsing @_ noise.

           Note: See caveats.

       my @keys = hkeys( %hash )
           Same as the builtin "keys()", except it stores and restores the iterator.

           Note: Overriding the builtin keys(), even locally, causes strange interactions with  other  builtins.
           When  trying to export hkeys as keys, a call to "sort keys %hash" would cause undef to be passed into
           keys() as the first and only argument.

       my @values = hvalues( %hash )
           Same as the builtin "values()", except it stores and restores the iterator.

           Note: Overriding the builtin values(), even locally, causes strange interactions with other builtins.
           When trying to export hvalues as values, a call to "sort values %hash" would cause undef to be passed
           into values() as the first and only argument.

       my $i = hash_get_iterator( \%hash )
           Get the current iterator value.

       hash_set_iterator( \%hash, $i )
           Set the iterator value.

           Note: Only ever set this to the value retrieved by "hash_get_iterator()", setting the iterator in any
           other way is untested, and may result in undefined behavior.

       hash_init_iterator( \%hash )
           Initialize or reset the hash iterator.

DEPRECATED

       These have been deprecated because they were terrible names. eich was  also  deprecated  because  it  was
       unnatural to use.

       eich
           use iterator() instead

       eech
           use hmap instead

CAVEATS

       Modification of hash during iteration
           Just  like  with the builtin "each()" modifying the hash between calls to each is not recommended and
           can result in undefined behavior. The builtin "each()" does allow for deleting  the  iterations  key,
           however that is NOT supported by this library.

       sort() edge case
           For some reason "[sort hkeys %hash]" and "[sort hkeys(%hash)]" both result in a list that has all the
           keys and values (and strangely not in sorted order).  However "[sort(hkeys(%hash))]" works fine.

AUTHORS

       Chad Granum exodist7@gmail.com

COPYRIGHT

       Copyright (C) 2013 Chad Granum

       Hash-StoredIterator is free software; Standard perl licence.

       Hash-StoredIterator  is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
       even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See  the  license  for
       more details.

perl v5.34.0                                       2022-02-06                          Hash::StoredIterator(3pm)