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

FreeBSD Manual Pages


home | help
Util(3)		      User Contributed Perl Documentation	       Util(3)

       Iterator::Util -	Essential utilities for	the Iterator class.

       This documentation describes version 0.02 of Iterator::Util, August 23,

	use Iterator::Util;

	# Transform sequences
	$iterator = imap { transformation code } $some_other_iterator;

	# Filter sequences
	$iterator = igrep { condition code } $some_other_iterator;

	# Range	of values  (arithmetic sequence)
	$iter =	irange ($start,	$end, $increment);
	$iter =	irange ($start,	$end);
	$iter =	irange ($start);

	# Iterate over an arbitrary list
	$iter =	ilist (item, item, ...);
	$iter =	ilist (@items);

	# Iterate over an array, by reference
	$iter =	iarray (\@array);

	# Return at most $num items from an iterator
	$iter	= ihead	($num, $some_other_iterator);
	@values	= ihead	($num, $some_other_iterator);

	# Append multiple iterators into one
	$iter =	iappend	($it1, $it2, $it3, ...);

	# Apply	a function to pairs of iterator	values
	$iter =	ipairwise {code} $iter_A, $iter_B;

	# Skip the first $num values of	an iterator
	$iter =	iskip ($num, $some_other_iterator);

	# Skip values from an iterator until a condition is met
	$iter =	iskip_until {code} $some_other_iterator;

	# Mesh iterators together
	$iter =	imesh ($iter, $iter, ...);
	$iter =	izip  ($iter, $iter, ...);

	# Return each value of an iterator once
	$iter =	iuniq ($another_iterator);

       This module implements many useful functions for	creating and
       manipulating iterator objects.

       An "iterator" is	an object, represented as a code block that generates
       the "next value"	of a sequence, and generally implemented as a closure.
       For further information,	including a tutorial on	using iterator
       objects,	see the	Iterator documentation.

	    $iter = imap { transformation code } $some_other_iterator;

	   Returns an iterator that is a transformation	of some	other
	   iterator.  Within the transformation	code, $_ is set	to each	value
	   of the other	iterator, in turn.


	    $evens   = imap { $_ * 2  }	 irange	(0);  #	returns	0, 2, 4, ...
	    $squares = imap { $_ * $_ }	 irange	(7);  #	49, 64,	81, 100, ...

	    $iter = igrep { condition }	$some_other_iterator;

	   Returns an iterator that selectively	returns	values from some other
	   iterator.  Within the "condition" code, $_ is set to	each value of
	   the other iterator, in turn.


	    $fives = igrep { $_	% 5 == 0 } irange (0,10);   # returns 0, 5, 10
	    $small = igrep { $_	< 10 }	   irange (8,12);   # returns 8, 9

	    $iter = irange ($start, $end, $increment);
	    $iter = irange ($start, $end);
	    $iter = irange ($start);

	   "irange" returns a sequence of numbers.  The	sequence begins	with
	   $start, ends	at $end, and steps by $increment.  This	is sort	of the
	   Iterator version of a "for" loop.

	   If $increment is not	specified, 1 is	used.  $increment may be
	   negative -- or even zero, in	which case iterator returns an
	   infinite sequence of	$start.

	   If $end is not specified (is	"undef"), the sequence is infinite.


	    $iter = irange (1, 2);	     #	Iterate	from 1 to 2
	    $val  = $iter->value();	     #	$val is	now 1.
	    $val  = $iter->value();	     #	$val is	now 2.
	    $bool = $iter->is_exhausted();   #	$bool is now true.

	    $iter = irange (10,	8, -1);	     #	Iterate	from 10	down to	8
	    $iter = irange (1);		     #	Iterate	from 1,	endlessly.

	    $iter = ilist (@items);

	   Returns an iterator that iterates over an arbitrary sequence	of
	   values.  It's sort of an Iterator version of	"foreach".

	   This	function makes an internal copy	of the list, so	it may not be
	   appropriate for an extremely	large list.


	    $iter = ilist (4, 'minus five', @foo, 7);
	    $val  = $iter->value();	     # $val is now 4
	    $val  = $iter->value();	     # $val is now 'minus five'

	    $iter = iarray (\@array);

	   Returns an iterator that iterates over an array.  Note that since
	   it uses a reference to that array, if you modify the	array, that
	   will	be reflected in	the values returned by the iterator.  This may
	   be What You Want.  Or it may	cause Hard-To-Find Bugs.

	    $iter   = ihead ($num, $some_other_iterator);
	    @values = ihead ($num, $some_iterator);

	   In scalar context, creates an iterator that returns at most $num
	   items from another iterator,	then stops.

	   In list context, returns the	first $num items from the iterator.
	   If $num is "undef", all remaining values are	pulled from the
	   iterator until it is	exhausted.  Use	"undef"	with caution;
	   iterators can be huge -- or infinite.


	    $iota5 = ihead 5, irange 1;	   # returns 1,	2, 3, 4, 5.

	    $iter = irange 1;		 # infinite sequence, starting with 1
	    @vals = ihead (5, $iter);	 # @vals is (1,	2, 3, 4, 5)
	    $nextval = $iter->value;	 # $nextval is 6.

	    $iter = iappend (@list_of_iterators);

	   Creates an iterator that consists of	any number of other iterators
	   glued together.  The	resulting iterator pulls values	from the first
	   iterator until it's exhausted, then from the	second,	and so on.

	    $iter = ipairwise {code} $it_A, $it_B;

	   Creates a new iterator which	applies	"{code}" to pairs of elements
	   of two other	iterators, $it_A and $it_B in turn.  The pairs are
	   assigned to $a and $b before	invoking the code.

	   The new iterator is exhausted when either $it_A or $it_B are

	   This	function is analogous to the pairwise function from


	    $first  = irange 1;				     # 1,  2,  3,  4, ...
	    $second = irange 4,	undef, 2;		     # 4,  6,  8, 10, ...
	    $third  = ipairwise	{$a * $b} $first, $second;   # 4, 12, 24, 40, ...

	    $iter = iskip ($num, $another_iterator);

	   Returns an iterator that contains the values	of $another_iterator,
	   minus the first $num	values.	 In other words, skips the first $num
	   values of $another_iterator.


	    $iter = ilist (24, -1, 7, 8);	 # Bunch of random values
	    $cdr  = iskip 1, $iter;		 # "pop" the first value
	    $val  = $cdr->value();		 # $val	is -1.

	    $iter = iskip_until	{code} $another_iterator;

	   Returns an iterator that skips the leading values of
	   $another_iterator until "{code}" evaluates to true for one of its
	   values.  "{code}" can refer to the current value as $_.


	    $iter = iskip_until	{$_ > 5}  irange 1;    # returns 6, 7, 8, 9, ...

	    $iter = imesh ($iter1, $iter2, ...);

	   This	iterator accepts any number of other iterators,	and "meshes"
	   their values	together.  First it returns the	first value of the
	   first iterator, then	the first value	of the second iterator,	and so
	   on, until it	has returned the first value of	all of its iterator
	   arguments.  Then it goes back and returns the second	value of the
	   first iterator, and so on.  It stops	when any of its	iterator
	   arguments is	exhausted.


	    $i1	= ilist	('a', 'b', 'c');
	    $i2	= ilist	(1, 2, 3);
	    $i3	= ilist	('rock', 'paper', 'scissors');
	    $iter = imesh ($i1,	$i2, $i3);
	    # $iter will return, in turn, 'a', 1, 'rock', 'b', 2, 'paper', 'c',...

	   "izip" is a synonym for "imesh".

	    $iter = iuniq ($another_iterator);

	   Creates an iterator to return unique	values from another iterator;
	   weeds out duplicates.


	    $iter = ilist (1, 2, 2, 3, 1, 4);
	    $uniq = iuniq ($iter);	      #	returns	1, 2, 3, 4.

       All function names are exported to the caller's namespace by default.

       Iterator::Util uses Exception::Class objects for	throwing exceptions.
       If you're not familiar with Exception::Class, don't worry; these
       exception objects work just like	$@ does	with "die" and "croak",	but
       they are	easier to work with if you are trapping	errors.

       See the Iterator	module documentation for more information on trapping
       and handling these exceptions.

       o   Parameter Errors

	   Class: "Iterator::X::Parameter_Error"

	   You called an Iterator method with one or more bad parameters.
	   Since this is almost	certainly a coding error, there	is probably
	   not much use	in handling this sort of exception.

	   As a	string,	this exception provides	a human-readable message about
	   what	the problem was.

       o   Exhausted Iterators

	   Class: "Iterator::X::Exhausted"

	   You called "value|Iterator/value" on	an iterator that is exhausted;
	   that	is, there are no more values in	the sequence to	return.

	   As a	string,	this exception is "Iterator is exhausted."

       o   User	Code Exceptions

	   Class: "Iterator::X::User_Code_Error"

	   This	exception is thrown when the sequence generation code throws
	   any sort of error besides "Am_Now_Exhausted".  This could be
	   because your	code explicitly	threw an error (that is, "die"d), or
	   because it otherwise	encountered an exception (any runtime error).

	   This	exception has one method, "eval_error",	which returns the
	   original $@ that was	trapped	by the Iterator	object.	 This may be a
	   string or an	object,	depending on how "die" was invoked.

	   As a	string,	this exception evaluates to the	stringified $@.

       o   I/O Errors

	   Class: "Iterator::X::IO_Error"

	   This	exception is thrown when any sort of I/O error occurs; this
	   only	happens	with the filesystem iterators.

	   This	exception has one method, "os_error", which returns the
	   original $! that was	trapped	by the Iterator	object.

	   As a	string,	this exception provides	some human-readable
	   information along with $!.

       o   Internal Errors

	   Class: "Iterator::X::Internal_Error"

	   Something happened that I thought couldn't possibly happen.	I
	   would appreciate it if you could send me an email message detailing
	   the circumstances of	the error.

       Requires	the following additional modules:


       Higher Order Perl, Mark Jason Dominus, Morgan Kauffman 2005.


       Much thanks to Will Coleda and Paul Lalli (and the RPI lily crowd in
       general)	for suggestions	for the	pre-release version.

       Eric J. Roode,

       Copyright (c) 2005 by Eric J. Roode.  All Rights	Reserved.  This	module
       is free software; you can redistribute it and/or	modify it under	the
       same terms as Perl itself.

       To avoid	my spam	filter,	please include "Perl", "module", or this
       module's	name in	the message's subject line, and/or GPG-sign your

perl v5.32.1			  2005-08-23			       Util(3)


Want to link to this manual page? Use this URL:

home | help