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