Util(3pm) User Contributed Perl Documentation Util(3pm)
NAME
Iterator::Util - Essential utilities for the Iterator class.
VERSION
This documentation describes version 0.02 of Iterator::Util, August 23,
2005.
SYNOPSIS
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);
DESCRIPTION
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.
FUNCTIONS
imap
$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.
Examples:
$evens = imap { $_ * 2 } irange (0); # returns 0, 2, 4, ...
$squares = imap { $_ * $_ } irange (7); # 49, 64, 81, 100, ...
igrep
$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.
Examples:
$fives = igrep { $_ % 5 == 0 } irange (0,10); # returns 0, 5, 10
$small = igrep { $_ < 10 } irange (8,12); # returns 8, 9
irange
$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.
Examples:
$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.
ilist
$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.
Example:
$iter = ilist (4, 'minus five', @foo, 7);
$val = $iter->value(); # $val is now 4
$val = $iter->value(); # $val is now 'minus five'
...
iarray
$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.
ihead
$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.
Examples:
$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.
iappend
$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.
ipairwise
$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
exhausted.
This function is analogous to the pairwise function from
List::MoreUtils.
Example:
$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, ...
iskip
$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.
Example:
$iter = ilist (24, -1, 7, 8); # Bunch of random values
$cdr = iskip 1, $iter; # "pop" the first value
$val = $cdr->value(); # $val is -1.
iskip_until
$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 $_.
Example:
$iter = iskip_until {$_ > 5} irange 1; # returns 6, 7, 8, 9, ...
imesh
izip
$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.
Example:
$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".
iuniq
$iter = iuniq ($another_iterator);
Creates an iterator to return unique values from another iterator;
weeds out duplicates.
Example:
$iter = ilist (1, 2, 2, 3, 1, 4);
$uniq = iuniq ($iter); # returns 1, 2, 3, 4.
EXPORTS
All function names are exported to the caller's namespace by default.
DIAGNOSTICS
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.
• 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.
• 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."
• 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 $@.
• 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 $!.
• 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.
REQUIREMENTS
Requires the following additional modules:
Iterator
SEE ALSO
Higher Order Perl, Mark Jason Dominus, Morgan Kauffman 2005.
<http://perl.plover.com/hop/>
THANKS
Much thanks to Will Coleda and Paul Lalli (and the RPI lily crowd in
general) for suggestions for the pre-release version.
AUTHOR / COPYRIGHT
Eric J. Roode, roode@cpan.org
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
message.
perl v5.32.0 2020-12-28 Util(3pm)
Generated by dwww version 1.14 on Fri Jan 24 09:37:01 CET 2025.