NAME
Iterator::Simple::Util - Port of List::Util and List::MoreUtils to
Iterator::Simple
VERSION
version 0.001
SYNOPSIS
use Iterator::Simple::Util qw( igroup ireduce isum
imax imin imaxstr iminstr imax_by imin_by imaxstr_by iminstr_by
iany inone inotall
ifirstval ilastval
ibefore ibefore_incl iafter iafter_incl
inatatime );
DESCRIPTION
Iterator::Simple::Util implements many of the functions from List::Util
and List::MoreUtils for iterators generated by Iterator::Simple.
EXPORTS
All of these functions call "Iterator::Simple::iter()" on the
**ITERABLE** argument; this detects what **ITERABLE** is and turns it
into an iterator. See iterator::Simple for details.
Functions taking a *BLOCK* expect a code block that operates on $_ or,
in the case of igroup and ireduce, on $a and $b.
igroup *BLOCK* *ITERABLE*
ireduce *BLOCK* [*INIT_VAL*] *ITERABLE*
Reduces *ITERABLE* by calling *BLOCK*, in a scalar context, multiple
times, setting $a and $b each time. The first call will be with $a
and $b set to the first two elements of the list, subsequent calls
will be done by setting $a to the result of the previous call and $b
to the next element in the list.
Returns the result of the last call to *BLOCK*. If the iterator is
empty then "undef" is returned. If the iterator only contains one
element then that element is returned and *BLOCK* is not executed.
$foo = ireduce { $a < $b ? $a : $b } $iterator # min
$foo = ireduce { $a lt $b ? $a : $b } $iterator # minstr
$foo = ireduce { $a + $b } $iterator # sum
$foo = ireduce { $a . $b } $iterator # concat
If your algorithm requires that "reduce" produce an identity value,
then make sure that you always pass that identity value as the first
argument to prevent "undef" being returned. For example:
$foo = ireduce { $a + $b } 0, $iterator
will return 0 (rather than "undef") when $iterator is empty.
isum [*INIT_VAL*] *ITERABLE*
Returns the sum of the elements of *ITERABLE*, which should return
numeric values. Returns 0 if the iterator is empty.
imax *ITERABLE*
Returns the maximum value of *ITERABLE*, which should produce
numeric values. Retruns "undef" if the iterator is empty.
imin *ITERABLE*
Returns the minimum value of *ITERABLE*, which should produce
numeric values. Returns "undef" if the iterator is empty.
imax_by *BLOCK* *ITERABLE*
Return the value of *ITERABLE* for which *BLOCK* produces the
maximum value. For example:
imax_by { $_ * $_ } iter( [ -5 -2 -1 0 1 2 ] )
will return -5.
imin_by *BLOCK* *ITERABLE*
Similar to imax_by, but returns the value of *ITERABLE* for which
*BLOCK* produces the minimum value.
imaxstr *ITERABLE*
Similar to imax, but expects *ITERABLE* to return string values.
iminstr *ITERABLE*
Similar to imin, but expects *ITERABLE* to return string values.
imaxstr_by *BLOCK* *ITERABLE*
Similar to imax_by, but expects *ITERABLE* to return string values.
iminstr_by *BLOCK* *ITERABLE*
Similar to imin_by, but expects *ITERABLE* to return string values.
iany *BLOCK* *ITERABLE*
Returns a true value if any item produced by *ITERABLE* meets the
criterion given through *BLOCK*. Sets $_ for each item in turn:
print "At least one value greater than 10"
if iany { $_ > 10 } $iterator;
Returns false otherwise, or if the iterator is empty.
inone *BLOCK* *ITERABLE*
Returns a true value if no item produced by *ITERABLE* meets the
criterion given through *BLOCK*, or if the iterator is empty. Sets
$_ for each item in turn:
print "No values greater than 10"
if inone { $_ > 10 } $iterator;
Returns false otherwise.
inotall *BLOCK* *ITERABLE*
Logically the negation of *all*. Returns true if *BLOCK* returns
false for some value of *ITERABLE*:
print "Not all even"
if inotall { $_ % 2 == 0 } $iterator;
Returns false if the iterator is empty, or all values of *BLOCK*
produces a true value for every item produced by *ITERABLE*.
ifirstval *BLOCK* *ITERABLE*
Returns the first element produced by *ITERABLE* for which *BLOCK*
evaluates to true. Each element produced by *ITERABLE* is set to $_
in turn. Returns "undef" if no such element has been found.
ilastval *BLOCK* *ITERABLE*
Returns the last element produced by *ITERABLE* for which *BLOCK*
evaluates to true. Each element of *ITERABLE* is set to $_ in turn.
Returns "undef" if no such element has been found.
ibefore *BLOCK* *ITERABLE*
Returns an iterator that will produce all values of *ITERABLE* upto
(and not including) the point where *BLOCK* returns a true value.
Sets $_ for each element in turn.
ibefore_incl *BLOCK* *ITERABLE*
Returns an iterator that will produce all values of *ITERABLE* upto
(and including) the point where *BLOCK* returns a true value. Sets
$_ for each element in turn.
iafter *BLOCK* *ITERABLE*
Returns an iterator that will produce all values of *ITERABLE* after
(and not including) the point where *BLOCK* returns a true value.
Sets $_ for each element in turn.
$it = iafter { $_ % 5 == 0 } [1..9]; # $it returns 6, 7, 8, 9
iafter_incl *BLOCK*_*ITERABLE*
Returns an iterator that will produce all values of *ITERABLE* after
(and including) the point where *BLOCK* returns a true value. Sets
$_ for each element in turn.
$it = iafter_incl { $_ % 5 == 0 } [1..9]; # $it returns 5, 6, 7, 8, 9
inatatime *KICKS* *ITERABLE*
Creates an array iterator that returns array refs of elements from
*ITERABLE, *KICKS* items at a time. For example:*
my $it = inatatime 3, iter( [ 'a' .. 'g' ] );
while( my $vals = $it->next ) {
print join( ' ', @{$vals} ) . "\n";
}
This prints:
a b c
d e f
g
AUTHOR
Ray Miller <raym@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2012 by Ray Miller.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
POD ERRORS
Hey! The above document had some coding errors, which are explained
below:
Around line 529:
Unterminated I<...> sequence