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