/ 
Iterator-Simple-Util-0.002
River stage zero No dependents
/ Iterator::Simple::Util

NAME

Iterator::Simple::Util - Port of List::Util and List::MoreUtils to Iterator::Simple

VERSION

version 0.002

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.