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 Since version 1.51 they also have a "TO_JSON" method to ease
284 serialisation.
285 unpairs
287 my @kvlist = unpairs @pairs
288 Since version 1.42.
290 The inverse function to "pairs"; this function takes a list of "ARRAY"
292 references containing two elements each, and returns a flattened list
293 of the two values from each of the pairs, in order. This is notionally
294 equivalent to
295 my @kvlist = map { @{$_}[0,1] } @pairs
297 except that it is implemented more efficiently internally.
299 Specifically, for any input item it will extract exactly two values for
300 the output list; using "undef" if the input array references are short.
301 Between "pairs" and "unpairs", a higher-order list function can be used
303 to operate on the pairs as single scalars; such as the following near-
304 equivalents of the other "pair*" higher-order functions:
305 @kvlist = unpairs grep { FUNC } pairs @kvlist
307 # Like pairgrep, but takes $_ instead of $a and $b
308 @kvlist = unpairs map { FUNC } pairs @kvlist
310 # Like pairmap, but takes $_ instead of $a and $b
311 Note however that these versions will not behave as nicely in scalar
313 context.
314 Finally, this technique can be used to implement a sort on a keyvalue
316 pair list; e.g.:
317 @kvlist = unpairs sort { $a->key cmp $b->key } pairs @kvlist
319 pairkeys
321 my @keys = pairkeys @kvlist;
322 Since version 1.29.
324 A convenient shortcut to operating on even-sized lists of pairs, this
326 function returns a list of the the first values of each of the pairs in
327 the given list. It is a more efficient version of
328 @keys = pairmap { $a } @kvlist
330 pairvalues
332 my @values = pairvalues @kvlist;
333 Since version 1.29.
335 A convenient shortcut to operating on even-sized lists of pairs, this
337 function returns a list of the the second values of each of the pairs
338 in the given list. It is a more efficient version of
339 @values = pairmap { $b } @kvlist
341 pairgrep
343 my @kvlist = pairgrep { BLOCK } @kvlist;
344 my $count = pairgrep { BLOCK } @kvlist;
346 Since version 1.29.
348 Similar to perl's "grep" keyword, but interprets the given list as an
350 even-sized list of pairs. It invokes the "BLOCK" multiple times, in
351 scalar context, with $a and $b set to successive pairs of values from
352 the @kvlist.
353 Returns an even-sized list of those pairs for which the "BLOCK"
355 returned true in list context, or the count of the number of pairs in
356 scalar context. (Note, therefore, in scalar context that it returns a
357 number half the size of the count of items it would have returned in
358 list context).
359 @subset = pairgrep { $a =~ m/^[[:upper:]]+$/ } @kvlist
361 As with "grep" aliasing $_ to list elements, "pairgrep" aliases $a and
363 $b to elements of the given list. Any modifications of it by the code
364 block will be visible to the caller.
365 pairfirst
367 my ( $key, $val ) = pairfirst { BLOCK } @kvlist;
368 my $found = pairfirst { BLOCK } @kvlist;
370 Since version 1.30.
372 Similar to the "first" function, but interprets the given list as an
374 even-sized list of pairs. It invokes the "BLOCK" multiple times, in
375 scalar context, with $a and $b set to successive pairs of values from
376 the @kvlist.
377 Returns the first pair of values from the list for which the "BLOCK"
379 returned true in list context, or an empty list of no such pair was
380 found. In scalar context it returns a simple boolean value, rather than
381 either the key or the value found.
382 ( $key, $value ) = pairfirst { $a =~ m/^[[:upper:]]+$/ } @kvlist
384 As with "grep" aliasing $_ to list elements, "pairfirst" aliases $a and
386 $b to elements of the given list. Any modifications of it by the code
387 block will be visible to the caller.
388 pairmap
390 my @list = pairmap { BLOCK } @kvlist;
391 my $count = pairmap { BLOCK } @kvlist;
393 Since version 1.29.
395 Similar to perl's "map" keyword, but interprets the given list as an
397 even-sized list of pairs. It invokes the "BLOCK" multiple times, in
398 list context, with $a and $b set to successive pairs of values from the
399 @kvlist.
400 Returns the concatenation of all the values returned by the "BLOCK" in
402 list context, or the count of the number of items that would have been
403 returned in scalar context.
404 @result = pairmap { "The key $a has value $b" } @kvlist
406 As with "map" aliasing $_ to list elements, "pairmap" aliases $a and $b
408 to elements of the given list. Any modifications of it by the code
409 block will be visible to the caller.
410 See "KNOWN BUGS" for a known-bug with "pairmap", and a workaround.
412
414 shuffle
415 my @values = shuffle @values;
416 Returns the values of the input in a random order
418 @cards = shuffle 0..51 # 0..51 in a random order
420 uniq
422 my @subset = uniq @values
423 Since version 1.45.
425 Filters a list of values to remove subsequent duplicates, as judged by
427 a DWIM-ish string equality or "undef" test. Preserves the order of
428 unique elements, and retains the first value of any duplicate set.
429 my $count = uniq @values
431 In scalar context, returns the number of elements that would have been
433 returned as a list.
434 The "undef" value is treated by this function as distinct from the
436 empty string, and no warning will be produced. It is left as-is in the
437 returned list. Subsequent "undef" values are still considered identical
438 to the first, and will be removed.
439 uniqnum
441 my @subset = uniqnum @values
442 Since version 1.44.
444 Filters a list of values to remove subsequent duplicates, as judged by
446 a numerical equality test. Preserves the order of unique elements, and
447 retains the first value of any duplicate set.
448 my $count = uniqnum @values
450 In scalar context, returns the number of elements that would have been
452 returned as a list.
453 Note that "undef" is treated much as other numerical operations treat
455 it; it compares equal to zero but additionally produces a warning if
456 such warnings are enabled ("use warnings 'uninitialized';"). In
457 addition, an "undef" in the returned list is coerced into a numerical
458 zero, so that the entire list of values returned by "uniqnum" are well-
459 behaved as numbers.
460 Note also that multiple IEEE "NaN" values are treated as duplicates of
462 each other, regardless of any differences in their payloads, and
463 despite the fact that "0+'NaN' == 0+'NaN'" yields false.
464 uniqstr
466 my @subset = uniqstr @values
467 Since version 1.45.
469 Filters a list of values to remove subsequent duplicates, as judged by
471 a string equality test. Preserves the order of unique elements, and
472 retains the first value of any duplicate set.
473 my $count = uniqstr @values
475 In scalar context, returns the number of elements that would have been
477 returned as a list.
478 Note that "undef" is treated much as other string operations treat it;
480 it compares equal to the empty string but additionally produces a
481 warning if such warnings are enabled ("use warnings 'uninitialized';").
482 In addition, an "undef" in the returned list is coerced into an empty
483 string, so that the entire list of values returned by "uniqstr" are
484 well-behaved as strings.
485 head
487 my @values = head $size, @list;
488 Since version 1.50.
490 Returns the first $size elements from @list. If $size is negative,
492 returns all but the last $size elements from @list.
493 @result = head 2, qw( foo bar baz );
495 # foo, bar
496 @result = head -2, qw( foo bar baz );
498 # foo
499 tail
501 my @values = tail $size, @list;
502 Since version 1.50.
504 Returns the last $size elements from @list. If $size is negative,
506 returns all but the first $size elements from @list.
507 @result = tail 2, qw( foo bar baz );
509 # bar, baz
510 @result = tail -2, qw( foo bar baz );
512 # baz
513
515 RT #95409
516 <https://rt.cpan.org/Ticket/Display.html?id=95409>
517 If the block of code given to "pairmap" contains lexical variables that
519 are captured by a returned closure, and the closure is executed after
520 the block has been re-used for the next iteration, these lexicals will
521 not see the correct values. For example:
522 my @subs = pairmap {
524 my $var = "$a is $b";
525 sub { print "$var\n" };
526 } one => 1, two => 2, three => 3;
527 $_->() for @subs;
529 Will incorrectly print
531 three is 3
533 three is 3
534 three is 3
535 This is due to the performance optimisation of using "MULTICALL" for
537 the code block, which means that fresh SVs do not get allocated for
538 each call to the block. Instead, the same SV is re-assigned for each
539 iteration, and all the closures will share the value seen on the final
540 iteration.
541 To work around this bug, surround the code with a second set of braces.
543 This creates an inner block that defeats the "MULTICALL" logic, and
544 does get fresh SVs allocated each time:
545 my @subs = pairmap {
547 {
548 my $var = "$a is $b";
549 sub { print "$var\n"; }
550 }
551 } one => 1, two => 2, three => 3;
552 This bug only affects closures that are generated by the block but used
554 afterwards. Lexical variables that are only used during the lifetime of
555 the block's execution will take their individual values for each
556 invocation, as normal.
557 uniqnum() on oversized bignums
559 Due to the way that "uniqnum()" compares numbers, it cannot distinguish
560 differences between bignums (especially bigints) that are too large to
561 fit in the native platform types. For example,
562 my $x = Math::BigInt->new( "1" x 100 );
564 my $y = $x + 1;
565 say for uniqnum( $x, $y );
567 Will print just the value of $x, believing that $y is a numerically-
569 equivalent value. This bug does not affect "uniqstr()", which will
570 correctly observe that the two values stringify to different strings.
571
573 The following are additions that have been requested, but I have been
574 reluctant to add due to them being very simple to implement in perl
575 # How many elements are true
577 sub true { scalar grep { $_ } @_ }
579 # How many elements are false
581 sub false { scalar grep { !$_ } @_ }
583
585 Scalar::Util, List::MoreUtils
586
588 Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights
589 reserved. This program is free software; you can redistribute it
590 and/or modify it under the same terms as Perl itself.
591 Recent additions and current maintenance by Paul Evans,
593 <leonerd@leonerd.org.uk>.
594perl v5.30.0 2019-10-25 List::Util(3)