view release on metacpan or  search on metacpan

lib/List/Pairwise.pod  view on Meta::CPAN

    mapp {
        print "$a: $b\n";
    } %hash;

    mapp {
        print "$a: $b\n";
    } @list;

=item grepp BLOCK LIST

=item grep_pairwise BLOCK LIST

Evaluates the BLOCK in scalar context for each pair of LIST (locally
setting $a and $b to each pair) and returns the list value
consisting of those pairs for which the expression evaluated
to true.
In scalar context, returns the number of valid pairs, ie the
number of times the expression was true.

So this equality stands:

    (grepp BLOCK LIST) == 1/2 * scalar(my @list = (grepp BLOCK LIST))

Note that $a and $b are aliases to the list elements, so they can be used to
modify the elements of the LIST, exept for hash keys ($a when LIST is a hash).

C<grep_pairwise> is an alias for C<grepp>.

grep hash subset:

    my %subset1 = grepp {$a =~ /^ba/} %hash;
    my %subset2 = grepp {$b < 5} %hash;

grep specific values:

    my @values = mapp {$b} grepp {$a =~ /^ba/} %hash;

This does not work:

    values grepp {$a =~ /^ba/} %hash;

values() and keys() expect a hash, whereas grepp returns a list

=item firstp BLOCK LIST

=item first_pairwise BLOCK LIST

Evaluates the BLOCK in scalar context for each pair of LIST (locally
setting $a and $b to each pair) and returns the first pair for
which the expression evaluated to true.
In scalar context, returns 1 if a valid pair was found.

C<firstp> can be used to iterate lists pairwise as does C<mapp>, but with
the additional option of using the value returned by the BLOCK as a C<last>
statement

    my $i;
    firstp {
        print "$a: $b\n";
        ++$i==5 # last after 5 iterations
    } %hash;

=item lastp BLOCK LIST

=item last_pairwise BLOCK LIST

Evaluates the BLOCK in scalar context for each pair of LIST (locally
setting $a and $b to each pair) and returns the last pair for
which the expression evaluated to true.
In scalar context, returns 1 if a valid pair was found.

=item pair LIST

Returns a list of pairs as array references.

    my @pairs = pair @list;
    my @pairs = mapp {[$a, $b]} @list; # same, but slower

C<pair> can be used in combination with sort, map and grep to do ordered
hash-like manipulations in long chains/streams:

    my @ranges =
        sort { $a->[0] <=> $b->[0] or $a->[1] <=> $b->[1] }
        grep { $_->[0] < $_->[1] }
        pair
        /\b(\d+)-(\d+)\b/g
    ;

=back

=head1 EXPORTS

Nothing by default.
Functions can be imported explicitely

    use List::Pairwise qw(mapp grepp first_pairwise);

You can use the :all tag to import all functions, including *_pairwise aliases

    use List::Pairwise qw(:all);

=head1 CAVEATS

In prior versions, List::Pairwise function did croak when given a list with an odd
number of elements. This is not the case anymore: a warning will now be emitted if
warnings of the 'misc' category are enabled, and the last pair will be completed
with an undefined value.
The old behavior can be restored by making these misc warnings FATAL:

    use warnings FATAL => 'misc';


=head1 TEST COVERAGE

As of List::Pairwise version 0.28:

    ---------------------------- ------ ------ ------ ------ ------ ------ ------
    File                           stmt   bran   cond    sub    pod   time  total
    ---------------------------- ------ ------ ------ ------ ------ ------ ------
    lib/List/Pairwise.pm          100.0  100.0  100.0  100.0  100.0   88.0  100.0