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
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 reduce a list down to a single
29       value.
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 remaining list-reduction functions are all specialisations of this
88       generic idea.
89
90   any
91           my $bool = any { BLOCK } @list;
92
93       Since version 1.33.
94
95       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
100       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
103           if( any { length > 10 } @strings ) {
104               # at least one string has more than 10 characters
105           }
106
107       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
110   all
111           my $bool = all { BLOCK } @list;
112
113       Since version 1.33.
114
115       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
120       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
123   none
124   notall
125           my $bool = none { BLOCK } @list;
126
127           my $bool = notall { BLOCK } @list;
128
129       Since version 1.33.
130
131       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
135       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
138   first
139           my $val = first { BLOCK } @list;
140
141       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
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   max
151           my $num = max @list;
152
153       Returns the entry in the list with the highest numerical value. If the
154       list is empty then "undef" is returned.
155
156           $foo = max 1..10                # 10
157           $foo = max 3,9,12               # 12
158           $foo = max @bar, @baz           # whatever
159
160   maxstr
161           my $str = maxstr @list;
162
163       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
167           $foo = maxstr 'A'..'Z'          # 'Z'
168           $foo = maxstr "hello","world"   # "world"
169           $foo = maxstr @bar, @baz        # whatever
170
171   min
172           my $num = min @list;
173
174       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
177           $foo = min 1..10                # 1
178           $foo = min 3,9,12               # 3
179           $foo = min @bar, @baz           # whatever
180
181   minstr
182           my $str = minstr @list;
183
184       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
188           $foo = minstr 'A'..'Z'          # 'A'
189           $foo = minstr "hello","world"   # "hello"
190           $foo = minstr @bar, @baz        # whatever
191
192   product
193           my $num = product @list;
194
195       Since version 1.35.
196
197       Returns the numerical product of all the elements in @list. If @list is
198       empty then 1 is returned.
199
200           $foo = product 1..10            # 3628800
201           $foo = product 3,9,12           # 324
202
203   sum
204           my $num_or_undef = sum @list;
205
206       Returns the numerical sum of all the elements in @list. For backwards
207       compatibility, if @list is empty then "undef" is returned.
208
209           $foo = sum 1..10                # 55
210           $foo = sum 3,9,12               # 24
211           $foo = sum @bar, @baz           # whatever
212
213   sum0
214           my $num = sum0 @list;
215
216       Since version 1.26.
217
218       Similar to "sum", except this returns 0 when given an empty list,
219       rather than "undef".
220

KEY/VALUE PAIR LIST FUNCTIONS

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
229       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
237       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
241        my @kvlist = ...
242
243        foreach (qw( some keys here )) {
244           my @items = pairgrep { $a eq $_ } @kvlist;
245           ...
246        }
247
248       Instead, write this using a lexical variable:
249
250        foreach my $key (qw( some keys here )) {
251           my @items = pairgrep { $a eq $key } @kvlist;
252           ...
253        }
254
255   pairs
256           my @pairs = pairs @kvlist;
257
258       Since version 1.29.
259
260       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
264           @pairs = pairmap { [ $a, $b ] } @kvlist
265
266       It is most convenient to use in a "foreach" loop, for example:
267
268           foreach my $pair ( pairs @kvlist ) {
269              my ( $key, $value ) = @$pair;
270              ...
271           }
272
273       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
277           foreach my $pair ( pairs @kvlist ) {
278              my $key   = $pair->key;
279              my $value = $pair->value;
280              ...
281           }
282
283   unpairs
284           my @kvlist = unpairs @pairs
285
286       Since version 1.42.
287
288       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
293           my @kvlist = map { @{$_}[0,1] } @pairs
294
295       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
299       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
303           @kvlist = unpairs grep { FUNC } pairs @kvlist
304           # Like pairgrep, but takes $_ instead of $a and $b
305
306           @kvlist = unpairs map { FUNC } pairs @kvlist
307           # Like pairmap, but takes $_ instead of $a and $b
308
309       Note however that these versions will not behave as nicely in scalar
310       context.
311
312       Finally, this technique can be used to implement a sort on a keyvalue
313       pair list; e.g.:
314
315           @kvlist = unpairs sort { $a->key cmp $b->key } pairs @kvlist
316
317   pairkeys
318           my @keys = pairkeys @kvlist;
319
320       Since version 1.29.
321
322       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
326           @keys = pairmap { $a } @kvlist
327
328   pairvalues
329           my @values = pairvalues @kvlist;
330
331       Since version 1.29.
332
333       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
337           @values = pairmap { $b } @kvlist
338
339   pairgrep
340           my @kvlist = pairgrep { BLOCK } @kvlist;
341
342           my $count = pairgrep { BLOCK } @kvlist;
343
344       Since version 1.29.
345
346       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
351       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
357           @subset = pairgrep { $a =~ m/^[[:upper:]]+$/ } @kvlist
358
359       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
363   pairfirst
364           my ( $key, $val ) = pairfirst { BLOCK } @kvlist;
365
366           my $found = pairfirst { BLOCK } @kvlist;
367
368       Since version 1.30.
369
370       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
375       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
380           ( $key, $value ) = pairfirst { $a =~ m/^[[:upper:]]+$/ } @kvlist
381
382       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
386   pairmap
387           my @list = pairmap { BLOCK } @kvlist;
388
389           my $count = pairmap { BLOCK } @kvlist;
390
391       Since version 1.29.
392
393       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
398       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
402           @result = pairmap { "The key $a has value $b" } @kvlist
403
404       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
408       See "KNOWN BUGS" for a known-bug with "pairmap", and a workaround.
409

OTHER FUNCTIONS

411   shuffle
412           my @values = shuffle @values;
413
414       Returns the values of the input in a random order
415
416           @cards = shuffle 0..51      # 0..51 in a random order
417
418   uniq
419           my @subset = uniq @values
420
421       Since version 1.45.
422
423       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
427           my $count = uniq @values
428
429       In scalar context, returns the number of elements that would have been
430       returned as a list.
431
432       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
437   uniqnum
438           my @subset = uniqnum @values
439
440       Since version 1.44.
441
442       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
446           my $count = uniqnum @values
447
448       In scalar context, returns the number of elements that would have been
449       returned as a list.
450
451       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
458       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
462   uniqstr
463           my @subset = uniqstr @values
464
465       Since version 1.45.
466
467       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
471           my $count = uniqstr @values
472
473       In scalar context, returns the number of elements that would have been
474       returned as a list.
475
476       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
483   head
484           my @values = head $size, @list;
485
486       Returns the first $size elements from @list. If $size is negative,
487       returns all but the last $size elements from @list.
488
489           @result = head 2, qw( foo bar baz );
490           # foo, bar
491
492           @result = head -2, qw( foo bar baz );
493           # foo
494
495   tail
496           my @values = tail $size, @list;
497
498       Returns the last $size elements from @list. If $size is negative,
499       returns all but the first $size elements from @list.
500
501           @result = tail 2, qw( foo bar baz );
502           # bar, baz
503
504           @result = tail -2, qw( foo bar baz );
505           # baz
506

KNOWN BUGS

508   RT #95409
509       <https://rt.cpan.org/Ticket/Display.html?id=95409>
510
511       If the block of code given to "pairmap" contains lexical variables that
512       are captured by a returned closure, and the closure is executed after
513       the block has been re-used for the next iteration, these lexicals will
514       not see the correct values. For example:
515
516        my @subs = pairmap {
517           my $var = "$a is $b";
518           sub { print "$var\n" };
519        } one => 1, two => 2, three => 3;
520
521        $_->() for @subs;
522
523       Will incorrectly print
524
525        three is 3
526        three is 3
527        three is 3
528
529       This is due to the performance optimisation of using "MULTICALL" for
530       the code block, which means that fresh SVs do not get allocated for
531       each call to the block. Instead, the same SV is re-assigned for each
532       iteration, and all the closures will share the value seen on the final
533       iteration.
534
535       To work around this bug, surround the code with a second set of braces.
536       This creates an inner block that defeats the "MULTICALL" logic, and
537       does get fresh SVs allocated each time:
538
539        my @subs = pairmap {
540           {
541              my $var = "$a is $b";
542              sub { print "$var\n"; }
543           }
544        } one => 1, two => 2, three => 3;
545
546       This bug only affects closures that are generated by the block but used
547       afterwards. Lexical variables that are only used during the lifetime of
548       the block's execution will take their individual values for each
549       invocation, as normal.
550
551   uniqnum() on oversized bignums
552       Due to the way that "uniqnum()" compares numbers, it cannot distinguish
553       differences between bignums (especially bigints) that are too large to
554       fit in the native platform types. For example,
555
556        my $x = Math::BigInt->new( "1" x 100 );
557        my $y = $x + 1;
558
559        say for uniqnum( $x, $y );
560
561       Will print just the value of $x, believing that $y is a numerically-
562       equivalent value. This bug does not affect "uniqstr()", which will
563       correctly observe that the two values stringify to different strings.
564

SUGGESTED ADDITIONS

566       The following are additions that have been requested, but I have been
567       reluctant to add due to them being very simple to implement in perl
568
569         # How many elements are true
570
571         sub true { scalar grep { $_ } @_ }
572
573         # How many elements are false
574
575         sub false { scalar grep { !$_ } @_ }
576

SEE ALSO

578       Scalar::Util, List::MoreUtils
579
581       Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights
582       reserved.  This program is free software; you can redistribute it
583       and/or modify it under the same terms as Perl itself.
584
585       Recent additions and current maintenance by Paul Evans,
586       <leonerd@leonerd.org.uk>.
587
588
589
590perl v5.28.0                      2018-02-20                     List::Util(3)
Impressum