use List::MoreUtils qw(any all none notall true false firstidx first_index lastidx last_index insert_after insert_after_string apply after after_incl before before_incl indexes firstval first_value lastval last_value each_array each_arrayref pairwise natatime mesh zip uniq minmax);
All of the below functions are implementable in only a couple of lines of Perl code. Using the functions from this module however should give slightly better performance as everything is implemented in C. The pure-Perl implementation of these functions only serves as a fallback in case the C portions of this module couldn't be compiled on this machine.
print "At least one value undefined" if any { !defined($_) } @list;
Returns false otherwise, or "undef" if LIST is empty.
print "All items defined" if all { defined($_) } @list;
Returns false otherwise, or "undef" if LIST is empty.
print "No value defined" if none { defined($_) } @list;
Returns false otherwise, or "undef" if LIST is empty.
print "Not all values defined" if notall { defined($_) } @list;
Returns false otherwise, or "undef" if LIST is empty.
printf "%i item(s) are defined", true { defined($_) } @list;
printf "%i item(s) are not defined", false { defined($_) } @list;
my @list = (1, 4, 3, 2, 4, 6); printf "item with index %i in list is 4", firstidx { $_ == 4 } @list; __END__ item with index 1 in list is 4
Returns "-1" if no such item could be found.
"first_index" is an alias for "firstidx".
my @list = (1, 4, 3, 2, 4, 6); printf "item with index %i in list is 4", lastidx { $_ == 4 } @list; __END__ item with index 4 in list is 4
Returns "-1" if no such item could be found.
"last_index" is an alias for "lastidx".
my @list = qw/This is a list/; insert_after { $_ eq "a" } "longer" => @list; print "@list"; __END__ This is a longer list
my @list = qw/This is a list/; insert_after_string "a", "longer" => @list; print "@list"; __END__ This is a longer list
my @list = (1 .. 4); my @mult = apply { $_ *= 2 } @list; print "\@list = @list\n"; print "\@mult = @mult\n"; __END__ @list = 1 2 3 4 @mult = 2 4 6 8
Think of it as syntactic sugar for
for (my @mult = @list) { $_ *= 2 }
@x = after { $_ % 5 == 0 } (1..9); # returns 6, 7, 8, 9
@x = indexes { $_ % 2 == 0 } (1..10); # returns 1, 3, 5, 7, 9
"first_val" is an alias for "firstval".
"last_val" is an alias for "lastval".
@a = (1 .. 5); @b = (11 .. 15); @x = pairwise { $a + $b } @a, @b; # returns 12, 14, 16, 18, 20 # mesh with pairwise @a = qw/a b c/; @b = qw/1 2 3/; @x = pairwise { ($a, $b) } @a, @b; # returns a, 1, b, 2, c, 3
This is useful for looping over more than one array at once:
my $ea = each_array(@a, @b, @c); while ( my ($a, $b, $c) = $ea->() ) { .... }
The iterator returns the empty list when it reached the end of all arrays.
If the iterator is passed an argument of '"index"', then it retuns the index of the last fetched set of values, as a scalar.
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
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
"zip" is an alias for "mesh".
my @x = uniq 1, 1, 2, 2, 3, 5, 3, 4; # returns 1 2 3 5 4 my $x = uniq 1, 1, 2, 2, 3, 5, 3, 4; # returns 5
The minmax algorithm differs from a naive iteration over the list where each element is compared to two values being the so far calculated min and max value in that it only requires 3n/2 - 2 comparisons. Thus it is the most efficient possible algorithm.
However, the Perl implementation of it has some overhead simply due to the fact that there are more lines of Perl code involved. Therefore, LIST needs to be fairly big in order for minmax to win over a naive implementation. This limitation does not apply to the XS version.
Returns a list of the partitions thusly created. Each partition created is a reference to an array.
my $i = 0; my @part = part { $i++ % 2 } 1 .. 8; # returns [1, 3, 5, 7], [2, 4, 6, 8]
You can have a sparse list of partitions as well where non-set partitions will be undef:
my @part = part { 2 } 1 .. 10; # returns undef, undef, [ 1 .. 10 ]
Be careful with negative values, though:
my @part = part { -1 } 1 .. 10; __END__ Modification of non-creatable array value attempted, subscript -1 ...
Negative values are only ok when they refer to a partition previously created:
my @idx = (0, 1, -1); my $i = 0; my @part = part { $idx[$++ % 3] } 1 .. 8; # [1, 4, 7], [2, 3, 5, 6, 8]
Returns a boolean value in scalar context. In list context, it returns the element if it was found, otherwise the empty list.
use List::MoreUtils qw/:all/;
It may make more sense though to only import the stuff your program actually needs:
use List::MoreUtils qw/any firstidx/;
my @x = apply { s/foo/bar/ } qw/foo bar baz/;
It has to be written as either
my @x = apply { s/foo/bar/ } 'foo', 'bar', 'baz';
or
my @x = apply { s/foo/bar/ } my @dummy = qw/foo bar baz/;
Perl5.5.x and perl5.8.x don't suffer from this limitation.
If you have a functionality that you could imagine being in this module, please drop me a line. This module's policy will be less strict than "List::Util"'s when it comes to additions as it isn't a core module.
When you report bugs, it would be nice if you could additionally give me the output of your program with the environment variable "LIST_MOREUTILS_PP" set to a true value. That way I know where to look for the problem (in XS, pure-Perl or possibly both).
Brian McCauley suggested the inclusion of apply() and provided the pure-Perl implementation for it.
Eric J. Roode asked me to add all functions from his module "List::MoreUtil" into this one. With minor modifications, the pure-Perl implementations of those are by him.
The bunch of people who almost immediately pointed out the many problems with the glitchy 0.07 release (Slaven Rezic, Ron Savage, CPAN testers).
A particularly nasty memory leak was spotted by Thomas A. Lowery.
Lars Thegler made me aware of problems with older Perl versions.
Anno Siegel de-orphaned each_arrayref().
David Filmer made me aware of a problem in each_arrayref that could ultimately lead to a segfault.
Ricardo Signes suggested the inclusion of part() and provided the Perl-implementation.
Robin Huston kindly fixed a bug in perl's MULTICALL API to make the XS-implementation of part() work.
Use code-reference to extract a key based on which the uniqueness is determined. Suggested by Aaron Crane.
These were all suggested by Dan Muey.
Always return a flat list when either a simple scalar value was passed or an array-reference. Suggested by Mark Summersault.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.4 or, at your option, any later version of Perl 5 you may have available.