NAME

Array::Iterator - A simple class for iterating over Perl arrays

SYNOPSIS

use Array::Iterator;

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

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

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

# shortcut style
my @accumulation;
push @accumulation => { item => $iterator->next() } while $iterator->hasNext();

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

# common perl iterator idiom
my $current;
while ($current = $i->getNext()) {
  # ... 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)

The constructor can be passed either a plain perl array or an array reference. Single element arrays are not allowed, as they do not make sense anyway. An exception will be thrown if any of the following conditions are meet; a single element array is given, a non-array reference is given.

hasNext

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.

getNext

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->getNext()) {
    ...
}

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 hasNext/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 now advance the internal pointer. This value will match the last value dispensed by next or getNext.

currentIndex

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

Template Methods

These methods are not to be used publically, and are documented here for those who want to extend this class. These two methods provide all the storage (_init) and access (_getItem) to the elements being iterated over. By overriding these two methods (and probably new as well), you can change the behavior of the iterator and still have the other methods behave accordingly.

_init ($length, $iteratee)

This method simply places the item to iterate over ($iteratee) and its calculated length ($length) into slots where the other methods expect to find them.

_getItem ($iteratee, $index)

This method handles all the element accessing. It takes an iteratee and and index, and returns the item found at that index.

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 1 year 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 branch   cond    sub    pod   time  total
-------------------------------- ------ ------ ------ ------ ------ ------ ------
/Array/Iterator.pm                100.0  100.0   66.7  100.0  100.0    8.8   97.5
t/10_Array_Iterator_test.t        100.0  100.0    n/a    n/a    n/a   59.4  100.0
t/20_Array_Iterator_exceptions.t  100.0    n/a    n/a  100.0    n/a   31.8  100.0
-------------------------------- ------ ------ ------ ------ ------ ------ ------
Total                             100.0  100.0   66.7  100.0  100.0  100.0   98.9
-------------------------------- ------ ------ ------ ------ ------ ------ ------

SEE ALSO

Design Patterns by the Gang of Four. Specifically the Iterator pattern.

Part of the interface for this Iterator is based upon the Java Iterator interface.

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.

AUTHOR

stevan little, <stevan@iinteractive.com>

COPYRIGHT AND LICENSE

Copyright 2004 by Infinity Interactive, Inc.

http://www.iinteractive.com

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