Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Array::Iterator(3)    User Contributed Perl Documentation   Array::Iterator(3)

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

VERSION
       This document describes version 0.12 of Array::Iterator (from Perl
       distribution Array-Iterator), released on 2017-07-04.

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);

	 # 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
	 }

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).

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.

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, <stevan@iinteractive.com>

ORIGINAL COPYRIGHT AND LICENSE
       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.

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->new({ __array__ => \@array });

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

	   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.

       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->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([$n])
	   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.

	   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.

       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.

       _get_item ($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.

HOMEPAGE
       Please visit the	project's homepage at
       <https://metacpan.org/release/Array-Iterator>.

SOURCE
       Source repository is at
       <https://github.com/sharyanto/perl-Array-Iterator>.

BUGS
       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.

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 beginning 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.

AUTHOR
       perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2017, 2013, 2012,	2011 by
       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.

perl v5.32.0			  2017-07-04		    Array::Iterator(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | TO DO | OTHER ITERATOR MODULES | ACKNOWLEDGEMENTS | ORIGINAL AUTHOR | ORIGINAL COPYRIGHT AND LICENSE | METHODS | HOMEPAGE | SOURCE | BUGS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Array::Iterator&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help