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