<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">NAME
    Array::Iterator - A simple class for iterating over Perl arrays

VERSION
    version 0.07

SYNOPSIS
      use Array::Iterator;

      # create an iterator with an array
      my $i = Array::Iterator-&gt;new(1 .. 100);

      # create an iterator with an array reference
      my $i = Array::Iterator-&gt;new(\@array);

      # create an iterator with a hash reference
      my $i = Array::Iterator-&gt;new({ __array__ =&gt; \@array });

      # a base iterator example
      while ($i-&gt;has_next()) {
          if ($i-&gt;peek() &lt; 50) {
              # ... do something because
              # the next element is over 50
          }
          my $current = $i-&gt;next();
          # ... do something with current
      }

      # shortcut style
      my @accumulation;
      push @accumulation =&gt; { item =&gt; $iterator-&gt;next() } while $iterator-&gt;has_next();

      # C++ ish style iterator
      for (my $i = Array::Iterator-&gt;new(@array); $i-&gt;has_next(); $i-&gt;next()) {
        my $current = $i-&gt;current();
        # .. do something with current
      }

      # common perl iterator idiom
      my $current;
      while ($current = $i-&gt;get_next()) {
        # ... do something with $current
      }

DESCRIPTION
    This class provides a very simple iterator interface. It is is
    uni-directional and can only be used once. It provides no means of
    reverseing or reseting the iterator. It is not recommended to alter the
    array during iteration, however no attempt is made to enforce this
    (although I will if I can find an efficient means of doing so). This
    class only intends to provide a clear and simple means of generic
    iteration, nothing more (yet).

METHODS
  Public Methods
    new (@array | $array_ref | $hash_ref)
        The constructor can be passed either a plain perl array, an array
        reference, or a hash reference (with the array specified as a single
        key off the hash, __array__). Single element arrays are not
        supported by either of the first two calling conventions, since it
        is not possible to distinguish between an array of a single element
        which happens to be an array reference, and an array reference of a
        single element, thus previous versions of the constructor would
        raise an exception. If you expect to pass arrays to the constructor
        which may have only a single element, then the array can be passed
        as the element of a HASH reference, with the key, __array__:

          my $i = Array::Iterator-&gt;new({ __array__ =&gt; \@array });

    has_next
        This methods returns a boolean. True (1) if there are still more
        elements in the iterator, false (0) if there are not.

    next
        This method returns the next item in the iterator, be sure to only
        call this once per iteration as it will advance the index pointer to
        the next item. If this method is called after all elements have been
        exhausted, an exception will be thrown.

    get_next
        This method returns the next item in the iterator, be sure to only
        call this once per iteration as it will advance the index pointer to
        the next item. If this method is called after all elements have been
        exhausted, it will return undef.

        This method was added to allow for a faily common perl iterator
        idiom of:

          my $current;
          while ($current = $i-&gt;get_next()) {
              ...
          }

        In this the loop terminates once $current is assigned to a false
        value. The only problem with this idiom for me is that it does not
        allow for undefined or false values in the iterator. Of course, if
        this fits your data, then there is no problem. Otherwise I would
        recommend the "has_next"/"next" idiom instead.

    peek
        This method can be used to peek ahead at the next item in the
        iterator. It is non-destructuve, meaning it does not advance the
        internal pointer. If this method is called and attempts to reach
        beyond the bounds of the iterator, it will return undef.

        NOTE: Prior to version 0.03 this method would throw an exception if
        called out of bounds. I decided this was not a good practice, as it
        made it difficult to be able to peek ahead effectively.

    current
        This method can be used to get the current item in the iterator. It
        is non-destructive, meaning that it does not advance the internal
        pointer. This value will match the last value dispensed by "next" or
        "get_next".

    current_index
        This method can be used to get the current index in the iterator. It
        is non-destructive, meaning that it does not advance the internal
        pointer. This value will match the index of the last value dispensed
        by "next" or "get_next".

    get_length
        This is a basic accessor for getting the length of the array being
        iterated over.

  Protected Methods
    These methods are *protected*, in the Java/C++ sense of the word. They
    can only be called internally by subclasses of Array::Iterator, an
    exception is thrown if that condition is violated. They are documented
    here only for people interested in subclassing Array::Iterator.

    _current_index
        An lvalue-ed subroutine which allows access to the iterator's
        internal pointer.

    _iteratee
        This returns the item being iteratated over, in our case an array.

    _getItem ($iteratee, $index)
        This method is used by all other routines to access items with.
        Given the iteratee and an index, it will return the item being
        stored in the $iteratee at the index of $index.

TO DO
    Improve BiDirectional Test suite
        I want to test the back and forth a little more, make sure they work
        well with one another.

    Other Iterators
        Array::Iterator::BiDirectional::Circular, Array::Iterator::Skipable
        and Array::Iterator::BiDirectional::Skipable are just a few ideas I
        have had. I am going to hold off for now until I am sure they are
        actually useful.

BUGS
    None that I am aware of. The code is pretty thoroughly tested (see "CODE
    COVERAGE" below) and is based on an (non-publicly released) module which
    I had used in production systems for about 2 years without incident. Of
    course, if you find a bug, let me know, and I will be sure to fix it.

CODE COVERAGE
    I use Devel::Cover to test the code coverage of my tests, below is the
    Devel::Cover report on this module's test suite.

     ------------------------------- ------ ------ ------ ------ ------ ------ ------
     File                              stmt   bran   cond    sub    pod   time  total
     ------------------------------- ------ ------ ------ ------ ------ ------ ------
     Array/Iterator.pm                100.0  100.0   66.7  100.0  100.0   67.6   98.2
     Array/Iterator/BiDirectional.pm  100.0  100.0    n/a  100.0  100.0   20.2  100.0
     Array/Iterator/Circular.pm       100.0  100.0    n/a  100.0  100.0    7.1  100.0
     Array/Iterator/Reusable.pm       100.0    n/a    n/a  100.0  100.0    5.0  100.0
     ------------------------------- ------ ------ ------ ------ ------ ------ ------
     Total                            100.0  100.0   66.7  100.0  100.0  100.0   99.0
     ------------------------------- ------ ------ ------ ------ ------ ------ ------

SEE ALSO
    This module now includes several subclasses of Array::Iterator which add
    certain behaviors to Array::Iterator, they are:

    Array::Iterator::BiDirectional
        Adds the ability to move backwards and forwards through the array.

    Array::Iterator::Circular
        When this iterator reaches the end of its list, it will loop back to
        the start again.

    Array::Iterator::Reusable
        This iterator can be reset to its begining and used again.

    The Design Patterns book by the Gang of Four, specifically the Iterator
    pattern.

    Some of the interface for this class is based upon the Java Iterator
    interface.

OTHER ITERATOR MODULES
    There are a number of modules on CPAN with the word Iterator in them.
    Most of them are actually iterators included inside other modules, and
    only really useful within that parent modules context. There are however
    some other modules out there that are just for pure iteration. I have
    provided a list below of the ones I have found, if perhaps you don't
    happen to like the way I do it.

    Tie::Array::Iterable
        This module ties the array, something we do not do. But it also
        makes an attempt to account for, and allow the array to be changed
        during iteration. It accomplishes this control because the
        underlying array is tied. As we all know, tie-ing things can be a
        performance issue, but if you need what this module provides, then
        it will likely be an acceptable compromise. Array::Iterator makes no
        attempt to deal with this mid-iteration manipulation problem. In
        fact it is recommened to not alter your array with Array::Iterator,
        and if possible we will enforce this in later versions.

    Data::Iter
        This module allows for simple iteratation over both hashes and
        arrays. It does it by importing several functions which can be used
        to loop over either type (hash or array) in the same way. It is an
        interesting module, it differs from Array::Iterator in paradigm
        (Array::Iterator is more OO) as well as in intent.

    Class::Iterator
        This is essentially a wrapper around a closure based iterator. This
        method can be very flexible, but at times is difficult to manage due
        to the inherent complextity of using closures. I actually was a
        closure-as-iterator fan for a while, but eventually moved away from
        it in favor of the more plain vanilla means of iteration, like that
        found Array::Iterator.

    Class::Iter
        This is part of the Class::Visitor module, and is a Visitor and
        Iterator extensions to Class::Template. Array::Iterator is a
        standalone module not associated with others.

    Data::Iterator::EasyObj
        Data::Iterator::EasyObj makes your array of arrays into iterator
        objects. It also has the ability to further nest additional data
        structures including Data::Iterator::EasyObj objects.
        Array::Iterator is one dimensional only, and does not attempt to do
        many of the more advanced features of this module.

ACKNOWLEDGEMENTS
    Thanks to Hugo Cornelis for pointing out a bug in "peek()"
    Thanks to Phillip Moore for providing the patch to allow single element
    iteration through the hash-ref constructor parameter.

ORIGINAL AUTHOR
    stevan little, &lt;stevan@iinteractive.com&gt;

ORIGINAL COPYRIGHT AND LICENSE
    Copyright 2004, 2005 by Infinity Interactive, Inc.

    &lt;http://www.iinteractive.com&gt;

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

AUTHOR
    Steven Haryanto &lt;stevenharyanto@gmail.com&gt;

COPYRIGHT AND LICENSE
    This software is copyright (c) 2011 by Steven Haryanto.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.

</pre></body></html>