1List::Util(3) User Contributed Perl Documentation List::Util(3)
2
6 List::Util - A selection of general-utility list subroutines
7
9 use List::Util qw(
10 reduce any all none notall first
11 max maxstr min minstr product sum sum0
13 pairs unpairs pairkeys pairvalues pairfirst pairgrep pairmap
15 shuffle uniq uniqnum uniqstr
17 );
18
20 "List::Util" contains a selection of subroutines that people have
21 expressed would be nice to have in the perl core, but the usage would
22 not really be high enough to warrant the use of a keyword, and the size
23 so small such that being individual extensions would be wasteful.
24 By default "List::Util" does not export any subroutines.
26
28 The following set of functions all reduce a list down to a single
29 value.
30 reduce
32 $result = reduce { BLOCK } @list
33 Reduces @list by calling "BLOCK" in a scalar context multiple times,
35 setting $a and $b each time. The first call will be with $a and $b set
36 to the first two elements of the list, subsequent calls will be done by
37 setting $a to the result of the previous call and $b to the next
38 element in the list.
39 Returns the result of the last call to the "BLOCK". If @list is empty
41 then "undef" is returned. If @list only contains one element then that
42 element is returned and "BLOCK" is not executed.
43 The following examples all demonstrate how "reduce" could be used to
45 implement the other list-reduction functions in this module. (They are
46 not in fact implemented like this, but instead in a more efficient
47 manner in individual C functions).
48 $foo = reduce { defined($a) ? $a :
50 $code->(local $_ = $b) ? $b :
51 undef } undef, @list # first
52 $foo = reduce { $a > $b ? $a : $b } 1..10 # max
54 $foo = reduce { $a gt $b ? $a : $b } 'A'..'Z' # maxstr
55 $foo = reduce { $a < $b ? $a : $b } 1..10 # min
56 $foo = reduce { $a lt $b ? $a : $b } 'aa'..'zz' # minstr
57 $foo = reduce { $a + $b } 1 .. 10 # sum
58 $foo = reduce { $a . $b } @bar # concat
59 $foo = reduce { $a || $code->(local $_ = $b) } 0, @bar # any
61 $foo = reduce { $a && $code->(local $_ = $b) } 1, @bar # all
62 $foo = reduce { $a && !$code->(local $_ = $b) } 1, @bar # none
63 $foo = reduce { $a || !$code->(local $_ = $b) } 0, @bar # notall
64 # Note that these implementations do not fully short-circuit
65 If your algorithm requires that "reduce" produce an identity value,
67 then make sure that you always pass that identity value as the first
68 argument to prevent "undef" being returned
69 $foo = reduce { $a + $b } 0, @values; # sum with 0 identity value
71 The above example code blocks also suggest how to use "reduce" to build
73 a more efficient combined version of one of these basic functions and a
74 "map" block. For example, to find the total length of all the strings
75 in a list, we could use
76 $total = sum map { length } @strings;
78 However, this produces a list of temporary integer values as long as
80 the original list of strings, only to reduce it down to a single value
81 again. We can compute the same result more efficiently by using
82 "reduce" with a code block that accumulates lengths by writing this
83 instead as:
84 $total = reduce { $a + length $b } 0, @strings
86 The remaining list-reduction functions are all specialisations of this
88 generic idea.
89 any
91 my $bool = any { BLOCK } @list;
92 Since version 1.33.
94 Similar to "grep" in that it evaluates "BLOCK" setting $_ to each
96 element of @list in turn. "any" returns true if any element makes the
97 "BLOCK" return a true value. If "BLOCK" never returns true or @list was
98 empty then it returns false.
99 Many cases of using "grep" in a conditional can be written using "any"
101 instead, as it can short-circuit after the first true result.
102 if( any { length > 10 } @strings ) {
104 # at least one string has more than 10 characters
105 }
106 Note: Due to XS issues the block passed may be able to access the outer
108 @_ directly. This is not intentional and will break under debugger.
109 all
111 my $bool = all { BLOCK } @list;
112 Since version 1.33.
114 Similar to "any", except that it requires all elements of the @list to
116 make the "BLOCK" return true. If any element returns false, then it
117 returns false. If the "BLOCK" never returns false or the @list was
118 empty then it returns true.
119 Note: Due to XS issues the block passed may be able to access the outer
121 @_ directly. This is not intentional and will break under debugger.
122 none
124 notall
125 my $bool = none { BLOCK } @list;
126 my $bool = notall { BLOCK } @list;
128 Since version 1.33.
130 Similar to "any" and "all", but with the return sense inverted. "none"
132 returns true only if no value in the @list causes the "BLOCK" to return
133 true, and "notall" returns true only if not all of the values do.
134 Note: Due to XS issues the block passed may be able to access the outer
136 @_ directly. This is not intentional and will break under debugger.
137 first
139 my $val = first { BLOCK } @list;
140 Similar to "grep" in that it evaluates "BLOCK" setting $_ to each
142 element of @list in turn. "first" returns the first element where the
143 result from "BLOCK" is a true value. If "BLOCK" never returns true or
144 @list was empty then "undef" is returned.
145 $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 max
151 my $num = max @list;
152 Returns the entry in the list with the highest numerical value. If the
154 list is empty then "undef" is returned.
155 $foo = max 1..10 # 10
157 $foo = max 3,9,12 # 12
158 $foo = max @bar, @baz # whatever
159 maxstr
161 my $str = maxstr @list;
162 Similar to "max", but treats all the entries in the list as strings and
164 returns the highest string as defined by the "gt" operator. If the list
165 is empty then "undef" is returned.
166 $foo = maxstr 'A'..'Z' # 'Z'
168 $foo = maxstr "hello","world" # "world"
169 $foo = maxstr @bar, @baz # whatever
170 min
172 my $num = min @list;
173 Similar to "max" but returns the entry in the list with the lowest
175 numerical value. If the list is empty then "undef" is returned.
176 $foo = min 1..10 # 1
178 $foo = min 3,9,12 # 3
179 $foo = min @bar, @baz # whatever
180 minstr
182 my $str = minstr @list;
183 Similar to "min", but treats all the entries in the list as strings and
185 returns the lowest string as defined by the "lt" operator. If the list
186 is empty then "undef" is returned.
187 $foo = minstr 'A'..'Z' # 'A'
189 $foo = minstr "hello","world" # "hello"
190 $foo = minstr @bar, @baz # whatever
191 product
193 my $num = product @list;
194 Since version 1.35.
196 Returns the numerical product of all the elements in @list. If @list is
198 empty then 1 is returned.
199 $foo = product 1..10 # 3628800
201 $foo = product 3,9,12 # 324
202 sum
204 my $num_or_undef = sum @list;
205 Returns the numerical sum of all the elements in @list. For backwards
207 compatibility, if @list is empty then "undef" is returned.
208 $foo = sum 1..10 # 55
210 $foo = sum 3,9,12 # 24
211 $foo = sum @bar, @baz # whatever
212 sum0
214 my $num = sum0 @list;
215 Since version 1.26.
217 Similar to "sum", except this returns 0 when given an empty list,
219 rather than "undef".
220
222 The following set of functions, all inspired by List::Pairwise, consume
223 an even-sized list of pairs. The pairs may be key/value associations
224 from a hash, or just a list of values. The functions will all preserve
225 the original ordering of the pairs, and will not be confused by
226 multiple pairs having the same "key" value - nor even do they require
227 that the first of each pair be a plain string.
228 NOTE: At the time of writing, the following "pair*" functions that take
230 a block do not modify the value of $_ within the block, and instead
231 operate using the $a and $b globals instead. This has turned out to be
232 a poor design, as it precludes the ability to provide a "pairsort"
233 function. Better would be to pass pair-like objects as 2-element array
234 references in $_, in a style similar to the return value of the "pairs"
235 function. At some future version this behaviour may be added.
236 Until then, users are alerted NOT to rely on the value of $_ remaining
238 unmodified between the outside and the inside of the control block. In
239 particular, the following example is UNSAFE:
240 my @kvlist = ...
242 foreach (qw( some keys here )) {
244 my @items = pairgrep { $a eq $_ } @kvlist;
245 ...
246 }
247 Instead, write this using a lexical variable:
249 foreach my $key (qw( some keys here )) {
251 my @items = pairgrep { $a eq $key } @kvlist;
252 ...
253 }
254 pairs
256 my @pairs = pairs @kvlist;
257 Since version 1.29.
259 A convenient shortcut to operating on even-sized lists of pairs, this
261 function returns a list of "ARRAY" references, each containing two
262 items from the given list. It is a more efficient version of
263 @pairs = pairmap { [ $a, $b ] } @kvlist
265 It is most convenient to use in a "foreach" loop, for example:
267 foreach my $pair ( pairs @kvlist ) {
269 my ( $key, $value ) = @$pair;
270 ...
271 }
272 Since version 1.39 these "ARRAY" references are blessed objects,
274 recognising the two methods "key" and "value". The following code is
275 equivalent:
276 foreach my $pair ( pairs @kvlist ) {
278 my $key = $pair->key;
279 my $value = $pair->value;
280 ...
281 }
282 unpairs
284 my @kvlist = unpairs @pairs
285 Since version 1.42.
287 The inverse function to "pairs"; this function takes a list of "ARRAY"
289 references containing two elements each, and returns a flattened list
290 of the two values from each of the pairs, in order. This is notionally
291 equivalent to
292 my @kvlist = map { @{$_}[0,1] } @pairs
294 except that it is implemented more efficiently internally.
296 Specifically, for any input item it will extract exactly two values for
297 the output list; using "undef" if the input array references are short.
298 Between "pairs" and "unpairs", a higher-order list function can be used
300 to operate on the pairs as single scalars; such as the following near-
301 equivalents of the other "pair*" higher-order functions:
302 @kvlist = unpairs grep { FUNC } pairs @kvlist
304 # Like pairgrep, but takes $_ instead of $a and $b
305 @kvlist = unpairs map { FUNC } pairs @kvlist
307 # Like pairmap, but takes $_ instead of $a and $b
308 Note however that these versions will not behave as nicely in scalar
310 context.
311 Finally, this technique can be used to implement a sort on a keyvalue
313 pair list; e.g.:
314 @kvlist = unpairs sort { $a->key cmp $b->key } pairs @kvlist
316 pairkeys
318 my @keys = pairkeys @kvlist;
319 Since version 1.29.
321 A convenient shortcut to operating on even-sized lists of pairs, this
323 function returns a list of the the first values of each of the pairs in
324 the given list. It is a more efficient version of
325 @keys = pairmap { $a } @kvlist
327 pairvalues
329 my @values = pairvalues @kvlist;
330 Since version 1.29.
332 A convenient shortcut to operating on even-sized lists of pairs, this
334 function returns a list of the the second values of each of the pairs
335 in the given list. It is a more efficient version of
336 @values = pairmap { $b } @kvlist
338 pairgrep
340 my @kvlist = pairgrep { BLOCK } @kvlist;
341 my $count = pairgrep { BLOCK } @kvlist;
343 Since version 1.29.
345 Similar to perl's "grep" keyword, but interprets the given list as an
347 even-sized list of pairs. It invokes the "BLOCK" multiple times, in
348 scalar context, with $a and $b set to successive pairs of values from
349 the @kvlist.
350 Returns an even-sized list of those pairs for which the "BLOCK"
352 returned true in list context, or the count of the number of pairs in
353 scalar context. (Note, therefore, in scalar context that it returns a
354 number half the size of the count of items it would have returned in
355 list context).
356 @subset = pairgrep { $a =~ m/^[[:upper:]]+$/ } @kvlist
358 As with "grep" aliasing $_ to list elements, "pairgrep" aliases $a and
360 $b to elements of the given list. Any modifications of it by the code
361 block will be visible to the caller.
362 pairfirst
364 my ( $key, $val ) = pairfirst { BLOCK } @kvlist;
365 my $found = pairfirst { BLOCK } @kvlist;
367 Since version 1.30.
369 Similar to the "first" function, but interprets the given list as an
371 even-sized list of pairs. It invokes the "BLOCK" multiple times, in
372 scalar context, with $a and $b set to successive pairs of values from
373 the @kvlist.
374 Returns the first pair of values from the list for which the "BLOCK"
376 returned true in list context, or an empty list of no such pair was
377 found. In scalar context it returns a simple boolean value, rather than
378 either the key or the value found.
379 ( $key, $value ) = pairfirst { $a =~ m/^[[:upper:]]+$/ } @kvlist
381 As with "grep" aliasing $_ to list elements, "pairfirst" aliases $a and
383 $b to elements of the given list. Any modifications of it by the code
384 block will be visible to the caller.
385 pairmap
387 my @list = pairmap { BLOCK } @kvlist;
388 my $count = pairmap { BLOCK } @kvlist;
390 Since version 1.29.
392 Similar to perl's "map" keyword, but interprets the given list as an
394 even-sized list of pairs. It invokes the "BLOCK" multiple times, in
395 list context, with $a and $b set to successive pairs of values from the
396 @kvlist.
397 Returns the concatenation of all the values returned by the "BLOCK" in
399 list context, or the count of the number of items that would have been
400 returned in scalar context.
401 @result = pairmap { "The key $a has value $b" } @kvlist
403 As with "map" aliasing $_ to list elements, "pairmap" aliases $a and $b
405 to elements of the given list. Any modifications of it by the code
406 block will be visible to the caller.
407 See "KNOWN BUGS" for a known-bug with "pairmap", and a workaround.
409
411 shuffle
412 my @values = shuffle @values;
413 Returns the values of the input in a random order
415 @cards = shuffle 0..51 # 0..51 in a random order
417 uniq
419 my @subset = uniq @values
420 Since version 1.45.
422 Filters a list of values to remove subsequent duplicates, as judged by
424 a DWIM-ish string equality or "undef" test. Preserves the order of
425 unique elements, and retains the first value of any duplicate set.
426 my $count = uniq @values
428 In scalar context, returns the number of elements that would have been
430 returned as a list.
431 The "undef" value is treated by this function as distinct from the
433 empty string, and no warning will be produced. It is left as-is in the
434 returned list. Subsequent "undef" values are still considered identical
435 to the first, and will be removed.
436 uniqnum
438 my @subset = uniqnum @values
439 Since version 1.44.
441 Filters a list of values to remove subsequent duplicates, as judged by
443 a numerical equality test. Preserves the order of unique elements, and
444 retains the first value of any duplicate set.
445 my $count = uniqnum @values
447 In scalar context, returns the number of elements that would have been
449 returned as a list.
450 Note that "undef" is treated much as other numerical operations treat
452 it; it compares equal to zero but additionally produces a warning if
453 such warnings are enabled ("use warnings 'uninitialized';"). In
454 addition, an "undef" in the returned list is coerced into a numerical
455 zero, so that the entire list of values returned by "uniqnum" are well-
456 behaved as numbers.
457 Note also that multiple IEEE "NaN" values are treated as duplicates of
459 each other, regardless of any differences in their payloads, and
460 despite the fact that "0+'NaN' == 0+'NaN'" yields false.
461 uniqstr
463 my @subset = uniqstr @values
464 Since version 1.45.
466 Filters a list of values to remove subsequent duplicates, as judged by
468 a string equality test. Preserves the order of unique elements, and
469 retains the first value of any duplicate set.
470 my $count = uniqstr @values
472 In scalar context, returns the number of elements that would have been
474 returned as a list.
475 Note that "undef" is treated much as other string operations treat it;
477 it compares equal to the empty string but additionally produces a
478 warning if such warnings are enabled ("use warnings 'uninitialized';").
479 In addition, an "undef" in the returned list is coerced into an empty
480 string, so that the entire list of values returned by "uniqstr" are
481 well-behaved as strings.
482
484 RT #95409
485 <https://rt.cpan.org/Ticket/Display.html?id=95409>
486 If the block of code given to "pairmap" contains lexical variables that
488 are captured by a returned closure, and the closure is executed after
489 the block has been re-used for the next iteration, these lexicals will
490 not see the correct values. For example:
491 my @subs = pairmap {
493 my $var = "$a is $b";
494 sub { print "$var\n" };
495 } one => 1, two => 2, three => 3;
496 $_->() for @subs;
498 Will incorrectly print
500 three is 3
502 three is 3
503 three is 3
504 This is due to the performance optimisation of using "MULTICALL" for
506 the code block, which means that fresh SVs do not get allocated for
507 each call to the block. Instead, the same SV is re-assigned for each
508 iteration, and all the closures will share the value seen on the final
509 iteration.
510 To work around this bug, surround the code with a second set of braces.
512 This creates an inner block that defeats the "MULTICALL" logic, and
513 does get fresh SVs allocated each time:
514 my @subs = pairmap {
516 {
517 my $var = "$a is $b";
518 sub { print "$var\n"; }
519 }
520 } one => 1, two => 2, three => 3;
521 This bug only affects closures that are generated by the block but used
523 afterwards. Lexical variables that are only used during the lifetime of
524 the block's execution will take their individual values for each
525 invocation, as normal.
526 uniqnum() on oversized bignums
528 Due to the way that "uniqnum()" compares numbers, it cannot distinguish
529 differences between bignums (especially bigints) that are too large to
530 fit in the native platform types. For example,
531 my $x = Math::BigInt->new( "1" x 100 );
533 my $y = $x + 1;
534 say for uniqnum( $x, $y );
536 Will print just the value of $x, believing that $y is a numerically-
538 equivalent value. This bug does not affect "uniqstr()", which will
539 correctly observe that the two values stringify to different strings.
540
542 The following are additions that have been requested, but I have been
543 reluctant to add due to them being very simple to implement in perl
544 # How many elements are true
546 sub true { scalar grep { $_ } @_ }
548 # How many elements are false
550 sub false { scalar grep { !$_ } @_ }
552
554 Scalar::Util, List::MoreUtils
555
557 Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights
558 reserved. This program is free software; you can redistribute it
559 and/or modify it under the same terms as Perl itself.
560 Recent additions and current maintenance by Paul Evans,
562 <leonerd@leonerd.org.uk>.
563perl v5.26.3 2017-09-08 List::Util(3)