3 # Copyright (c) 1997-2009 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.
7 # This module is normally only loaded if the XS module is not available
12 use vars qw(@ISA @EXPORT_OK $VERSION $XS_VERSION $TESTING_PERL_ONLY);
16 @EXPORT_OK = qw(first min max minstr maxstr reduce sum shuffle);
18 $XS_VERSION = $VERSION;
19 $VERSION = eval $VERSION;
22 # PERL_DL_NONLAZY must be false, or any errors in loading will just
23 # cause the perl code to be tested
24 local $ENV{PERL_DL_NONLAZY} = 0 if $ENV{PERL_DL_NONLAZY};
27 XSLoader::load('List::Util', $XS_VERSION);
31 local @ISA = qw(DynaLoader);
32 bootstrap List::Util $XS_VERSION;
34 } unless $TESTING_PERL_ONLY;
38 require List::Util::PP;
39 List::Util::PP->import;
48 List::Util - A selection of general-utility list subroutines
52 use List::Util qw(first max maxstr min minstr reduce shuffle sum);
56 C<List::Util> contains a selection of subroutines that people have
57 expressed would be nice to have in the perl core, but the usage would
58 not really be high enough to warrant the use of a keyword, and the size
59 so small such that being individual extensions would be wasteful.
61 By default C<List::Util> does not export any subroutines. The
62 subroutines defined are
66 =item first BLOCK LIST
68 Similar to C<grep> in that it evaluates BLOCK setting C<$_> to each element
69 of LIST in turn. C<first> returns the first element where the result from
70 BLOCK is a true value. If BLOCK never returns true or LIST was empty then
73 $foo = first { defined($_) } @list # first defined value in @list
74 $foo = first { $_ > $value } @list # first value in @list which
75 # is greater than $value
77 This function could be implemented using C<reduce> like this
79 $foo = reduce { defined($a) ? $a : wanted($b) ? $b : undef } undef, @list
81 for example wanted() could be defined() which would return the first
82 defined value in @list
86 Returns the entry in the list with the highest numerical value. If the
87 list is empty then C<undef> is returned.
90 $foo = max 3,9,12 # 12
91 $foo = max @bar, @baz # whatever
93 This function could be implemented using C<reduce> like this
95 $foo = reduce { $a > $b ? $a : $b } 1..10
99 Similar to C<max>, but treats all the entries in the list as strings
100 and returns the highest string as defined by the C<gt> operator.
101 If the list is empty then C<undef> is returned.
103 $foo = maxstr 'A'..'Z' # 'Z'
104 $foo = maxstr "hello","world" # "world"
105 $foo = maxstr @bar, @baz # whatever
107 This function could be implemented using C<reduce> like this
109 $foo = reduce { $a gt $b ? $a : $b } 'A'..'Z'
113 Similar to C<max> but returns the entry in the list with the lowest
114 numerical value. If the list is empty then C<undef> is returned.
117 $foo = min 3,9,12 # 3
118 $foo = min @bar, @baz # whatever
120 This function could be implemented using C<reduce> like this
122 $foo = reduce { $a < $b ? $a : $b } 1..10
126 Similar to C<min>, but treats all the entries in the list as strings
127 and returns the lowest string as defined by the C<lt> operator.
128 If the list is empty then C<undef> is returned.
130 $foo = minstr 'A'..'Z' # 'A'
131 $foo = minstr "hello","world" # "hello"
132 $foo = minstr @bar, @baz # whatever
134 This function could be implemented using C<reduce> like this
136 $foo = reduce { $a lt $b ? $a : $b } 'A'..'Z'
138 =item reduce BLOCK LIST
140 Reduces LIST by calling BLOCK, in a scalar context, multiple times,
141 setting C<$a> and C<$b> each time. The first call will be with C<$a>
142 and C<$b> set to the first two elements of the list, subsequent
143 calls will be done by setting C<$a> to the result of the previous
144 call and C<$b> to the next element in the list.
146 Returns the result of the last call to BLOCK. If LIST is empty then
147 C<undef> is returned. If LIST only contains one element then that
148 element is returned and BLOCK is not executed.
150 $foo = reduce { $a < $b ? $a : $b } 1..10 # min
151 $foo = reduce { $a lt $b ? $a : $b } 'aa'..'zz' # minstr
152 $foo = reduce { $a + $b } 1 .. 10 # sum
153 $foo = reduce { $a . $b } @bar # concat
155 If your algorithm requires that C<reduce> produce an identity value, then
156 make sure that you always pass that identity value as the first argument to prevent
157 C<undef> being returned
159 $foo = reduce { $a + $b } 0, @values; # sum with 0 identity value
163 Returns the elements of LIST in a random order
165 @cards = shuffle 0..51 # 0..51 in a random order
169 Returns the sum of all the elements in LIST. If LIST is empty then
170 C<undef> is returned.
172 $foo = sum 1..10 # 55
173 $foo = sum 3,9,12 # 24
174 $foo = sum @bar, @baz # whatever
176 This function could be implemented using C<reduce> like this
178 $foo = reduce { $a + $b } 1..10
180 If your algorithm requires that C<sum> produce an identity of 0, then
181 make sure that you always pass C<0> as the first argument to prevent
182 C<undef> being returned
184 $foo = sum 0, @values;
190 With perl versions prior to 5.005 there are some cases where reduce
191 will return an incorrect result. This will show up as test 7 of
194 =head1 SUGGESTED ADDITIONS
196 The following are additions that have been requested, but I have been reluctant
197 to add due to them being very simple to implement in perl
199 # One argument is true
201 sub any { $_ && return 1 for @_; 0 }
203 # All arguments are true
205 sub all { $_ || return 0 for @_; 1 }
207 # All arguments are false
209 sub none { $_ && return 0 for @_; 1 }
211 # One argument is false
213 sub notall { $_ || return 1 for @_; 0 }
215 # How many elements are true
217 sub true { scalar grep { $_ } @_ }
219 # How many elements are false
221 sub false { scalar grep { !$_ } @_ }
225 L<Scalar::Util>, L<List::MoreUtils>
229 Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights reserved.
230 This program is free software; you can redistribute it and/or
231 modify it under the same terms as Perl itself.