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

