3 # Copyright (c) 1997-2005 Graham Barr <gbarr@pobox.com>. All rights reserved.
4 # This program is free software; you can redistribute it and/or
5 # modify it under the same terms as Perl itself.
12 @EXPORT_OK = qw(first min max minstr maxstr reduce sum shuffle);
14 $XS_VERSION = $VERSION;
15 $VERSION = eval $VERSION;
18 # PERL_DL_NONLAZY must be false, or any errors in loading will just
19 # cause the perl code to be tested
20 local $ENV{PERL_DL_NONLAZY} = 0 if $ENV{PERL_DL_NONLAZY};
22 local @ISA = qw(DynaLoader);
23 bootstrap List::Util $XS_VERSION;
27 eval <<'ESQ' unless defined &reduce;
29 # This code is only compiled if the XS did not load
36 return shift unless @_ > 1;
39 local(*{$caller."::a"}) = \my $a;
40 local(*{$caller."::b"}) = \my $b;
51 sub sum (@) { reduce { $a + $b } @_ }
53 sub min (@) { reduce { $a < $b ? $a : $b } @_ }
55 sub max (@) { reduce { $a > $b ? $a : $b } @_ }
57 sub minstr (@) { reduce { $a lt $b ? $a : $b } @_ }
59 sub maxstr (@) { reduce { $a gt $b ? $a : $b } @_ }
65 return $_ if &{$code}();
77 (${$a[$n]}, $a[$n] = $a[$i])[0];
89 List::Util - A selection of general-utility list subroutines
93 use List::Util qw(first max maxstr min minstr reduce shuffle sum);
97 C<List::Util> contains a selection of subroutines that people have
98 expressed would be nice to have in the perl core, but the usage would
99 not really be high enough to warrant the use of a keyword, and the size
100 so small such that being individual extensions would be wasteful.
102 By default C<List::Util> does not export any subroutines. The
103 subroutines defined are
107 =item first BLOCK LIST
109 Similar to C<grep> in that it evaluates BLOCK setting C<$_> to each element
110 of LIST in turn. C<first> returns the first element where the result from
111 BLOCK is a true value. If BLOCK never returns true or LIST was empty then
112 C<undef> is returned.
114 $foo = first { defined($_) } @list # first defined value in @list
115 $foo = first { $_ > $value } @list # first value in @list which
116 # is greater than $value
118 This function could be implemented using C<reduce> like this
120 $foo = reduce { defined($a) ? $a : wanted($b) ? $b : undef } undef, @list
122 for example wanted() could be defined() which would return the first
123 defined value in @list
127 Returns the entry in the list with the highest numerical value. If the
128 list is empty then C<undef> is returned.
130 $foo = max 1..10 # 10
131 $foo = max 3,9,12 # 12
132 $foo = max @bar, @baz # whatever
134 This function could be implemented using C<reduce> like this
136 $foo = reduce { $a > $b ? $a : $b } 1..10
140 Similar to C<max>, but treats all the entries in the list as strings
141 and returns the highest string as defined by the C<gt> operator.
142 If the list is empty then C<undef> is returned.
144 $foo = maxstr 'A'..'Z' # 'Z'
145 $foo = maxstr "hello","world" # "world"
146 $foo = maxstr @bar, @baz # whatever
148 This function could be implemented using C<reduce> like this
150 $foo = reduce { $a gt $b ? $a : $b } 'A'..'Z'
154 Similar to C<max> but returns the entry in the list with the lowest
155 numerical value. If the list is empty then C<undef> is returned.
158 $foo = min 3,9,12 # 3
159 $foo = min @bar, @baz # whatever
161 This function could be implemented using C<reduce> like this
163 $foo = reduce { $a < $b ? $a : $b } 1..10
167 Similar to C<min>, but treats all the entries in the list as strings
168 and returns the lowest string as defined by the C<lt> operator.
169 If the list is empty then C<undef> is returned.
171 $foo = minstr 'A'..'Z' # 'A'
172 $foo = minstr "hello","world" # "hello"
173 $foo = minstr @bar, @baz # whatever
175 This function could be implemented using C<reduce> like this
177 $foo = reduce { $a lt $b ? $a : $b } 'A'..'Z'
179 =item reduce BLOCK LIST
181 Reduces LIST by calling BLOCK multiple times, setting C<$a> and C<$b>
182 each time. The first call will be with C<$a> and C<$b> set to the first
183 two elements of the list, subsequent calls will be done by
184 setting C<$a> to the result of the previous call and C<$b> to the next
187 Returns the result of the last call to BLOCK. If LIST is empty then
188 C<undef> is returned. If LIST only contains one element then that
189 element is returned and BLOCK is not executed.
191 $foo = reduce { $a < $b ? $a : $b } 1..10 # min
192 $foo = reduce { $a lt $b ? $a : $b } 'aa'..'zz' # minstr
193 $foo = reduce { $a + $b } 1 .. 10 # sum
194 $foo = reduce { $a . $b } @bar # concat
198 Returns the elements of LIST in a random order
200 @cards = shuffle 0..51 # 0..51 in a random order
204 Returns the sum of all the elements in LIST.
206 $foo = sum 1..10 # 55
207 $foo = sum 3,9,12 # 24
208 $foo = sum @bar, @baz # whatever
210 This function could be implemented using C<reduce> like this
212 $foo = reduce { $a + $b } 1..10
218 With perl versions prior to 5.005 there are some cases where reduce
219 will return an incorrect result. This will show up as test 7 of
222 =head1 SUGGESTED ADDITIONS
224 The following are additions that have been requested, but I have been reluctant
225 to add due to them being very simple to implement in perl
227 # One argument is true
229 sub any { $_ && return 1 for @_; 0 }
231 # All arguments are true
233 sub all { $_ || return 0 for @_; 1 }
235 # All arguments are false
237 sub none { $_ && return 0 for @_; 1 }
239 # One argument is false
241 sub notall { $_ || return 1 for @_; 0 }
243 # How many elements are true
245 sub true { scalar grep { $_ } @_ }
247 # How many elements are false
249 sub false { scalar grep { !$_ } @_ }
253 Copyright (c) 1997-2005 Graham Barr <gbarr@pobox.com>. All rights reserved.
254 This program is free software; you can redistribute it and/or
255 modify it under the same terms as Perl itself.