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 reductions
11 max maxstr min minstr product sum sum0
13 pairs unpairs pairkeys pairvalues pairfirst pairgrep pairmap
15 shuffle uniq uniqint 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 apply a given block of code to a
29 list of values.
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 other scalar-returning list reduction functions are all
88 specialisations of this generic idea.
89 reductions
91 @results = reductions { BLOCK } @list
92 Since version 1.54.
94 Similar to "reduce" except that it also returns the intermediate values
96 along with the final result. As before, $a is set to the first element
97 of the given list, and the "BLOCK" is then called once for remaining
98 item in the list set into $b, with the result being captured for return
99 as well as becoming the new value for $a.
100 The returned list will begin with the initial value for $a, followed by
102 each return value from the block in order. The final value of the
103 result will be identical to what the "reduce" function would have
104 returned given the same block and list.
105 reduce { "$a-$b" } "a".."d" # "a-b-c-d"
107 reductions { "$a-$b" } "a".."d" # "a", "a-b", "a-b-c", "a-b-c-d"
108 any
110 my $bool = any { BLOCK } @list;
111 Since version 1.33.
113 Similar to "grep" in that it evaluates "BLOCK" setting $_ to each
115 element of @list in turn. "any" returns true if any element makes the
116 "BLOCK" return a true value. If "BLOCK" never returns true or @list was
117 empty then it returns false.
118 Many cases of using "grep" in a conditional can be written using "any"
120 instead, as it can short-circuit after the first true result.
121 if( any { length > 10 } @strings ) {
123 # at least one string has more than 10 characters
124 }
125 Note: Due to XS issues the block passed may be able to access the outer
127 @_ directly. This is not intentional and will break under debugger.
128 all
130 my $bool = all { BLOCK } @list;
131 Since version 1.33.
133 Similar to "any", except that it requires all elements of the @list to
135 make the "BLOCK" return true. If any element returns false, then it
136 returns false. If the "BLOCK" never returns false or the @list was
137 empty then it returns true.
138 Note: Due to XS issues the block passed may be able to access the outer
140 @_ directly. This is not intentional and will break under debugger.
141 none
143 notall
144 my $bool = none { BLOCK } @list;
145 my $bool = notall { BLOCK } @list;
147 Since version 1.33.
149 Similar to "any" and "all", but with the return sense inverted. "none"
151 returns true only if no value in the @list causes the "BLOCK" to return
152 true, and "notall" returns true only if not all of the values do.
153 Note: Due to XS issues the block passed may be able to access the outer
155 @_ directly. This is not intentional and will break under debugger.
156 first
158 my $val = first { BLOCK } @list;
159 Similar to "grep" in that it evaluates "BLOCK" setting $_ to each
161 element of @list in turn. "first" returns the first element where the
162 result from "BLOCK" is a true value. If "BLOCK" never returns true or
163 @list was empty then "undef" is returned.
164 $foo = first { defined($_) } @list # first defined value in @list
166 $foo = first { $_ > $value } @list # first value in @list which
167 # is greater than $value
168 max
170 my $num = max @list;
171 Returns the entry in the list with the highest numerical value. If the
173 list is empty then "undef" is returned.
174 $foo = max 1..10 # 10
176 $foo = max 3,9,12 # 12
177 $foo = max @bar, @baz # whatever
178 maxstr
180 my $str = maxstr @list;
181 Similar to "max", but treats all the entries in the list as strings and
183 returns the highest string as defined by the "gt" operator. If the list
184 is empty then "undef" is returned.
185 $foo = maxstr 'A'..'Z' # 'Z'
187 $foo = maxstr "hello","world" # "world"
188 $foo = maxstr @bar, @baz # whatever
189 min
191 my $num = min @list;
192 Similar to "max" but returns the entry in the list with the lowest
194 numerical value. If the list is empty then "undef" is returned.
195 $foo = min 1..10 # 1
197 $foo = min 3,9,12 # 3
198 $foo = min @bar, @baz # whatever
199 minstr
201 my $str = minstr @list;
202 Similar to "min", but treats all the entries in the list as strings and
204 returns the lowest string as defined by the "lt" operator. If the list
205 is empty then "undef" is returned.
206 $foo = minstr 'A'..'Z' # 'A'
208 $foo = minstr "hello","world" # "hello"
209 $foo = minstr @bar, @baz # whatever
210 product
212 my $num = product @list;
213 Since version 1.35.
215 Returns the numerical product of all the elements in @list. If @list is
217 empty then 1 is returned.
218 $foo = product 1..10 # 3628800
220 $foo = product 3,9,12 # 324
221 sum
223 my $num_or_undef = sum @list;
224 Returns the numerical sum of all the elements in @list. For backwards
226 compatibility, if @list is empty then "undef" is returned.
227 $foo = sum 1..10 # 55
229 $foo = sum 3,9,12 # 24
230 $foo = sum @bar, @baz # whatever
231 sum0
233 my $num = sum0 @list;
234 Since version 1.26.
236 Similar to "sum", except this returns 0 when given an empty list,
238 rather than "undef".
239
241 The following set of functions, all inspired by List::Pairwise, consume
242 an even-sized list of pairs. The pairs may be key/value associations
243 from a hash, or just a list of values. The functions will all preserve
244 the original ordering of the pairs, and will not be confused by
245 multiple pairs having the same "key" value - nor even do they require
246 that the first of each pair be a plain string.
247 NOTE: At the time of writing, the following "pair*" functions that take
249 a block do not modify the value of $_ within the block, and instead
250 operate using the $a and $b globals instead. This has turned out to be
251 a poor design, as it precludes the ability to provide a "pairsort"
252 function. Better would be to pass pair-like objects as 2-element array
253 references in $_, in a style similar to the return value of the "pairs"
254 function. At some future version this behaviour may be added.
255 Until then, users are alerted NOT to rely on the value of $_ remaining
257 unmodified between the outside and the inside of the control block. In
258 particular, the following example is UNSAFE:
259 my @kvlist = ...
261 foreach (qw( some keys here )) {
263 my @items = pairgrep { $a eq $_ } @kvlist;
264 ...
265 }
266 Instead, write this using a lexical variable:
268 foreach my $key (qw( some keys here )) {
270 my @items = pairgrep { $a eq $key } @kvlist;
271 ...
272 }
273 pairs
275 my @pairs = pairs @kvlist;
276 Since version 1.29.
278 A convenient shortcut to operating on even-sized lists of pairs, this
280 function returns a list of "ARRAY" references, each containing two
281 items from the given list. It is a more efficient version of
282 @pairs = pairmap { [ $a, $b ] } @kvlist
284 It is most convenient to use in a "foreach" loop, for example:
286 foreach my $pair ( pairs @kvlist ) {
288 my ( $key, $value ) = @$pair;
289 ...
290 }
291 Since version 1.39 these "ARRAY" references are blessed objects,
293 recognising the two methods "key" and "value". The following code is
294 equivalent:
295 foreach my $pair ( pairs @kvlist ) {
297 my $key = $pair->key;
298 my $value = $pair->value;
299 ...
300 }
301 Since version 1.51 they also have a "TO_JSON" method to ease
303 serialisation.
304 unpairs
306 my @kvlist = unpairs @pairs
307 Since version 1.42.
309 The inverse function to "pairs"; this function takes a list of "ARRAY"
311 references containing two elements each, and returns a flattened list
312 of the two values from each of the pairs, in order. This is notionally
313 equivalent to
314 my @kvlist = map { @{$_}[0,1] } @pairs
316 except that it is implemented more efficiently internally.
318 Specifically, for any input item it will extract exactly two values for
319 the output list; using "undef" if the input array references are short.
320 Between "pairs" and "unpairs", a higher-order list function can be used
322 to operate on the pairs as single scalars; such as the following near-
323 equivalents of the other "pair*" higher-order functions:
324 @kvlist = unpairs grep { FUNC } pairs @kvlist
326 # Like pairgrep, but takes $_ instead of $a and $b
327 @kvlist = unpairs map { FUNC } pairs @kvlist
329 # Like pairmap, but takes $_ instead of $a and $b
330 Note however that these versions will not behave as nicely in scalar
332 context.
333 Finally, this technique can be used to implement a sort on a keyvalue
335 pair list; e.g.:
336 @kvlist = unpairs sort { $a->key cmp $b->key } pairs @kvlist
338 pairkeys
340 my @keys = pairkeys @kvlist;
341 Since version 1.29.
343 A convenient shortcut to operating on even-sized lists of pairs, this
345 function returns a list of the the first values of each of the pairs in
346 the given list. It is a more efficient version of
347 @keys = pairmap { $a } @kvlist
349 pairvalues
351 my @values = pairvalues @kvlist;
352 Since version 1.29.
354 A convenient shortcut to operating on even-sized lists of pairs, this
356 function returns a list of the the second values of each of the pairs
357 in the given list. It is a more efficient version of
358 @values = pairmap { $b } @kvlist
360 pairgrep
362 my @kvlist = pairgrep { BLOCK } @kvlist;
363 my $count = pairgrep { BLOCK } @kvlist;
365 Since version 1.29.
367 Similar to perl's "grep" keyword, but interprets the given list as an
369 even-sized list of pairs. It invokes the "BLOCK" multiple times, in
370 scalar context, with $a and $b set to successive pairs of values from
371 the @kvlist.
372 Returns an even-sized list of those pairs for which the "BLOCK"
374 returned true in list context, or the count of the number of pairs in
375 scalar context. (Note, therefore, in scalar context that it returns a
376 number half the size of the count of items it would have returned in
377 list context).
378 @subset = pairgrep { $a =~ m/^[[:upper:]]+$/ } @kvlist
380 As with "grep" aliasing $_ to list elements, "pairgrep" aliases $a and
382 $b to elements of the given list. Any modifications of it by the code
383 block will be visible to the caller.
384 pairfirst
386 my ( $key, $val ) = pairfirst { BLOCK } @kvlist;
387 my $found = pairfirst { BLOCK } @kvlist;
389 Since version 1.30.
391 Similar to the "first" function, but interprets the given list as an
393 even-sized list of pairs. It invokes the "BLOCK" multiple times, in
394 scalar context, with $a and $b set to successive pairs of values from
395 the @kvlist.
396 Returns the first pair of values from the list for which the "BLOCK"
398 returned true in list context, or an empty list of no such pair was
399 found. In scalar context it returns a simple boolean value, rather than
400 either the key or the value found.
401 ( $key, $value ) = pairfirst { $a =~ m/^[[:upper:]]+$/ } @kvlist
403 As with "grep" aliasing $_ to list elements, "pairfirst" aliases $a and
405 $b to elements of the given list. Any modifications of it by the code
406 block will be visible to the caller.
407 pairmap
409 my @list = pairmap { BLOCK } @kvlist;
410 my $count = pairmap { BLOCK } @kvlist;
412 Since version 1.29.
414 Similar to perl's "map" keyword, but interprets the given list as an
416 even-sized list of pairs. It invokes the "BLOCK" multiple times, in
417 list context, with $a and $b set to successive pairs of values from the
418 @kvlist.
419 Returns the concatenation of all the values returned by the "BLOCK" in
421 list context, or the count of the number of items that would have been
422 returned in scalar context.
423 @result = pairmap { "The key $a has value $b" } @kvlist
425 As with "map" aliasing $_ to list elements, "pairmap" aliases $a and $b
427 to elements of the given list. Any modifications of it by the code
428 block will be visible to the caller.
429 See "KNOWN BUGS" for a known-bug with "pairmap", and a workaround.
431
433 shuffle
434 my @values = shuffle @values;
435 Returns the values of the input in a random order
437 @cards = shuffle 0..51 # 0..51 in a random order
439 This function is affected by the $RAND variable.
441 sample
443 my @items = sample $count, @values
444 Since version 1.54.
446 Randomly select the given number of elements from the input list. Any
448 given position in the input list will be selected at most once.
449 If there are fewer than $count items in the list then the function will
451 return once all of them have been randomly selected; effectively the
452 function behaves similarly to "shuffle".
453 This function is affected by the $RAND variable.
455 uniq
457 my @subset = uniq @values
458 Since version 1.45.
460 Filters a list of values to remove subsequent duplicates, as judged by
462 a DWIM-ish string equality or "undef" test. Preserves the order of
463 unique elements, and retains the first value of any duplicate set.
464 my $count = uniq @values
466 In scalar context, returns the number of elements that would have been
468 returned as a list.
469 The "undef" value is treated by this function as distinct from the
471 empty string, and no warning will be produced. It is left as-is in the
472 returned list. Subsequent "undef" values are still considered identical
473 to the first, and will be removed.
474 uniqint
476 my @subset = uniqint @values
477 Since version 1.55.
479 Filters a list of values to remove subsequent duplicates, as judged by
481 an integer numerical equality test. Preserves the order of unique
482 elements, and retains the first value of any duplicate set. Values in
483 the returned list will be coerced into integers.
484 my $count = uniqint @values
486 In scalar context, returns the number of elements that would have been
488 returned as a list.
489 Note that "undef" is treated much as other numerical operations treat
491 it; it compares equal to zero but additionally produces a warning if
492 such warnings are enabled ("use warnings 'uninitialized';"). In
493 addition, an "undef" in the returned list is coerced into a numerical
494 zero, so that the entire list of values returned by "uniqint" are well-
495 behaved as integers.
496 uniqnum
498 my @subset = uniqnum @values
499 Since version 1.44.
501 Filters a list of values to remove subsequent duplicates, as judged by
503 a numerical equality test. Preserves the order of unique elements, and
504 retains the first value of any duplicate set.
505 my $count = uniqnum @values
507 In scalar context, returns the number of elements that would have been
509 returned as a list.
510 Note that "undef" is treated much as other numerical operations treat
512 it; it compares equal to zero but additionally produces a warning if
513 such warnings are enabled ("use warnings 'uninitialized';"). In
514 addition, an "undef" in the returned list is coerced into a numerical
515 zero, so that the entire list of values returned by "uniqnum" are well-
516 behaved as numbers.
517 Note also that multiple IEEE "NaN" values are treated as duplicates of
519 each other, regardless of any differences in their payloads, and
520 despite the fact that "0+'NaN' == 0+'NaN'" yields false.
521 uniqstr
523 my @subset = uniqstr @values
524 Since version 1.45.
526 Filters a list of values to remove subsequent duplicates, as judged by
528 a string equality test. Preserves the order of unique elements, and
529 retains the first value of any duplicate set.
530 my $count = uniqstr @values
532 In scalar context, returns the number of elements that would have been
534 returned as a list.
535 Note that "undef" is treated much as other string operations treat it;
537 it compares equal to the empty string but additionally produces a
538 warning if such warnings are enabled ("use warnings 'uninitialized';").
539 In addition, an "undef" in the returned list is coerced into an empty
540 string, so that the entire list of values returned by "uniqstr" are
541 well-behaved as strings.
542 head
544 my @values = head $size, @list;
545 Since version 1.50.
547 Returns the first $size elements from @list. If $size is negative,
549 returns all but the last $size elements from @list.
550 @result = head 2, qw( foo bar baz );
552 # foo, bar
553 @result = head -2, qw( foo bar baz );
555 # foo
556 tail
558 my @values = tail $size, @list;
559 Since version 1.50.
561 Returns the last $size elements from @list. If $size is negative,
563 returns all but the first $size elements from @list.
564 @result = tail 2, qw( foo bar baz );
566 # bar, baz
567 @result = tail -2, qw( foo bar baz );
569 # baz
570
572 $RAND
573 local $List::Util::RAND = sub { ... };
574 Since version 1.54.
576 This package variable is used by code which needs to generate random
578 numbers (such as the "shuffle" and "sample" functions). If set to a
579 CODE reference it provides an alternative to perl's builtin "rand()"
580 function. When a new random number is needed this function will be
581 invoked with no arguments and is expected to return a floating-point
582 value, of which only the fractional part will be used.
583
585 RT #95409
586 <https://rt.cpan.org/Ticket/Display.html?id=95409>
587 If the block of code given to "pairmap" contains lexical variables that
589 are captured by a returned closure, and the closure is executed after
590 the block has been re-used for the next iteration, these lexicals will
591 not see the correct values. For example:
592 my @subs = pairmap {
594 my $var = "$a is $b";
595 sub { print "$var\n" };
596 } one => 1, two => 2, three => 3;
597 $_->() for @subs;
599 Will incorrectly print
601 three is 3
603 three is 3
604 three is 3
605 This is due to the performance optimisation of using "MULTICALL" for
607 the code block, which means that fresh SVs do not get allocated for
608 each call to the block. Instead, the same SV is re-assigned for each
609 iteration, and all the closures will share the value seen on the final
610 iteration.
611 To work around this bug, surround the code with a second set of braces.
613 This creates an inner block that defeats the "MULTICALL" logic, and
614 does get fresh SVs allocated each time:
615 my @subs = pairmap {
617 {
618 my $var = "$a is $b";
619 sub { print "$var\n"; }
620 }
621 } one => 1, two => 2, three => 3;
622 This bug only affects closures that are generated by the block but used
624 afterwards. Lexical variables that are only used during the lifetime of
625 the block's execution will take their individual values for each
626 invocation, as normal.
627 uniqnum() on oversized bignums
629 Due to the way that "uniqnum()" compares numbers, it cannot distinguish
630 differences between bignums (especially bigints) that are too large to
631 fit in the native platform types. For example,
632 my $x = Math::BigInt->new( "1" x 100 );
634 my $y = $x + 1;
635 say for uniqnum( $x, $y );
637 Will print just the value of $x, believing that $y is a numerically-
639 equivalent value. This bug does not affect "uniqstr()", which will
640 correctly observe that the two values stringify to different strings.
641
643 The following are additions that have been requested, but I have been
644 reluctant to add due to them being very simple to implement in perl
645 # How many elements are true
647 sub true { scalar grep { $_ } @_ }
649 # How many elements are false
651 sub false { scalar grep { !$_ } @_ }
653
655 Scalar::Util, List::MoreUtils
656
658 Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights
659 reserved. This program is free software; you can redistribute it
660 and/or modify it under the same terms as Perl itself.
661 Recent additions and current maintenance by Paul Evans,
663 <leonerd@leonerd.org.uk>.
664perl v5.32.0 2020-07-28 List::Util(3)