NAME

List::MoreUtil - More list utility functions.

VERSION

This documentation describes version 0.01 of List::MoreUtil, October 11, 2004.

SYNOPSIS

 # Boolean test functions
 $bool = all  {code}  @list    # True if <code> is true for all <@list>
 $bool = any  {code}  @list    # True if <code> is true for any <@list>
 $bool = none {code}  @list    # True if <code> is false for all <@list>

 # Grep-like functions
 @list = after       {code} @list   # Values of <@list> after where {code} is true
 @list = after_incl  {code} @list   # Values of <@list> after (and including) where {code} is true
 @list = before      {code} @list   # Values of <@list> before where {code} is true
 @list = before_incl {code} @list   # Values of <@list> before (and including) where {code} is true

 # Map-like functions
 @list = mesh @array, ...           # Merge several arrays together
 @list = pairwise {code} @a, @b     # Apply a function to two arrays

 # Selection functions
 $num = first_index {code} @list    # First index into <@list> where {code} is true
 $val = first_value {code} @list    # First value of <@list> where {code} is true
 @num = indexes     {code} @list    # Indexes into <@list> where {code} is true
 $num = last_index  {code} @list    # Last index into <@list> where {code} is true
 $val = last_value  {code} @list    # Last value of <@list> where {code} is true
 $num = max  @list       # Maximum value of <@list> (numerically)
 $str = maxs @list       # Maximum value of <@list> (string comparison)
 $num = min  @list       # Minimum value of <@list> (numerically)
 $str = mins @list       # Minimum value of <@list> (string comparison)

 # Looping helpers
 $it = each_array    @array, ...    # Loop over several arrays at once
 $it = each_arrayref $arref, ...    # Loop over several array references at once
 $it = natatime $n, @list           # Loop over a list, taking several values at once

DESCRIPTION

This module is a loose collection of miscellaneous list/array utility functions that I have written over the years. They've been useful to me, and I am making them available to others in the hope that they will find them useful as well.

The only common thread between these functions is that they all operate on lists of variables -- tranforming them, selecting from them, looping over them.

FUNCTIONS

after

 @list = after {code} @list;

Returns a list of the values of @list after (and not including) the point where {code} returns a true value. Each element of the input list is assigned to $_ (as an lvalue alias) in turn before invoking the test code.

Example:

    @x = after {$_ % 5 == 0} (1..9);    # returns 6, 7, 8, 9

after_incl

 @list = after_incl {code} @list;

Returns a list of the values of @list after (and including) the point where {code} returns a true value. Each element of the input list is assigned to $_ (as an lvalue alias) in turn before invoking the test code.

This is almost the same as after, except that it includes the value in the list where {code} first returned true.

Example:

    @x = after_incl {$_ % 5 == 0} (1..9);    # returns 5, 6, 7, 8, 9

all

 $bool = all {code} @list;

Returns true if {code} evaluates true for all elements of @list. Each element is passed in turn to {code} as $_. $_ acts as an lvalue alias, like it does for map.

Examples:

     $x = all {$_ > 5} (1..10);    # false
     $y = all {$_ > 5} (10..20);   # true

any

 $bool = any {code} @list;

Returns true if {code} evaluates true for any element of @list. Each element is passed in turn to {code} as $_. $_ acts as an lvalue alias, like it does for map.

Examples:

     $x = any {$_ > 5} (1..5);    # false
     $y = any {$_ > 5} (1..10);   # true

before

 @list = before {code} @list;

Returns a list of the values of @list up until (but not including) the point where {code} returns a true value. Each element of the input list is assigned to $_ (as an lvalue alias) before invoking the test code.

Example:

    @x = before {$_ % 5 == 0} (1..9);    # returns 1, 2, 3, 4

before_incl

 @list = before_incl {code} @list;

Returns a list of the values of @list up to (and including) the point where {code} returns a true value. Each element of the input list is assigned to $_ (as an lvalue alias) in turn before invoking the test code.

This is almost the same as before, except that it includes the value in the list where {code} first returned true.

Example:

    @x = before_incl {$_ % 5 == 0} (1..9);    # returns 1, 2, 3, 4, 5

each_array

 $array_iterator = each_array(@a, @b, @c, ...);

Creates an array iterator to return the elements of a set of arrays in turn. That is, the first time it is called, it returns the first element of each array. The next time, it returns the second elements. And so on, until all elements are exhausted.

This is useful for looping over more than one array at once:

     my $ea = each_array(@a, @b, @c);
     while ( ($a,$b,$c) = $ea->() )   { .... }

If the iterator is passed an argument of 'index', then it retuns the index of the last fetched set of values, as a scalar.

each_arrayref

 $array_iterator = each_arrayref(\@a, \@b, \@c, ...);

Works like each_array(), but works on array references instead of arrays directly.

first_index

 $index = first_index {code} @list;

Returns the position in the argument list of the first value that satisfies a given condition. Each element is passed to {code} as $_ (as an lvalue alias, like for grep). Returns undef if no value in the list satisfies the condition.

Example:

     $x = first_index {$_ > 5}  (4..9);    # returns 2
     $x = first_index {$_ > 5}  (1..4);    # returns undef

first_value

 $value = first_value {code} @list;

Returns the first value that satisfies a given condition. Each element is passed to {code} as $_ (as an lvalue alias, like for grep). Returns undef if no value in the list satisfies the condition.

Example:

     $x = first_value {$_ > 5}  (4..9);    # returns 6
     $x = first_value {$_ > 5}  (1..4);    # returns undef

indexes

 @list = indexes {code} @list;

Returns a list of the indexes into @list of the values that satisfy the given condition. Sort of like grep, but returns index positions instead of values. Each element is passed to {code} as $_. (as an lvalue alias, like for grep). Returns the empty list if no value in the list satisfies the condition.

Example:

     @x = indexes {$_ > 5}  (4..9);    # returns (2, 3, 4, 5)
     @x = indexes {$_ > 5}  (1..4);    # returns ()

last_index

 $index = last_index {code} @list;

Returns the position in the argument list of the last value that satisfies a given condition. Each element is passed to {code} as $_ (as an lvalue alias, like for grep). Returns undef if no value in the list satisfies the condition.

Example:

     $x = last_index {$_ > 5}  (4..9);    # returns 5
     $x = last_index {$_ > 5}  (1..4);    # returns undef

last_value

 $value = last_value {code} @list;

Returns the last value in the list that satisfies a given condition. Each element is passed to {code} as $_ (as an lvalue alias, like for grep). Returns undef if no value in the list satisfies the condition.

Example:

     $x = last_value {$_ > 5}  (4..9);    # returns 9
     $x = last_value {$_ > 5}  (1..4);    # returns undef

max

 $scalar = max @list;

Returns the maximum (numerically) of a list of numbers.

maxs

 $scalar = maxs @list;

Returns the maximum (lexically) of a list of strings.

mesh

 @list = mesh @a, @b, ...;

Returns a list consisting of the first elements of each array, then the second, then the third, etc, until all arrays are exhausted.

Examples:

    @x = qw/a b c d/;
    @y = qw/1 2 3 4/;
    @z = mesh @x, @y;    # returns a, 1, b, 2, c, 3, d, 4

    @a = ('x');
    @b = ('1', '2');
    @c = qw/zip zap zot/;
    @d = mesh @a, @b, @c;   # x, 1, zip, undef, 2, zap, undef, undef, zot

min

 $scalar = min @list;

Returns the minimum (numerically) of a list of numbers.

mins

 $scalar = mins @list;

Returns the minimum (lexically) of a list of strings.

natatime

 $iterator = natatime $n, @list;

Creates an array iterator, for looping over an array in chunks of $n items at a time. (n at a time, get it?). An example is probably a better explanation than I could give in words.

Example:

     my @x = ('a'..'g');
     my $it = natatime 3, @x;
     while (my @vals = $it->())
     {
         print "@vals\n";
     }

This prints

     a b c
     d e f
     g

none

 $bool = none {code} @list;

Returns true if {code} evaluates false for all elements of @list. Each element is passed in turn to {code} as $_. $_ acts as an lvalue alias, like it does for map.

Example:

     $x = none {$_ > 5} (1..5);    # true
     $y = none {$_ > 5} (1..10);   # false

pairwise

 @c = pairwise {code} @a, @b;

Applies {code} to each pair of elements of @a, @b in turn. Returns a list of the results of that evaluation. The pairs are assigned to $a and $b before invoking the code. Note that $a and $b are lvalue aliases into the input arrays.

Examples:

    @a = (1, 2, 3); @b = (2, 4, 6);
    @c = pairwise {$a + $b} @a, @b;   # returns (3, 6, 9)
    @d = pairwise {$a * $b} @a, @b;   # returns (2, 8, 18)

EXPORTS

No symbols are exported by this module by default.

SEE ALSO

List::Util

AUTHOR / COPYRIGHT

Eric J. Roode, eric@cpan.org

Copyright (c) 2004 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.

If you have suggestions for improvement, please drop me a line. If you make improvements to this software, I ask that you please send me a copy of your changes. Thanks.