This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update to Scalar-List-Utils-1.14
[perl5.git] / ext / List / Util / lib / List / Util.pm
CommitLineData
f4a2945e
JH
1# List::Util.pm
2#
42975ef9 3# Copyright (c) 1997-2004 Graham Barr <gbarr@pobox.com>. All rights reserved.
f4a2945e
JH
4# This program is free software; you can redistribute it and/or
5# modify it under the same terms as Perl itself.
6
7package List::Util;
8
9require Exporter;
10
09c2a9b8
GB
11@ISA = qw(Exporter);
12@EXPORT_OK = qw(first min max minstr maxstr reduce sum shuffle);
42975ef9 13$VERSION = "1.14";
09c2a9b8 14$XS_VERSION = $VERSION;
60f3865b 15$VERSION = eval $VERSION;
f4a2945e 16
09c2a9b8
GB
17eval {
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};
21 require DynaLoader;
22 local @ISA = qw(DynaLoader);
23 bootstrap List::Util $XS_VERSION;
24 1
25};
26
27eval <<'ESQ' unless defined &reduce;
28
29# This code is only compiled if the XS did not load
30
31use vars qw($a $b);
32
33sub reduce (&@) {
34 my $code = shift;
35
36 return shift unless @_ > 1;
37
38 my $caller = caller;
39 local(*{$caller."::a"}) = \my $a;
40 local(*{$caller."::b"}) = \my $b;
41
42 $a = shift;
43 foreach (@_) {
44 $b = $_;
45 $a = &{$code}();
46 }
47
48 $a;
49}
50
51sub sum (@) { reduce { $a + $b } @_ }
52
53sub min (@) { reduce { $a < $b ? $a : $b } @_ }
54
55sub max (@) { reduce { $a > $b ? $a : $b } @_ }
56
57sub minstr (@) { reduce { $a lt $b ? $a : $b } @_ }
58
59sub maxstr (@) { reduce { $a gt $b ? $a : $b } @_ }
60
61sub first (&@) {
62 my $code = shift;
63
64 foreach (@_) {
65 return $_ if &{$code}();
66 }
67
68 undef;
69}
70
71sub shuffle (@) {
72 my @a=\(@_);
73 my $n;
74 my $i=@_;
75 map {
76 $n = rand($i--);
77 (${$a[$n]}, $a[$n] = $a[$i])[0];
78 } @_;
79}
80
81ESQ
f4a2945e 82
f4a2945e
JH
831;
84
85__END__
86
87=head1 NAME
88
89List::Util - A selection of general-utility list subroutines
90
91=head1 SYNOPSIS
92
c29e891d 93 use List::Util qw(first max maxstr min minstr reduce shuffle sum);
f4a2945e
JH
94
95=head1 DESCRIPTION
96
97C<List::Util> contains a selection of subroutines that people have
98expressed would be nice to have in the perl core, but the usage would
99not really be high enough to warrant the use of a keyword, and the size
100so small such that being individual extensions would be wasteful.
101
102By default C<List::Util> does not export any subroutines. The
103subroutines defined are
104
105=over 4
106
107=item first BLOCK LIST
108
109Similar to C<grep> in that it evaluates BLOCK setting C<$_> to each element
110of LIST in turn. C<first> returns the first element where the result from
111BLOCK is a true value. If BLOCK never returns true or LIST was empty then
112C<undef> is returned.
113
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
c29e891d 117
f4a2945e
JH
118This function could be implemented using C<reduce> like this
119
120 $foo = reduce { defined($a) ? $a : wanted($b) ? $b : undef } undef, @list
121
122for example wanted() could be defined() which would return the first
123defined value in @list
124
125=item max LIST
126
127Returns the entry in the list with the highest numerical value. If the
128list is empty then C<undef> is returned.
129
130 $foo = max 1..10 # 10
131 $foo = max 3,9,12 # 12
132 $foo = max @bar, @baz # whatever
133
134This function could be implemented using C<reduce> like this
135
136 $foo = reduce { $a > $b ? $a : $b } 1..10
137
138=item maxstr LIST
139
140Similar to C<max>, but treats all the entries in the list as strings
141and returns the highest string as defined by the C<gt> operator.
142If the list is empty then C<undef> is returned.
c29e891d
GB
143
144 $foo = maxstr 'A'..'Z' # 'Z'
f4a2945e
JH
145 $foo = maxstr "hello","world" # "world"
146 $foo = maxstr @bar, @baz # whatever
147
148This function could be implemented using C<reduce> like this
149
150 $foo = reduce { $a gt $b ? $a : $b } 'A'..'Z'
151
152=item min LIST
153
154Similar to C<max> but returns the entry in the list with the lowest
155numerical value. If the list is empty then C<undef> is returned.
156
157 $foo = min 1..10 # 1
158 $foo = min 3,9,12 # 3
159 $foo = min @bar, @baz # whatever
160
161This function could be implemented using C<reduce> like this
162
163 $foo = reduce { $a < $b ? $a : $b } 1..10
164
165=item minstr LIST
166
167Similar to C<min>, but treats all the entries in the list as strings
168and returns the lowest string as defined by the C<lt> operator.
169If the list is empty then C<undef> is returned.
170
c29e891d
GB
171 $foo = minstr 'A'..'Z' # 'A'
172 $foo = minstr "hello","world" # "hello"
173 $foo = minstr @bar, @baz # whatever
f4a2945e
JH
174
175This function could be implemented using C<reduce> like this
176
177 $foo = reduce { $a lt $b ? $a : $b } 'A'..'Z'
178
179=item reduce BLOCK LIST
180
181Reduces LIST by calling BLOCK multiple times, setting C<$a> and C<$b>
182each time. The first call will be with C<$a> and C<$b> set to the first
183two elements of the list, subsequent calls will be done by
184setting C<$a> to the result of the previous call and C<$b> to the next
c29e891d 185element in the list.
f4a2945e
JH
186
187Returns the result of the last call to BLOCK. If LIST is empty then
188C<undef> is returned. If LIST only contains one element then that
189element is returned and BLOCK is not executed.
190
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
195
1bfb5477
GB
196=item shuffle LIST
197
198Returns the elements of LIST in a random order
199
c29e891d
GB
200 @cards = shuffle 0..51 # 0..51 in a random order
201
f4a2945e
JH
202=item sum LIST
203
204Returns the sum of all the elements in LIST.
205
206 $foo = sum 1..10 # 55
207 $foo = sum 3,9,12 # 24
208 $foo = sum @bar, @baz # whatever
209
210This function could be implemented using C<reduce> like this
211
212 $foo = reduce { $a + $b } 1..10
213
214=back
215
9c3c560b
JH
216=head1 KNOWN BUGS
217
218With perl versions prior to 5.005 there are some cases where reduce
219will return an incorrect result. This will show up as test 7 of
220reduce.t failing.
221
f4a2945e
JH
222=head1 SUGGESTED ADDITIONS
223
224The following are additions that have been requested, but I have been reluctant
225to add due to them being very simple to implement in perl
226
227 # One argument is true
228
229 sub any { $_ && return 1 for @_; 0 }
230
231 # All arguments are true
232
233 sub all { $_ || return 0 for @_; 1 }
234
235 # All arguments are false
236
237 sub none { $_ && return 0 for @_; 1 }
238
239 # One argument is false
240
241 sub notall { $_ || return 1 for @_; 0 }
242
243 # How many elements are true
244
245 sub true { scalar grep { $_ } @_ }
246
247 # How many elements are false
248
249 sub false { scalar grep { !$_ } @_ }
250
251=head1 COPYRIGHT
252
42975ef9 253Copyright (c) 1997-2004 Graham Barr <gbarr@pobox.com>. All rights reserved.
f4a2945e
JH
254This program is free software; you can redistribute it and/or
255modify it under the same terms as Perl itself.
256
257=cut