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 eachother 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 stange
        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 stange
        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 strangly 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.