This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
podcheck.t: Make blead pass again
[perl5.git] / cpan / List-Util / lib / List / Util.pm
CommitLineData
f4a2945e
JH
1# List::Util.pm
2#
2ff28616 3# Copyright (c) 1997-2009 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.
2ff28616
GB
6#
7# This module is normally only loaded if the XS module is not available
f4a2945e
JH
8
9package List::Util;
10
82f35e8b 11use strict;
f4a2945e
JH
12require Exporter;
13
3630f57e 14our @ISA = qw(Exporter);
6a9ebaf3 15our @EXPORT_OK = qw(first min max minstr maxstr reduce sum sum0 shuffle pairmap pairgrep pairfirst pairs pairkeys pairvalues);
ad434879 16our $VERSION = "1.32";
3630f57e 17our $XS_VERSION = $VERSION;
60f3865b 18$VERSION = eval $VERSION;
f4a2945e 19
3630f57e
CBW
20require XSLoader;
21XSLoader::load('List::Util', $XS_VERSION);
09c2a9b8 22
8b198969
CBW
23sub sum0
24{
25 return 0 unless @_;
26 goto &sum;
27}
28
f4a2945e
JH
291;
30
31__END__
32
33=head1 NAME
34
35List::Util - A selection of general-utility list subroutines
36
37=head1 SYNOPSIS
38
c29e891d 39 use List::Util qw(first max maxstr min minstr reduce shuffle sum);
f4a2945e
JH
40
41=head1 DESCRIPTION
42
43C<List::Util> contains a selection of subroutines that people have
44expressed would be nice to have in the perl core, but the usage would
45not really be high enough to warrant the use of a keyword, and the size
46so small such that being individual extensions would be wasteful.
47
6a9ebaf3 48By default C<List::Util> does not export any subroutines.
f4a2945e 49
6a9ebaf3
SH
50=cut
51
52=head1 LIST-REDUCTION FUNCTIONS
53
54The following set of functions all reduce a list down to a single value.
55
56=cut
57
58=head2 reduce BLOCK LIST
59
60Reduces LIST by calling BLOCK, in a scalar context, multiple times,
61setting C<$a> and C<$b> each time. The first call will be with C<$a>
62and C<$b> set to the first two elements of the list, subsequent
63calls will be done by setting C<$a> to the result of the previous
64call and C<$b> to the next element in the list.
65
66Returns the result of the last call to BLOCK. If LIST is empty then
67C<undef> is returned. If LIST only contains one element then that
68element is returned and BLOCK is not executed.
f4a2945e 69
6a9ebaf3
SH
70 $foo = reduce { $a < $b ? $a : $b } 1..10 # min
71 $foo = reduce { $a lt $b ? $a : $b } 'aa'..'zz' # minstr
72 $foo = reduce { $a + $b } 1 .. 10 # sum
73 $foo = reduce { $a . $b } @bar # concat
74
75If your algorithm requires that C<reduce> produce an identity value, then
76make sure that you always pass that identity value as the first argument to prevent
77C<undef> being returned
78
79 $foo = reduce { $a + $b } 0, @values; # sum with 0 identity value
80
81The remaining list-reduction functions are all specialisations of this
82generic idea.
83
84=head2 first BLOCK LIST
f4a2945e
JH
85
86Similar to C<grep> in that it evaluates BLOCK setting C<$_> to each element
87of LIST in turn. C<first> returns the first element where the result from
88BLOCK is a true value. If BLOCK never returns true or LIST was empty then
89C<undef> is returned.
90
91 $foo = first { defined($_) } @list # first defined value in @list
92 $foo = first { $_ > $value } @list # first value in @list which
93 # is greater than $value
c29e891d 94
f4a2945e
JH
95This function could be implemented using C<reduce> like this
96
97 $foo = reduce { defined($a) ? $a : wanted($b) ? $b : undef } undef, @list
98
99for example wanted() could be defined() which would return the first
100defined value in @list
101
6a9ebaf3 102=head2 max LIST
f4a2945e
JH
103
104Returns the entry in the list with the highest numerical value. If the
105list is empty then C<undef> is returned.
106
107 $foo = max 1..10 # 10
108 $foo = max 3,9,12 # 12
109 $foo = max @bar, @baz # whatever
110
111This function could be implemented using C<reduce> like this
112
113 $foo = reduce { $a > $b ? $a : $b } 1..10
114
6a9ebaf3 115=head2 maxstr LIST
f4a2945e
JH
116
117Similar to C<max>, but treats all the entries in the list as strings
118and returns the highest string as defined by the C<gt> operator.
119If the list is empty then C<undef> is returned.
c29e891d
GB
120
121 $foo = maxstr 'A'..'Z' # 'Z'
f4a2945e
JH
122 $foo = maxstr "hello","world" # "world"
123 $foo = maxstr @bar, @baz # whatever
124
125This function could be implemented using C<reduce> like this
126
127 $foo = reduce { $a gt $b ? $a : $b } 'A'..'Z'
128
6a9ebaf3 129=head2 min LIST
f4a2945e
JH
130
131Similar to C<max> but returns the entry in the list with the lowest
132numerical value. If the list is empty then C<undef> is returned.
133
134 $foo = min 1..10 # 1
135 $foo = min 3,9,12 # 3
136 $foo = min @bar, @baz # whatever
137
138This function could be implemented using C<reduce> like this
139
140 $foo = reduce { $a < $b ? $a : $b } 1..10
141
6a9ebaf3 142=head2 minstr LIST
f4a2945e
JH
143
144Similar to C<min>, but treats all the entries in the list as strings
145and returns the lowest string as defined by the C<lt> operator.
146If the list is empty then C<undef> is returned.
147
c29e891d
GB
148 $foo = minstr 'A'..'Z' # 'A'
149 $foo = minstr "hello","world" # "hello"
150 $foo = minstr @bar, @baz # whatever
f4a2945e
JH
151
152This function could be implemented using C<reduce> like this
153
154 $foo = reduce { $a lt $b ? $a : $b } 'A'..'Z'
155
6a9ebaf3
SH
156=head2 sum LIST
157
158Returns the sum of all the elements in LIST. If LIST is empty then
159C<undef> is returned.
160
161 $foo = sum 1..10 # 55
162 $foo = sum 3,9,12 # 24
163 $foo = sum @bar, @baz # whatever
164
165This function could be implemented using C<reduce> like this
166
167 $foo = reduce { $a + $b } 1..10
168
169=head2 sum0 LIST
170
171Similar to C<sum>, except this returns 0 when given an empty list, rather
172than C<undef>.
173
174=cut
175
176=head1 KEY/VALUE PAIR LIST FUNCTIONS
177
178The following set of functions, all inspired by L<List::Pairwise>, consume
179an even-sized list of pairs. The pairs may be key/value associations from a
180hash, or just a list of values. The functions will all preserve the original
181ordering of the pairs, and will not be confused by multiple pairs having the
182same "key" value - nor even do they require that the first of each pair be a
183plain string.
184
185=cut
186
187=head2 pairgrep BLOCK KVLIST
2dc8d725
CBW
188
189Similar to perl's C<grep> keyword, but interprets the given list as an
190even-sized list of pairs. It invokes the BLOCK multiple times, in scalar
191context, with C<$a> and C<$b> set to successive pairs of values from the
192KVLIST.
193
194Returns an even-sized list of those pairs for which the BLOCK returned true
195in list context, or the count of the B<number of pairs> in scalar context.
196(Note, therefore, in scalar context that it returns a number half the size
197of the count of items it would have returned in list context).
198
199 @subset = pairgrep { $a =~ m/^[[:upper:]]+$/ } @kvlist
200
201Similar to C<grep>, C<pairgrep> aliases C<$a> and C<$b> to elements of the
202given list. Any modifications of it by the code block will be visible to
203the caller.
204
6a9ebaf3
SH
205=head2 pairfirst BLOCK KVLIST
206
207Similar to the C<first> function, but interprets the given list as an
208even-sized list of pairs. It invokes the BLOCK multiple times, in scalar
209context, with C<$a> and C<$b> set to successive pairs of values from the
210KVLIST.
211
212Returns the first pair of values from the list for which the BLOCK returned
213true in list context, or an empty list of no such pair was found. In scalar
214context it returns a simple boolean value, rather than either the key or the
215value found.
216
217 ( $key, $value ) = pairfirst { $a =~ m/^[[:upper:]]+$/ } @kvlist
218
219Similar to C<grep>, C<pairfirst> aliases C<$a> and C<$b> to elements of the
220given list. Any modifications of it by the code block will be visible to
221the caller.
222
223=head2 pairmap BLOCK KVLIST
2dc8d725
CBW
224
225Similar to perl's C<map> keyword, but interprets the given list as an
226even-sized list of pairs. It invokes the BLOCK multiple times, in list
227context, with C<$a> and C<$b> set to successive pairs of values from the
228KVLIST.
229
230Returns the concatenation of all the values returned by the BLOCK in list
231context, or the count of the number of items that would have been returned
232in scalar context.
233
234 @result = pairmap { "The key $a has value $b" } @kvlist
235
236Similar to C<map>, C<pairmap> aliases C<$a> and C<$b> to elements of the
237given list. Any modifications of it by the code block will be visible to
238the caller.
239
6a9ebaf3 240=head2 pairs KVLIST
2dc8d725
CBW
241
242A convenient shortcut to operating on even-sized lists of pairs, this
243function returns a list of ARRAY references, each containing two items from
244the given list. It is a more efficient version of
245
246 pairmap { [ $a, $b ] } KVLIST
247
248It is most convenient to use in a C<foreach> loop, for example:
249
250 foreach ( pairs @KVLIST ) {
251 my ( $key, $value ) = @$_;
252 ...
253 }
254
6a9ebaf3 255=head2 pairkeys KVLIST
2dc8d725
CBW
256
257A convenient shortcut to operating on even-sized lists of pairs, this
258function returns a list of the the first values of each of the pairs in
259the given list. It is a more efficient version of
260
261 pairmap { $a } KVLIST
262
6a9ebaf3 263=head2 pairvalues KVLIST
2dc8d725
CBW
264
265A convenient shortcut to operating on even-sized lists of pairs, this
266function returns a list of the the second values of each of the pairs in
267the given list. It is a more efficient version of
268
269 pairmap { $b } KVLIST
270
6a9ebaf3 271=cut
f4a2945e 272
6a9ebaf3 273=head1 OTHER FUNCTIONS
f4a2945e 274
6a9ebaf3 275=cut
2ff28616 276
6a9ebaf3 277=head2 shuffle LIST
1bfb5477
GB
278
279Returns the elements of LIST in a random order
280
c29e891d
GB
281 @cards = shuffle 0..51 # 0..51 in a random order
282
6a9ebaf3 283=cut
f4a2945e 284
9c3c560b
JH
285=head1 KNOWN BUGS
286
287With perl versions prior to 5.005 there are some cases where reduce
288will return an incorrect result. This will show up as test 7 of
289reduce.t failing.
290
f4a2945e
JH
291=head1 SUGGESTED ADDITIONS
292
293The following are additions that have been requested, but I have been reluctant
294to add due to them being very simple to implement in perl
295
296 # One argument is true
297
298 sub any { $_ && return 1 for @_; 0 }
299
300 # All arguments are true
301
302 sub all { $_ || return 0 for @_; 1 }
303
304 # All arguments are false
305
306 sub none { $_ && return 0 for @_; 1 }
307
308 # One argument is false
309
310 sub notall { $_ || return 1 for @_; 0 }
311
312 # How many elements are true
313
314 sub true { scalar grep { $_ } @_ }
315
316 # How many elements are false
317
318 sub false { scalar grep { !$_ } @_ }
319
ddf53ba4
GB
320=head1 SEE ALSO
321
322L<Scalar::Util>, L<List::MoreUtils>
323
f4a2945e
JH
324=head1 COPYRIGHT
325
2ff28616 326Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights reserved.
f4a2945e
JH
327This program is free software; you can redistribute it and/or
328modify it under the same terms as Perl itself.
329
6a9ebaf3
SH
330Recent additions and current maintenance by
331Paul Evans, <leonerd@leonerd.org.uk>.
332
f4a2945e 333=cut