1List::Util(3)         User Contributed Perl Documentation        List::Util(3)
2
3
4

NAME

6       List::Util - A selection of general-utility list subroutines
7

SYNOPSIS

9           use List::Util qw(
10             reduce any all none notall first reductions
11
12             max maxstr min minstr product sum sum0
13
14             pairs unpairs pairkeys pairvalues pairfirst pairgrep pairmap
15
16             shuffle uniq uniqnum uniqstr
17           );
18

DESCRIPTION

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
25       By default "List::Util" does not export any subroutines.
26

LIST-REDUCTION FUNCTIONS

28       The following set of functions all apply a given block of code to a
29       list of values.
30
31   reduce
32           $result = reduce { BLOCK } @list
33
34       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
40       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
44       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
49           $foo = reduce { defined($a)            ? $a :
50                           $code->(local $_ = $b) ? $b :
51                                                    undef } undef, @list # first
52
53           $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
60           $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
66       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
70         $foo = reduce { $a + $b } 0, @values;             # sum with 0 identity value
71
72       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
77           $total = sum map { length } @strings;
78
79       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
85           $total = reduce { $a + length $b } 0, @strings
86
87       The other scalar-returning list reduction functions are all
88       specialisations of this generic idea.
89
90   reductions
91           @results = reductions { BLOCK } @list
92
93       Since version 1.54.
94
95       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
101       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
106           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
109   any
110           my $bool = any { BLOCK } @list;
111
112       Since version 1.33.
113
114       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
119       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
122           if( any { length > 10 } @strings ) {
123               # at least one string has more than 10 characters
124           }
125
126       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
129   all
130           my $bool = all { BLOCK } @list;
131
132       Since version 1.33.
133
134       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
139       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
142   none
143   notall
144           my $bool = none { BLOCK } @list;
145
146           my $bool = notall { BLOCK } @list;
147
148       Since version 1.33.
149
150       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
154       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
157   first
158           my $val = first { BLOCK } @list;
159
160       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
165           $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
169   max
170           my $num = max @list;
171
172       Returns the entry in the list with the highest numerical value. If the
173       list is empty then "undef" is returned.
174
175           $foo = max 1..10                # 10
176           $foo = max 3,9,12               # 12
177           $foo = max @bar, @baz           # whatever
178
179   maxstr
180           my $str = maxstr @list;
181
182       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
186           $foo = maxstr 'A'..'Z'          # 'Z'
187           $foo = maxstr "hello","world"   # "world"
188           $foo = maxstr @bar, @baz        # whatever
189
190   min
191           my $num = min @list;
192
193       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
196           $foo = min 1..10                # 1
197           $foo = min 3,9,12               # 3
198           $foo = min @bar, @baz           # whatever
199
200   minstr
201           my $str = minstr @list;
202
203       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
207           $foo = minstr 'A'..'Z'          # 'A'
208           $foo = minstr "hello","world"   # "hello"
209           $foo = minstr @bar, @baz        # whatever
210
211   product
212           my $num = product @list;
213
214       Since version 1.35.
215
216       Returns the numerical product of all the elements in @list. If @list is
217       empty then 1 is returned.
218
219           $foo = product 1..10            # 3628800
220           $foo = product 3,9,12           # 324
221
222   sum
223           my $num_or_undef = sum @list;
224
225       Returns the numerical sum of all the elements in @list. For backwards
226       compatibility, if @list is empty then "undef" is returned.
227
228           $foo = sum 1..10                # 55
229           $foo = sum 3,9,12               # 24
230           $foo = sum @bar, @baz           # whatever
231
232   sum0
233           my $num = sum0 @list;
234
235       Since version 1.26.
236
237       Similar to "sum", except this returns 0 when given an empty list,
238       rather than "undef".
239

KEY/VALUE PAIR LIST FUNCTIONS

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
248       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
256       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
260        my @kvlist = ...
261
262        foreach (qw( some keys here )) {
263           my @items = pairgrep { $a eq $_ } @kvlist;
264           ...
265        }
266
267       Instead, write this using a lexical variable:
268
269        foreach my $key (qw( some keys here )) {
270           my @items = pairgrep { $a eq $key } @kvlist;
271           ...
272        }
273
274   pairs
275           my @pairs = pairs @kvlist;
276
277       Since version 1.29.
278
279       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
283           @pairs = pairmap { [ $a, $b ] } @kvlist
284
285       It is most convenient to use in a "foreach" loop, for example:
286
287           foreach my $pair ( pairs @kvlist ) {
288              my ( $key, $value ) = @$pair;
289              ...
290           }
291
292       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
296           foreach my $pair ( pairs @kvlist ) {
297              my $key   = $pair->key;
298              my $value = $pair->value;
299              ...
300           }
301
302       Since version 1.51 they also have a "TO_JSON" method to ease
303       serialisation.
304
305   unpairs
306           my @kvlist = unpairs @pairs
307
308       Since version 1.42.
309
310       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
315           my @kvlist = map { @{$_}[0,1] } @pairs
316
317       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
321       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
325           @kvlist = unpairs grep { FUNC } pairs @kvlist
326           # Like pairgrep, but takes $_ instead of $a and $b
327
328           @kvlist = unpairs map { FUNC } pairs @kvlist
329           # Like pairmap, but takes $_ instead of $a and $b
330
331       Note however that these versions will not behave as nicely in scalar
332       context.
333
334       Finally, this technique can be used to implement a sort on a keyvalue
335       pair list; e.g.:
336
337           @kvlist = unpairs sort { $a->key cmp $b->key } pairs @kvlist
338
339   pairkeys
340           my @keys = pairkeys @kvlist;
341
342       Since version 1.29.
343
344       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
348           @keys = pairmap { $a } @kvlist
349
350   pairvalues
351           my @values = pairvalues @kvlist;
352
353       Since version 1.29.
354
355       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
359           @values = pairmap { $b } @kvlist
360
361   pairgrep
362           my @kvlist = pairgrep { BLOCK } @kvlist;
363
364           my $count = pairgrep { BLOCK } @kvlist;
365
366       Since version 1.29.
367
368       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
373       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
379           @subset = pairgrep { $a =~ m/^[[:upper:]]+$/ } @kvlist
380
381       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
385   pairfirst
386           my ( $key, $val ) = pairfirst { BLOCK } @kvlist;
387
388           my $found = pairfirst { BLOCK } @kvlist;
389
390       Since version 1.30.
391
392       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
397       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
402           ( $key, $value ) = pairfirst { $a =~ m/^[[:upper:]]+$/ } @kvlist
403
404       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
408   pairmap
409           my @list = pairmap { BLOCK } @kvlist;
410
411           my $count = pairmap { BLOCK } @kvlist;
412
413       Since version 1.29.
414
415       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
420       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
424           @result = pairmap { "The key $a has value $b" } @kvlist
425
426       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
430       See "KNOWN BUGS" for a known-bug with "pairmap", and a workaround.
431

OTHER FUNCTIONS

433   shuffle
434           my @values = shuffle @values;
435
436       Returns the values of the input in a random order
437
438           @cards = shuffle 0..51      # 0..51 in a random order
439
440       This function is affected by the $RAND variable.
441
442   sample
443           my @items = sample $count, @values
444
445       Since version 1.54.
446
447       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
450       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
454       This function is affected by the $RAND variable.
455
456   uniq
457           my @subset = uniq @values
458
459       Since version 1.45.
460
461       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
465           my $count = uniq @values
466
467       In scalar context, returns the number of elements that would have been
468       returned as a list.
469
470       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
475   uniqnum
476           my @subset = uniqnum @values
477
478       Since version 1.44.
479
480       Filters a list of values to remove subsequent duplicates, as judged by
481       a numerical equality test. Preserves the order of unique elements, and
482       retains the first value of any duplicate set.
483
484           my $count = uniqnum @values
485
486       In scalar context, returns the number of elements that would have been
487       returned as a list.
488
489       Note that "undef" is treated much as other numerical operations treat
490       it; it compares equal to zero but additionally produces a warning if
491       such warnings are enabled ("use warnings 'uninitialized';"). In
492       addition, an "undef" in the returned list is coerced into a numerical
493       zero, so that the entire list of values returned by "uniqnum" are well-
494       behaved as numbers.
495
496       Note also that multiple IEEE "NaN" values are treated as duplicates of
497       each other, regardless of any differences in their payloads, and
498       despite the fact that "0+'NaN' == 0+'NaN'" yields false.
499
500   uniqstr
501           my @subset = uniqstr @values
502
503       Since version 1.45.
504
505       Filters a list of values to remove subsequent duplicates, as judged by
506       a string equality test. Preserves the order of unique elements, and
507       retains the first value of any duplicate set.
508
509           my $count = uniqstr @values
510
511       In scalar context, returns the number of elements that would have been
512       returned as a list.
513
514       Note that "undef" is treated much as other string operations treat it;
515       it compares equal to the empty string but additionally produces a
516       warning if such warnings are enabled ("use warnings 'uninitialized';").
517       In addition, an "undef" in the returned list is coerced into an empty
518       string, so that the entire list of values returned by "uniqstr" are
519       well-behaved as strings.
520
521   head
522           my @values = head $size, @list;
523
524       Since version 1.50.
525
526       Returns the first $size elements from @list. If $size is negative,
527       returns all but the last $size elements from @list.
528
529           @result = head 2, qw( foo bar baz );
530           # foo, bar
531
532           @result = head -2, qw( foo bar baz );
533           # foo
534
535   tail
536           my @values = tail $size, @list;
537
538       Since version 1.50.
539
540       Returns the last $size elements from @list. If $size is negative,
541       returns all but the first $size elements from @list.
542
543           @result = tail 2, qw( foo bar baz );
544           # bar, baz
545
546           @result = tail -2, qw( foo bar baz );
547           # baz
548

CONFIGURATION VARIABLES

550   $RAND
551           local $List::Util::RAND = sub { ... };
552
553       Since version 1.54.
554
555       This package variable is used by code which needs to generate random
556       numbers (such as the "shuffle" and "sample" functions). If set to a
557       CODE reference it provides an alternative to perl's builtin "rand()"
558       function. When a new random number is needed this function will be
559       invoked with no arguments and is expected to return a floating-point
560       value, of which only the fractional part will be used.
561

KNOWN BUGS

563   RT #95409
564       <https://rt.cpan.org/Ticket/Display.html?id=95409>
565
566       If the block of code given to "pairmap" contains lexical variables that
567       are captured by a returned closure, and the closure is executed after
568       the block has been re-used for the next iteration, these lexicals will
569       not see the correct values. For example:
570
571        my @subs = pairmap {
572           my $var = "$a is $b";
573           sub { print "$var\n" };
574        } one => 1, two => 2, three => 3;
575
576        $_->() for @subs;
577
578       Will incorrectly print
579
580        three is 3
581        three is 3
582        three is 3
583
584       This is due to the performance optimisation of using "MULTICALL" for
585       the code block, which means that fresh SVs do not get allocated for
586       each call to the block. Instead, the same SV is re-assigned for each
587       iteration, and all the closures will share the value seen on the final
588       iteration.
589
590       To work around this bug, surround the code with a second set of braces.
591       This creates an inner block that defeats the "MULTICALL" logic, and
592       does get fresh SVs allocated each time:
593
594        my @subs = pairmap {
595           {
596              my $var = "$a is $b";
597              sub { print "$var\n"; }
598           }
599        } one => 1, two => 2, three => 3;
600
601       This bug only affects closures that are generated by the block but used
602       afterwards. Lexical variables that are only used during the lifetime of
603       the block's execution will take their individual values for each
604       invocation, as normal.
605
606   uniqnum() on oversized bignums
607       Due to the way that "uniqnum()" compares numbers, it cannot distinguish
608       differences between bignums (especially bigints) that are too large to
609       fit in the native platform types. For example,
610
611        my $x = Math::BigInt->new( "1" x 100 );
612        my $y = $x + 1;
613
614        say for uniqnum( $x, $y );
615
616       Will print just the value of $x, believing that $y is a numerically-
617       equivalent value. This bug does not affect "uniqstr()", which will
618       correctly observe that the two values stringify to different strings.
619

SUGGESTED ADDITIONS

621       The following are additions that have been requested, but I have been
622       reluctant to add due to them being very simple to implement in perl
623
624         # How many elements are true
625
626         sub true { scalar grep { $_ } @_ }
627
628         # How many elements are false
629
630         sub false { scalar grep { !$_ } @_ }
631

SEE ALSO

633       Scalar::Util, List::MoreUtils
634
636       Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights
637       reserved.  This program is free software; you can redistribute it
638       and/or modify it under the same terms as Perl itself.
639
640       Recent additions and current maintenance by Paul Evans,
641       <leonerd@leonerd.org.uk>.
642
643
644
645perl v5.30.1                      2020-02-03                     List::Util(3)
Impressum