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