1N/A# List::Util.pm
1N/A#
1N/A# Copyright (c) 1997-2003 Graham Barr <gbarr@pobox.com>. All rights reserved.
1N/A# This program is free software; you can redistribute it and/or
1N/A# modify it under the same terms as Perl itself.
1N/A
1N/Apackage List::Util;
1N/A
1N/Arequire Exporter;
1N/A
1N/A@ISA = qw(Exporter);
1N/A@EXPORT_OK = qw(first min max minstr maxstr reduce sum shuffle);
1N/A$VERSION = "1.13";
1N/A$XS_VERSION = $VERSION;
1N/A$VERSION = eval $VERSION;
1N/A
1N/Aeval {
1N/A # PERL_DL_NONLAZY must be false, or any errors in loading will just
1N/A # cause the perl code to be tested
1N/A local $ENV{PERL_DL_NONLAZY} = 0 if $ENV{PERL_DL_NONLAZY};
1N/A require DynaLoader;
1N/A local @ISA = qw(DynaLoader);
1N/A bootstrap List::Util $XS_VERSION;
1N/A 1
1N/A};
1N/A
1N/Aeval <<'ESQ' unless defined &reduce;
1N/A
1N/A# This code is only compiled if the XS did not load
1N/A
1N/Ause vars qw($a $b);
1N/A
1N/Asub reduce (&@) {
1N/A my $code = shift;
1N/A
1N/A return shift unless @_ > 1;
1N/A
1N/A my $caller = caller;
1N/A local(*{$caller."::a"}) = \my $a;
1N/A local(*{$caller."::b"}) = \my $b;
1N/A
1N/A $a = shift;
1N/A foreach (@_) {
1N/A $b = $_;
1N/A $a = &{$code}();
1N/A }
1N/A
1N/A $a;
1N/A}
1N/A
1N/Asub sum (@) { reduce { $a + $b } @_ }
1N/A
1N/Asub min (@) { reduce { $a < $b ? $a : $b } @_ }
1N/A
1N/Asub max (@) { reduce { $a > $b ? $a : $b } @_ }
1N/A
1N/Asub minstr (@) { reduce { $a lt $b ? $a : $b } @_ }
1N/A
1N/Asub maxstr (@) { reduce { $a gt $b ? $a : $b } @_ }
1N/A
1N/Asub first (&@) {
1N/A my $code = shift;
1N/A
1N/A foreach (@_) {
1N/A return $_ if &{$code}();
1N/A }
1N/A
1N/A undef;
1N/A}
1N/A
1N/Asub shuffle (@) {
1N/A my @a=\(@_);
1N/A my $n;
1N/A my $i=@_;
1N/A map {
1N/A $n = rand($i--);
1N/A (${$a[$n]}, $a[$n] = $a[$i])[0];
1N/A } @_;
1N/A}
1N/A
1N/AESQ
1N/A
1N/A1;
1N/A
1N/A__END__
1N/A
1N/A=head1 NAME
1N/A
1N/AList::Util - A selection of general-utility list subroutines
1N/A
1N/A=head1 SYNOPSIS
1N/A
1N/A use List::Util qw(first max maxstr min minstr reduce shuffle sum);
1N/A
1N/A=head1 DESCRIPTION
1N/A
1N/AC<List::Util> contains a selection of subroutines that people have
1N/Aexpressed would be nice to have in the perl core, but the usage would
1N/Anot really be high enough to warrant the use of a keyword, and the size
1N/Aso small such that being individual extensions would be wasteful.
1N/A
1N/ABy default C<List::Util> does not export any subroutines. The
1N/Asubroutines defined are
1N/A
1N/A=over 4
1N/A
1N/A=item first BLOCK LIST
1N/A
1N/ASimilar to C<grep> in that it evaluates BLOCK setting C<$_> to each element
1N/Aof LIST in turn. C<first> returns the first element where the result from
1N/ABLOCK is a true value. If BLOCK never returns true or LIST was empty then
1N/AC<undef> is returned.
1N/A
1N/A $foo = first { defined($_) } @list # first defined value in @list
1N/A $foo = first { $_ > $value } @list # first value in @list which
1N/A # is greater than $value
1N/A
1N/AThis function could be implemented using C<reduce> like this
1N/A
1N/A $foo = reduce { defined($a) ? $a : wanted($b) ? $b : undef } undef, @list
1N/A
1N/Afor example wanted() could be defined() which would return the first
1N/Adefined value in @list
1N/A
1N/A=item max LIST
1N/A
1N/AReturns the entry in the list with the highest numerical value. If the
1N/Alist is empty then C<undef> is returned.
1N/A
1N/A $foo = max 1..10 # 10
1N/A $foo = max 3,9,12 # 12
1N/A $foo = max @bar, @baz # whatever
1N/A
1N/AThis function could be implemented using C<reduce> like this
1N/A
1N/A $foo = reduce { $a > $b ? $a : $b } 1..10
1N/A
1N/A=item maxstr LIST
1N/A
1N/ASimilar to C<max>, but treats all the entries in the list as strings
1N/Aand returns the highest string as defined by the C<gt> operator.
1N/AIf the list is empty then C<undef> is returned.
1N/A
1N/A $foo = maxstr 'A'..'Z' # 'Z'
1N/A $foo = maxstr "hello","world" # "world"
1N/A $foo = maxstr @bar, @baz # whatever
1N/A
1N/AThis function could be implemented using C<reduce> like this
1N/A
1N/A $foo = reduce { $a gt $b ? $a : $b } 'A'..'Z'
1N/A
1N/A=item min LIST
1N/A
1N/ASimilar to C<max> but returns the entry in the list with the lowest
1N/Anumerical value. If the list is empty then C<undef> is returned.
1N/A
1N/A $foo = min 1..10 # 1
1N/A $foo = min 3,9,12 # 3
1N/A $foo = min @bar, @baz # whatever
1N/A
1N/AThis function could be implemented using C<reduce> like this
1N/A
1N/A $foo = reduce { $a < $b ? $a : $b } 1..10
1N/A
1N/A=item minstr LIST
1N/A
1N/ASimilar to C<min>, but treats all the entries in the list as strings
1N/Aand returns the lowest string as defined by the C<lt> operator.
1N/AIf the list is empty then C<undef> is returned.
1N/A
1N/A $foo = minstr 'A'..'Z' # 'A'
1N/A $foo = minstr "hello","world" # "hello"
1N/A $foo = minstr @bar, @baz # whatever
1N/A
1N/AThis function could be implemented using C<reduce> like this
1N/A
1N/A $foo = reduce { $a lt $b ? $a : $b } 'A'..'Z'
1N/A
1N/A=item reduce BLOCK LIST
1N/A
1N/AReduces LIST by calling BLOCK multiple times, setting C<$a> and C<$b>
1N/Aeach time. The first call will be with C<$a> and C<$b> set to the first
1N/Atwo elements of the list, subsequent calls will be done by
1N/Asetting C<$a> to the result of the previous call and C<$b> to the next
1N/Aelement in the list.
1N/A
1N/AReturns the result of the last call to BLOCK. If LIST is empty then
1N/AC<undef> is returned. If LIST only contains one element then that
1N/Aelement is returned and BLOCK is not executed.
1N/A
1N/A $foo = reduce { $a < $b ? $a : $b } 1..10 # min
1N/A $foo = reduce { $a lt $b ? $a : $b } 'aa'..'zz' # minstr
1N/A $foo = reduce { $a + $b } 1 .. 10 # sum
1N/A $foo = reduce { $a . $b } @bar # concat
1N/A
1N/A=item shuffle LIST
1N/A
1N/AReturns the elements of LIST in a random order
1N/A
1N/A @cards = shuffle 0..51 # 0..51 in a random order
1N/A
1N/A=item sum LIST
1N/A
1N/AReturns the sum of all the elements in LIST.
1N/A
1N/A $foo = sum 1..10 # 55
1N/A $foo = sum 3,9,12 # 24
1N/A $foo = sum @bar, @baz # whatever
1N/A
1N/AThis function could be implemented using C<reduce> like this
1N/A
1N/A $foo = reduce { $a + $b } 1..10
1N/A
1N/A=back
1N/A
1N/A=head1 KNOWN BUGS
1N/A
1N/AWith perl versions prior to 5.005 there are some cases where reduce
1N/Awill return an incorrect result. This will show up as test 7 of
1N/Areduce.t failing.
1N/A
1N/A=head1 SUGGESTED ADDITIONS
1N/A
1N/AThe following are additions that have been requested, but I have been reluctant
1N/Ato add due to them being very simple to implement in perl
1N/A
1N/A # One argument is true
1N/A
1N/A sub any { $_ && return 1 for @_; 0 }
1N/A
1N/A # All arguments are true
1N/A
1N/A sub all { $_ || return 0 for @_; 1 }
1N/A
1N/A # All arguments are false
1N/A
1N/A sub none { $_ && return 0 for @_; 1 }
1N/A
1N/A # One argument is false
1N/A
1N/A sub notall { $_ || return 1 for @_; 0 }
1N/A
1N/A # How many elements are true
1N/A
1N/A sub true { scalar grep { $_ } @_ }
1N/A
1N/A # How many elements are false
1N/A
1N/A sub false { scalar grep { !$_ } @_ }
1N/A
1N/A=head1 COPYRIGHT
1N/A
1N/ACopyright (c) 1997-2003 Graham Barr <gbarr@pobox.com>. All rights reserved.
1N/AThis program is free software; you can redistribute it and/or
1N/Amodify it under the same terms as Perl itself.
1N/A
1N/A=cut