| Array::Iterator(3pm) | User Contributed Perl Documentation | Array::Iterator(3pm) |
Array::Iterator - A simple class for iterating over Perl arrays
This document describes version 0.131 of Array::Iterator (from Perl distribution Array-Iterator), released on 2021-09-26.
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);
# create an iterator with a hash reference
my $i = Array::Iterator->new({ __array__ => \@array });
# a base iterator example
while ($i->has_next()) {
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->has_next();
# C++ ish style iterator
for (my $i = Array::Iterator->new(@array); $i->has_next(); $i->next()) {
my $current = $i->current();
# .. do something with current
}
# common perl iterator idiom
my $current;
while ($current = $i->get_next()) {
# ... do something with $current
}
This class provides a very simple iterator interface. It is uni-directional and can only be used once. It provides no means of reversing or resetting 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).
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.
my $i = Array::Iterator->new({ __array__ => \@array });
Takes an optional positive integer (> 0) that specifies the position you want to check. This allows you to check if there an element at arbitrary position. Think of it as an ordinal number you want to check:
$i->has_next(2); # 2nd next element $i->has_next(10); # 10th next element
Note that has_next(1) is the same as "has_next()".
Throws an exception if $n <= 0.
This method was added to allow for a fairly common perl iterator idiom of:
my $current;
while ($current = $i->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.
Takes an optional positive integer (> 0) that specifies how far ahead you want to peek:
$i->peek(2); # gives you 2nd next element $i->peek(10); # gives you 10th next element
Note that peek(1) is the same as "peek()".
Throws an exception if $n <= 0.
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. This not the case when calling with an argument that is <= 0 though, as it's clearly a sign of incorrect usage.
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.
Please visit the project's homepage at <https://metacpan.org/release/Array-Iterator>.
Source repository is at <https://github.com/perlancar/perl-Array-Iterator>.
This module now includes several subclasses of Array::Iterator which add certain behaviors to Array::Iterator, they are:
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.
perlancar <perlancar@cpan.org>
stevan little, <stevan@iinteractive.com>
To contribute, you can send patches by email/via RT, or send pull requests on GitHub.
Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via:
% prove -l
If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla plugin and/or Pod::Weaver::Plugin. Any additional steps required beyond that are considered a bug and can be reported to me.
This software is copyright (c) 2021, 2017, 2013, 2012, 2011 by perlancar <perlancar@cpan.org>.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
Copyright 2004, 2005 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.
Please report any bugs or feature requests on the bugtracker website <https://rt.cpan.org/Public/Dist/Display.html?Name=Array-Iterator>
When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.
| 2022-10-13 | perl v5.34.0 |