SYNOPSIS

  use Hash_Iterator;

  my $it = Hash_Iterator->new( \%some_hash );

  while ( defined( my $k = $it->each ) ) {
    # do something with $k
  }

  # $it->each restarts after hitting the end

  while ( my ( $k, $v ) = $it->each ) {
    # one more iteration
  }

  # alternatively, $it->start resets the iterator

  for ( $it->start; !$it->exhausted; $it->next ) {
    my $k = $it->value;
    # do something with $k
  }

  # here's another way to traverse the hash
  $it->start;
  until ( $it->exhausted ) {
    my ( $k, $v ) = $it->next;
    # do something with ( $k, $v )
  }


DESCRIPTION

The API is as follows:

new( $hashref )    The constructor, obviously.  The argument is
                   mandatory, and must be a hashref.

$it->each          Should behave exactly like CORE::each.

$it->start         Resets the iterator.  (It also returns the first
                   value.  This is as described in HOP.)

$it->value         Returns the current value, according to the
                   same rules as CORE::each (i.e. both key and
                   value are returned in list context); does not
                   advance the iterator.

$it->next          Advances the iterator.  (It also returns
                   the results of $it->value *before* advancing
                   the iterator, as described in HOP.)

$it->nextval       An alias for $it->next().

$it->exhausted     Returns true iff the iterator is exhausted.

NB: The only difference between the next() (or nextval()) and
each() methods is that the latter (but not the former) 
automatically resets the iterator after hitting the end once.