1List::AllUtils(3) User Contributed Perl Documentation List::AllUtils(3)
2
6 List::AllUtils - Combines List::Util, List::SomeUtils and List::UtilsBy
7 in one bite-sized package
8
10 version 0.19
11
13 use List::AllUtils qw( first any );
14 # _Everything_ from List::Util, List::SomeUtils, and List::UtilsBy
16 use List::AllUtils qw( :all );
17 my @numbers = ( 1, 2, 3, 5, 7 );
19 # or don't import anything
20 return List::AllUtils::first { $_ > 5 } @numbers;
21
23 Are you sick of trying to remember whether a particular helper is
24 defined in List::Util, List::SomeUtils or List::UtilsBy? I sure am. Now
25 you don't have to remember. This module will export all of the
26 functions that either of those three modules defines.
27 Note that all function documentation has been shamelessly copied from
29 List::Util, List::SomeUtils and List::UtilsBy.
30 Which One Wins?
32 Recently, List::Util has started including some of the subs that used
33 to only be in List::SomeUtils. Similarly, List::SomeUtils has some
34 small overlap with List::UtilsBy.
35 "List::AllUtils" use to always favors the subroutine provided by
37 List::Util, List::SomeUtils or List::UtilsBy in that order. However, as
38 of List::Util 1.56, it included some functions, "mesh" and "zip" with
39 the same name as List::SomeUtils functions, but different behavior.
40 So going forward, we will always prefer backwards compatibility. This
42 means that "mesh" and "zip" will always come from List::SomeUtils. If
43 other incompatible functions are added to List::Util, those will also
44 be skipped in favor of the List::SomeUtils version.
45 The docs below come from List::Util 1.56, List::SomeUtils 0.58, and
47 List::UtilsBy 0.11.
48
50 All this module does is load List::Util, List::SomeUtils, and
51 List::UtilsBy, and then re-export everything that they provide. That
52 means that regardless of the documentation below, you will get any
53 subroutine that your installed version provides.
54
56 The following set of functions all apply a given block of code to a
57 list of values.
58 reduce
60 $result = reduce { BLOCK } @list
61 Reduces @list by calling "BLOCK" in a scalar context multiple times,
63 setting $a and $b each time. The first call will be with $a and $b set
64 to the first two elements of the list, subsequent calls will be done by
65 setting $a to the result of the previous call and $b to the next
66 element in the list.
67 Returns the result of the last call to the "BLOCK". If @list is empty
69 then "undef" is returned. If @list only contains one element then that
70 element is returned and "BLOCK" is not executed.
71 The following examples all demonstrate how "reduce" could be used to
73 implement the other list-reduction functions in this module. (They are
74 not in fact implemented like this, but instead in a more efficient
75 manner in individual C functions).
76 $foo = reduce { defined($a) ? $a :
78 $code->(local $_ = $b) ? $b :
79 undef } undef, @list # first
80 $foo = reduce { $a > $b ? $a : $b } 1..10 # max
82 $foo = reduce { $a gt $b ? $a : $b } 'A'..'Z' # maxstr
83 $foo = reduce { $a < $b ? $a : $b } 1..10 # min
84 $foo = reduce { $a lt $b ? $a : $b } 'aa'..'zz' # minstr
85 $foo = reduce { $a + $b } 1 .. 10 # sum
86 $foo = reduce { $a . $b } @bar # concat
87 $foo = reduce { $a || $code->(local $_ = $b) } 0, @bar # any
89 $foo = reduce { $a && $code->(local $_ = $b) } 1, @bar # all
90 $foo = reduce { $a && !$code->(local $_ = $b) } 1, @bar # none
91 $foo = reduce { $a || !$code->(local $_ = $b) } 0, @bar # notall
92 # Note that these implementations do not fully short-circuit
93 If your algorithm requires that "reduce" produce an identity value,
95 then make sure that you always pass that identity value as the first
96 argument to prevent "undef" being returned
97 $foo = reduce { $a + $b } 0, @values; # sum with 0 identity value
99 The above example code blocks also suggest how to use "reduce" to build
101 a more efficient combined version of one of these basic functions and a
102 "map" block. For example, to find the total length of all the strings
103 in a list, we could use
104 $total = sum map { length } @strings;
106 However, this produces a list of temporary integer values as long as
108 the original list of strings, only to reduce it down to a single value
109 again. We can compute the same result more efficiently by using
110 "reduce" with a code block that accumulates lengths by writing this
111 instead as:
112 $total = reduce { $a + length $b } 0, @strings
114 The other scalar-returning list reduction functions are all
116 specialisations of this generic idea.
117 reductions
119 @results = reductions { BLOCK } @list
120 Since version 1.54.
122 Similar to "reduce" except that it also returns the intermediate values
124 along with the final result. As before, $a is set to the first element
125 of the given list, and the "BLOCK" is then called once for remaining
126 item in the list set into $b, with the result being captured for return
127 as well as becoming the new value for $a.
128 The returned list will begin with the initial value for $a, followed by
130 each return value from the block in order. The final value of the
131 result will be identical to what the "reduce" function would have
132 returned given the same block and list.
133 reduce { "$a-$b" } "a".."d" # "a-b-c-d"
135 reductions { "$a-$b" } "a".."d" # "a", "a-b", "a-b-c", "a-b-c-d"
136 any
138 my $bool = any { BLOCK } @list;
139 Since version 1.33.
141 Similar to "grep" in that it evaluates "BLOCK" setting $_ to each
143 element of @list in turn. "any" returns true if any element makes the
144 "BLOCK" return a true value. If "BLOCK" never returns true or @list was
145 empty then it returns false.
146 Many cases of using "grep" in a conditional can be written using "any"
148 instead, as it can short-circuit after the first true result.
149 if( any { length > 10 } @strings ) {
151 # at least one string has more than 10 characters
152 }
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 all
158 my $bool = all { BLOCK } @list;
159 Since version 1.33.
161 Similar to "any", except that it requires all elements of the @list to
163 make the "BLOCK" return true. If any element returns false, then it
164 returns false. If the "BLOCK" never returns false or the @list was
165 empty then it returns true.
166 Note: Due to XS issues the block passed may be able to access the outer
168 @_ directly. This is not intentional and will break under debugger.
169 none
171 notall
172 my $bool = none { BLOCK } @list;
173 my $bool = notall { BLOCK } @list;
175 Since version 1.33.
177 Similar to "any" and "all", but with the return sense inverted. "none"
179 returns true only if no value in the @list causes the "BLOCK" to return
180 true, and "notall" returns true only if not all of the values do.
181 Note: Due to XS issues the block passed may be able to access the outer
183 @_ directly. This is not intentional and will break under debugger.
184 first
186 my $val = first { BLOCK } @list;
187 Similar to "grep" in that it evaluates "BLOCK" setting $_ to each
189 element of @list in turn. "first" returns the first element where the
190 result from "BLOCK" is a true value. If "BLOCK" never returns true or
191 @list was empty then "undef" is returned.
192 $foo = first { defined($_) } @list # first defined value in @list
194 $foo = first { $_ > $value } @list # first value in @list which
195 # is greater than $value
196 max
198 my $num = max @list;
199 Returns the entry in the list with the highest numerical value. If the
201 list is empty then "undef" is returned.
202 $foo = max 1..10 # 10
204 $foo = max 3,9,12 # 12
205 $foo = max @bar, @baz # whatever
206 maxstr
208 my $str = maxstr @list;
209 Similar to "max", but treats all the entries in the list as strings and
211 returns the highest string as defined by the "gt" operator. If the list
212 is empty then "undef" is returned.
213 $foo = maxstr 'A'..'Z' # 'Z'
215 $foo = maxstr "hello","world" # "world"
216 $foo = maxstr @bar, @baz # whatever
217 min
219 my $num = min @list;
220 Similar to "max" but returns the entry in the list with the lowest
222 numerical value. If the list is empty then "undef" is returned.
223 $foo = min 1..10 # 1
225 $foo = min 3,9,12 # 3
226 $foo = min @bar, @baz # whatever
227 minstr
229 my $str = minstr @list;
230 Similar to "min", but treats all the entries in the list as strings and
232 returns the lowest string as defined by the "lt" operator. If the list
233 is empty then "undef" is returned.
234 $foo = minstr 'A'..'Z' # 'A'
236 $foo = minstr "hello","world" # "hello"
237 $foo = minstr @bar, @baz # whatever
238 product
240 my $num = product @list;
241 Since version 1.35.
243 Returns the numerical product of all the elements in @list. If @list is
245 empty then 1 is returned.
246 $foo = product 1..10 # 3628800
248 $foo = product 3,9,12 # 324
249 sum
251 my $num_or_undef = sum @list;
252 Returns the numerical sum of all the elements in @list. For backwards
254 compatibility, if @list is empty then "undef" is returned.
255 $foo = sum 1..10 # 55
257 $foo = sum 3,9,12 # 24
258 $foo = sum @bar, @baz # whatever
259 sum0
261 my $num = sum0 @list;
262 Since version 1.26.
264 Similar to "sum", except this returns 0 when given an empty list,
266 rather than "undef".
267
269 The following set of functions, all inspired by List::Pairwise, consume
270 an even-sized list of pairs. The pairs may be key/value associations
271 from a hash, or just a list of values. The functions will all preserve
272 the original ordering of the pairs, and will not be confused by
273 multiple pairs having the same "key" value - nor even do they require
274 that the first of each pair be a plain string.
275 NOTE: At the time of writing, the following "pair*" functions that take
277 a block do not modify the value of $_ within the block, and instead
278 operate using the $a and $b globals instead. This has turned out to be
279 a poor design, as it precludes the ability to provide a "pairsort"
280 function. Better would be to pass pair-like objects as 2-element array
281 references in $_, in a style similar to the return value of the "pairs"
282 function. At some future version this behaviour may be added.
283 Until then, users are alerted NOT to rely on the value of $_ remaining
285 unmodified between the outside and the inside of the control block. In
286 particular, the following example is UNSAFE:
287 my @kvlist = ...
289 foreach (qw( some keys here )) {
291 my @items = pairgrep { $a eq $_ } @kvlist;
292 ...
293 }
294 Instead, write this using a lexical variable:
296 foreach my $key (qw( some keys here )) {
298 my @items = pairgrep { $a eq $key } @kvlist;
299 ...
300 }
301 pairs
303 my @pairs = pairs @kvlist;
304 Since version 1.29.
306 A convenient shortcut to operating on even-sized lists of pairs, this
308 function returns a list of "ARRAY" references, each containing two
309 items from the given list. It is a more efficient version of
310 @pairs = pairmap { [ $a, $b ] } @kvlist
312 It is most convenient to use in a "foreach" loop, for example:
314 foreach my $pair ( pairs @kvlist ) {
316 my ( $key, $value ) = @$pair;
317 ...
318 }
319 Since version 1.39 these "ARRAY" references are blessed objects,
321 recognising the two methods "key" and "value". The following code is
322 equivalent:
323 foreach my $pair ( pairs @kvlist ) {
325 my $key = $pair->key;
326 my $value = $pair->value;
327 ...
328 }
329 Since version 1.51 they also have a "TO_JSON" method to ease
331 serialisation.
332 unpairs
334 my @kvlist = unpairs @pairs
335 Since version 1.42.
337 The inverse function to "pairs"; this function takes a list of "ARRAY"
339 references containing two elements each, and returns a flattened list
340 of the two values from each of the pairs, in order. This is notionally
341 equivalent to
342 my @kvlist = map { @{$_}[0,1] } @pairs
344 except that it is implemented more efficiently internally.
346 Specifically, for any input item it will extract exactly two values for
347 the output list; using "undef" if the input array references are short.
348 Between "pairs" and "unpairs", a higher-order list function can be used
350 to operate on the pairs as single scalars; such as the following near-
351 equivalents of the other "pair*" higher-order functions:
352 @kvlist = unpairs grep { FUNC } pairs @kvlist
354 # Like pairgrep, but takes $_ instead of $a and $b
355 @kvlist = unpairs map { FUNC } pairs @kvlist
357 # Like pairmap, but takes $_ instead of $a and $b
358 Note however that these versions will not behave as nicely in scalar
360 context.
361 Finally, this technique can be used to implement a sort on a keyvalue
363 pair list; e.g.:
364 @kvlist = unpairs sort { $a->key cmp $b->key } pairs @kvlist
366 pairkeys
368 my @keys = pairkeys @kvlist;
369 Since version 1.29.
371 A convenient shortcut to operating on even-sized lists of pairs, this
373 function returns a list of the the first values of each of the pairs in
374 the given list. It is a more efficient version of
375 @keys = pairmap { $a } @kvlist
377 pairvalues
379 my @values = pairvalues @kvlist;
380 Since version 1.29.
382 A convenient shortcut to operating on even-sized lists of pairs, this
384 function returns a list of the the second values of each of the pairs
385 in the given list. It is a more efficient version of
386 @values = pairmap { $b } @kvlist
388 pairgrep
390 my @kvlist = pairgrep { BLOCK } @kvlist;
391 my $count = pairgrep { BLOCK } @kvlist;
393 Since version 1.29.
395 Similar to perl's "grep" keyword, but interprets the given list as an
397 even-sized list of pairs. It invokes the "BLOCK" multiple times, in
398 scalar context, with $a and $b set to successive pairs of values from
399 the @kvlist.
400 Returns an even-sized list of those pairs for which the "BLOCK"
402 returned true in list context, or the count of the number of pairs in
403 scalar context. (Note, therefore, in scalar context that it returns a
404 number half the size of the count of items it would have returned in
405 list context).
406 @subset = pairgrep { $a =~ m/^[[:upper:]]+$/ } @kvlist
408 As with "grep" aliasing $_ to list elements, "pairgrep" aliases $a and
410 $b to elements of the given list. Any modifications of it by the code
411 block will be visible to the caller.
412 pairfirst
414 my ( $key, $val ) = pairfirst { BLOCK } @kvlist;
415 my $found = pairfirst { BLOCK } @kvlist;
417 Since version 1.30.
419 Similar to the "first" function, but interprets the given list as an
421 even-sized list of pairs. It invokes the "BLOCK" multiple times, in
422 scalar context, with $a and $b set to successive pairs of values from
423 the @kvlist.
424 Returns the first pair of values from the list for which the "BLOCK"
426 returned true in list context, or an empty list of no such pair was
427 found. In scalar context it returns a simple boolean value, rather than
428 either the key or the value found.
429 ( $key, $value ) = pairfirst { $a =~ m/^[[:upper:]]+$/ } @kvlist
431 As with "grep" aliasing $_ to list elements, "pairfirst" aliases $a and
433 $b to elements of the given list. Any modifications of it by the code
434 block will be visible to the caller.
435 pairmap
437 my @list = pairmap { BLOCK } @kvlist;
438 my $count = pairmap { BLOCK } @kvlist;
440 Since version 1.29.
442 Similar to perl's "map" keyword, but interprets the given list as an
444 even-sized list of pairs. It invokes the "BLOCK" multiple times, in
445 list context, with $a and $b set to successive pairs of values from the
446 @kvlist.
447 Returns the concatenation of all the values returned by the "BLOCK" in
449 list context, or the count of the number of items that would have been
450 returned in scalar context.
451 @result = pairmap { "The key $a has value $b" } @kvlist
453 As with "map" aliasing $_ to list elements, "pairmap" aliases $a and $b
455 to elements of the given list. Any modifications of it by the code
456 block will be visible to the caller.
457 See "KNOWN BUGS" for a known-bug with "pairmap", and a workaround.
459
461 shuffle
462 my @values = shuffle @values;
463 Returns the values of the input in a random order
465 @cards = shuffle 0..51 # 0..51 in a random order
467 This function is affected by the $RAND variable.
469 sample
471 my @items = sample $count, @values
472 Since version 1.54.
474 Randomly select the given number of elements from the input list. Any
476 given position in the input list will be selected at most once.
477 If there are fewer than $count items in the list then the function will
479 return once all of them have been randomly selected; effectively the
480 function behaves similarly to "shuffle".
481 This function is affected by the $RAND variable.
483 uniq
485 my @subset = uniq @values
486 Since version 1.45.
488 Filters a list of values to remove subsequent duplicates, as judged by
490 a DWIM-ish string equality or "undef" test. Preserves the order of
491 unique elements, and retains the first value of any duplicate set.
492 my $count = uniq @values
494 In scalar context, returns the number of elements that would have been
496 returned as a list.
497 The "undef" value is treated by this function as distinct from the
499 empty string, and no warning will be produced. It is left as-is in the
500 returned list. Subsequent "undef" values are still considered identical
501 to the first, and will be removed.
502 uniqint
504 my @subset = uniqint @values
505 Since version 1.55.
507 Filters a list of values to remove subsequent duplicates, as judged by
509 an integer numerical equality test. Preserves the order of unique
510 elements, and retains the first value of any duplicate set. Values in
511 the returned list will be coerced into integers.
512 my $count = uniqint @values
514 In scalar context, returns the number of elements that would have been
516 returned as a list.
517 Note that "undef" is treated much as other numerical operations treat
519 it; it compares equal to zero but additionally produces a warning if
520 such warnings are enabled ("use warnings 'uninitialized';"). In
521 addition, an "undef" in the returned list is coerced into a numerical
522 zero, so that the entire list of values returned by "uniqint" are well-
523 behaved as integers.
524 uniqnum
526 my @subset = uniqnum @values
527 Since version 1.44.
529 Filters a list of values to remove subsequent duplicates, as judged by
531 a numerical equality test. Preserves the order of unique elements, and
532 retains the first value of any duplicate set.
533 my $count = uniqnum @values
535 In scalar context, returns the number of elements that would have been
537 returned as a list.
538 Note that "undef" is treated much as other numerical operations treat
540 it; it compares equal to zero but additionally produces a warning if
541 such warnings are enabled ("use warnings 'uninitialized';"). In
542 addition, an "undef" in the returned list is coerced into a numerical
543 zero, so that the entire list of values returned by "uniqnum" are well-
544 behaved as numbers.
545 Note also that multiple IEEE "NaN" values are treated as duplicates of
547 each other, regardless of any differences in their payloads, and
548 despite the fact that "0+'NaN' == 0+'NaN'" yields false.
549 uniqstr
551 my @subset = uniqstr @values
552 Since version 1.45.
554 Filters a list of values to remove subsequent duplicates, as judged by
556 a string equality test. Preserves the order of unique elements, and
557 retains the first value of any duplicate set.
558 my $count = uniqstr @values
560 In scalar context, returns the number of elements that would have been
562 returned as a list.
563 Note that "undef" is treated much as other string operations treat it;
565 it compares equal to the empty string but additionally produces a
566 warning if such warnings are enabled ("use warnings 'uninitialized';").
567 In addition, an "undef" in the returned list is coerced into an empty
568 string, so that the entire list of values returned by "uniqstr" are
569 well-behaved as strings.
570 head
572 my @values = head $size, @list;
573 Since version 1.50.
575 Returns the first $size elements from @list. If $size is negative,
577 returns all but the last $size elements from @list.
578 @result = head 2, qw( foo bar baz );
580 # foo, bar
581 @result = head -2, qw( foo bar baz );
583 # foo
584 tail
586 my @values = tail $size, @list;
587 Since version 1.50.
589 Returns the last $size elements from @list. If $size is negative,
591 returns all but the first $size elements from @list.
592 @result = tail 2, qw( foo bar baz );
594 # bar, baz
595 @result = tail -2, qw( foo bar baz );
597 # baz
598
600 Junctions
601 Treatment of an empty list
602 There are two schools of thought for how to evaluate a junction on an
604 empty list:
605 • Reduction to an identity (boolean)
607 • Result is undefined (three-valued)
609 In the first case, the result of the junction applied to the empty list
611 is determined by a mathematical reduction to an identity depending on
612 whether the underlying comparison is "or" or "and". Conceptually:
613 "any are true" "all are true"
615 -------------- --------------
616 2 elements: A || B || 0 A && B && 1
617 1 element: A || 0 A && 1
618 0 elements: 0 1
619 In the second case, three-value logic is desired, in which a junction
621 applied to an empty list returns "undef" rather than true or false
622 Junctions with a "_u" suffix implement three-valued logic. Those
624 without are boolean.
625 all BLOCK LIST
627 all_u BLOCK LIST
629 Returns a true value if all items in LIST meet the criterion given
631 through BLOCK. Sets $_ for each item in LIST in turn:
632 print "All values are non-negative"
634 if all { $_ >= 0 } ($x, $y, $z);
635 For an empty LIST, "all" returns true (i.e. no values failed the
637 condition) and "all_u" returns "undef".
638 Thus, all_u(@list) is equivalent to "@list ? all(@list) : undef".
640 Note: because Perl treats "undef" as false, you must check the return
642 value of "all_u" with "defined" or you will get the opposite result of
643 what you expect.
644 any BLOCK LIST
646 any_u BLOCK LIST
648 Returns a true value if any item in LIST meets the criterion given
650 through BLOCK. Sets $_ for each item in LIST in turn:
651 print "At least one non-negative value"
653 if any { $_ >= 0 } ($x, $y, $z);
654 For an empty LIST, "any" returns false and "any_u" returns "undef".
656 Thus, any_u(@list) is equivalent to "@list ? any(@list) : undef".
658 none BLOCK LIST
660 none_u BLOCK LIST
662 Logically the negation of "any". Returns a true value if no item in
664 LIST meets the criterion given through BLOCK. Sets $_ for each item in
665 LIST in turn:
666 print "No non-negative values"
668 if none { $_ >= 0 } ($x, $y, $z);
669 For an empty LIST, "none" returns true (i.e. no values failed the
671 condition) and "none_u" returns "undef".
672 Thus, none_u(@list) is equivalent to "@list ? none(@list) : undef".
674 Note: because Perl treats "undef" as false, you must check the return
676 value of "none_u" with "defined" or you will get the opposite result of
677 what you expect.
678 notall BLOCK LIST
680 notall_u BLOCK LIST
682 Logically the negation of "all". Returns a true value if not all items
684 in LIST meet the criterion given through BLOCK. Sets $_ for each item
685 in LIST in turn:
686 print "Not all values are non-negative"
688 if notall { $_ >= 0 } ($x, $y, $z);
689 For an empty LIST, "notall" returns false and "notall_u" returns
691 "undef".
692 Thus, notall_u(@list) is equivalent to "@list ? notall(@list) : undef".
694 one BLOCK LIST
696 one_u BLOCK LIST
698 Returns a true value if precisely one item in LIST meets the criterion
700 given through BLOCK. Sets $_ for each item in LIST in turn:
701 print "Precisely one value defined"
703 if one { defined($_) } @list;
704 Returns false otherwise.
706 For an empty LIST, "one" returns false and "one_u" returns "undef".
708 The expression "one BLOCK LIST" is almost equivalent to "1 == true
710 BLOCK LIST", except for short-cutting. Evaluation of BLOCK will
711 immediately stop at the second true value.
712 Transformation
714 apply BLOCK LIST
715 Makes a copy of the list and then passes each element from the copy to
717 the BLOCK. Any changes or assignments to $_ in the BLOCK will only
718 affect the elements of the new list. However, if $_ is a reference then
719 changes to the referenced value will be seen in both the original and
720 new list.
721 This function is similar to "map" but will not modify the elements of
723 the input list:
724 my @list = (1 .. 4);
726 my @mult = apply { $_ *= 2 } @list;
727 print "\@list = @list\n";
728 print "\@mult = @mult\n";
729 __END__
730 @list = 1 2 3 4
731 @mult = 2 4 6 8
732 Think of it as syntactic sugar for
734 for (my @mult = @list) { $_ *= 2 }
736 Note that you must alter $_ directly inside BLOCK in order for changes
738 to make effect. New value returned from the BLOCK are ignored:
739 # @new is identical to @list.
741 my @new = apply { $_ * 2 } @list;
742 # @new is different from @list
744 my @new = apply { $_ =* 2 } @list;
745 insert_after BLOCK VALUE LIST
747 Inserts VALUE after the first item in LIST for which the criterion in
749 BLOCK is true. Sets $_ for each item in LIST in turn.
750 my @list = qw/This is a list/;
752 insert_after { $_ eq "a" } "longer" => @list;
753 print "@list";
754 __END__
755 This is a longer list
756 insert_after_string STRING VALUE LIST
758 Inserts VALUE after the first item in LIST which is equal to STRING.
760 my @list = qw/This is a list/;
762 insert_after_string "a", "longer" => @list;
763 print "@list";
764 __END__
765 This is a longer list
766 pairwise BLOCK ARRAY1 ARRAY2
768 Evaluates BLOCK for each pair of elements in ARRAY1 and ARRAY2 and
770 returns a new list consisting of BLOCK's return values. The two
771 elements are set to $a and $b. Note that those two are aliases to the
772 original value so changing them will modify the input arrays.
773 @a = (1 .. 5);
775 @b = (11 .. 15);
776 @x = pairwise { $a + $b } @a, @b; # returns 12, 14, 16, 18, 20
777 # mesh with pairwise
779 @a = qw/a b c/;
780 @b = qw/1 2 3/;
781 @x = pairwise { ($a, $b) } @a, @b; # returns a, 1, b, 2, c, 3
782 mesh ARRAY1 ARRAY2 [ ARRAY3 ... ]
784 zip ARRAY1 ARRAY2 [ ARRAY3 ... ]
786 Returns a list consisting of the first elements of each array, then the
788 second, then the third, etc, until all arrays are exhausted.
789 Examples:
791 @x = qw/a b c d/;
793 @y = qw/1 2 3 4/;
794 @z = mesh @x, @y; # returns a, 1, b, 2, c, 3, d, 4
795 @a = ('x');
797 @b = ('1', '2');
798 @c = qw/zip zap zot/;
799 @d = mesh @a, @b, @c; # x, 1, zip, undef, 2, zap, undef, undef, zot
800 "zip" is an alias for "mesh".
802 uniq LIST
804 distinct LIST
806 Returns a new list by stripping duplicate values in LIST by comparing
808 the values as hash keys, except that undef is considered separate from
809 ''. The order of elements in the returned list is the same as in LIST.
810 In scalar context, returns the number of unique elements in LIST.
811 my @x = uniq 1, 1, 2, 2, 3, 5, 3, 4; # returns 1 2 3 5 4
813 my $x = uniq 1, 1, 2, 2, 3, 5, 3, 4; # returns 5
814 # returns "Mike", "Michael", "Richard", "Rick"
815 my @n = distinct "Mike", "Michael", "Richard", "Rick", "Michael", "Rick"
816 # returns '', undef, 'S1', A5'
817 my @s = distinct '', undef, 'S1', 'A5'
818 # returns '', undef, 'S1', A5'
819 my @w = uniq undef, '', 'S1', 'A5'
820 "distinct" is an alias for "uniq".
822 RT#49800 can be used to give feedback about this behavior.
824 singleton
826 Returns a new list by stripping values in LIST occurring more than once
828 by comparing the values as hash keys, except that undef is considered
829 separate from ''. The order of elements in the returned list is the
830 same as in LIST. In scalar context, returns the number of elements
831 occurring only once in LIST.
832 my @x = singleton 1,1,2,2,3,4,5 # returns 3 4 5
834 Partitioning
836 after BLOCK LIST
837 Returns a list of the values of LIST after (and not including) the
839 point where BLOCK returns a true value. Sets $_ for each element in
840 LIST in turn.
841 @x = after { $_ % 5 == 0 } (1..9); # returns 6, 7, 8, 9
843 after_incl BLOCK LIST
845 Same as "after" but also includes the element for which BLOCK is true.
847 before BLOCK LIST
849 Returns a list of values of LIST up to (and not including) the point
851 where BLOCK returns a true value. Sets $_ for each element in LIST in
852 turn.
853 before_incl BLOCK LIST
855 Same as "before" but also includes the element for which BLOCK is true.
857 part BLOCK LIST
859 Partitions LIST based on the return value of BLOCK which denotes into
861 which partition the current value is put.
862 Returns a list of the partitions thusly created. Each partition created
864 is a reference to an array.
865 my $i = 0;
867 my @part = part { $i++ % 2 } 1 .. 8; # returns [1, 3, 5, 7], [2, 4, 6, 8]
868 You can have a sparse list of partitions as well where non-set
870 partitions will be undef:
871 my @part = part { 2 } 1 .. 10; # returns undef, undef, [ 1 .. 10 ]
873 Be careful with negative values, though:
875 my @part = part { -1 } 1 .. 10;
877 __END__
878 Modification of non-creatable array value attempted, subscript -1 ...
879 Negative values are only ok when they refer to a partition previously
881 created:
882 my @idx = ( 0, 1, -1 );
884 my $i = 0;
885 my @part = part { $idx[$i++ % 3] } 1 .. 8; # [1, 4, 7], [2, 3, 5, 6, 8]
886 Iteration
888 each_array ARRAY1 ARRAY2 ...
889 Creates an array iterator to return the elements of the list of arrays
891 ARRAY1, ARRAY2 throughout ARRAYn in turn. That is, the first time it
892 is called, it returns the first element of each array. The next time,
893 it returns the second elements. And so on, until all elements are
894 exhausted.
895 This is useful for looping over more than one array at once:
897 my $ea = each_array(@a, @b, @c);
899 while ( my ($a, $b, $c) = $ea->() ) { .... }
900 The iterator returns the empty list when it reached the end of all
902 arrays.
903 If the iterator is passed an argument of '"index"', then it returns the
905 index of the last fetched set of values, as a scalar.
906 each_arrayref LIST
908 Like each_array, but the arguments are references to arrays, not the
910 plain arrays.
911 natatime EXPR, LIST
913 Creates an array iterator, for looping over an array in chunks of $n
915 items at a time. (n at a time, get it?). An example is probably a
916 better explanation than I could give in words.
917 Example:
919 my @x = ('a' .. 'g');
921 my $it = natatime 3, @x;
922 while (my @vals = $it->())
923 {
924 print "@vals\n";
925 }
926 This prints
928 a b c
930 d e f
931 g
932 Searching
934 bsearch BLOCK LIST
935 Performs a binary search on LIST which must be a sorted list of values.
937 BLOCK must return a negative value if the current element (stored in
938 $_) is smaller, a positive value if it is bigger and zero if it
939 matches.
940 Returns a boolean value in scalar context. In list context, it returns
942 the element if it was found, otherwise the empty list.
943 bsearchidx BLOCK LIST
945 bsearch_index BLOCK LIST
947 Performs a binary search on LIST which must be a sorted list of values.
949 BLOCK must return a negative value if the current element (stored in
950 $_) is smaller, a positive value if it is bigger and zero if it
951 matches.
952 Returns the index of found element, otherwise -1.
954 "bsearch_index" is an alias for "bsearchidx".
956 firstval BLOCK LIST
958 first_value BLOCK LIST
960 Returns the first element in LIST for which BLOCK evaluates to true.
962 Each element of LIST is set to $_ in turn. Returns "undef" if no such
963 element has been found.
964 "first_value" is an alias for "firstval".
966 onlyval BLOCK LIST
968 only_value BLOCK LIST
970 Returns the only element in LIST for which BLOCK evaluates to true.
972 Sets $_ for each item in LIST in turn. Returns "undef" if no such
973 element has been found.
974 "only_value" is an alias for "onlyval".
976 lastval BLOCK LIST
978 last_value BLOCK LIST
980 Returns the last value in LIST for which BLOCK evaluates to true. Each
982 element of LIST is set to $_ in turn. Returns "undef" if no such
983 element has been found.
984 "last_value" is an alias for "lastval".
986 firstres BLOCK LIST
988 first_result BLOCK LIST
990 Returns the result of BLOCK for the first element in LIST for which
992 BLOCK evaluates to true. Each element of LIST is set to $_ in turn.
993 Returns "undef" if no such element has been found.
994 "first_result" is an alias for "firstres".
996 onlyres BLOCK LIST
998 only_result BLOCK LIST
1000 Returns the result of BLOCK for the first element in LIST for which
1002 BLOCK evaluates to true. Sets $_ for each item in LIST in turn. Returns
1003 "undef" if no such element has been found.
1004 "only_result" is an alias for "onlyres".
1006 lastres BLOCK LIST
1008 last_result BLOCK LIST
1010 Returns the result of BLOCK for the last element in LIST for which
1012 BLOCK evaluates to true. Each element of LIST is set to $_ in turn.
1013 Returns "undef" if no such element has been found.
1014 "last_result" is an alias for "lastres".
1016 indexes BLOCK LIST
1018 Evaluates BLOCK for each element in LIST (assigned to $_) and returns a
1020 list of the indices of those elements for which BLOCK returned a true
1021 value. This is just like "grep" only that it returns indices instead of
1022 values:
1023 @x = indexes { $_ % 2 == 0 } (1..10); # returns 1, 3, 5, 7, 9
1025 firstidx BLOCK LIST
1027 first_index BLOCK LIST
1029 Returns the index of the first element in LIST for which the criterion
1031 in BLOCK is true. Sets $_ for each item in LIST in turn:
1032 my @list = (1, 4, 3, 2, 4, 6);
1034 printf "item with index %i in list is 4", firstidx { $_ == 4 } @list;
1035 __END__
1036 item with index 1 in list is 4
1037 Returns -1 if no such item could be found.
1039 "first_index" is an alias for "firstidx".
1041 onlyidx BLOCK LIST
1043 only_index BLOCK LIST
1045 Returns the index of the only element in LIST for which the criterion
1047 in BLOCK is true. Sets $_ for each item in LIST in turn:
1048 my @list = (1, 3, 4, 3, 2, 4);
1050 printf "uniqe index of item 2 in list is %i", onlyidx { $_ == 2 } @list;
1051 __END__
1052 unique index of item 2 in list is 4
1053 Returns -1 if either no such item or more than one of these has been
1055 found.
1056 "only_index" is an alias for "onlyidx".
1058 lastidx BLOCK LIST
1060 last_index BLOCK LIST
1062 Returns the index of the last element in LIST for which the criterion
1064 in BLOCK is true. Sets $_ for each item in LIST in turn:
1065 my @list = (1, 4, 3, 2, 4, 6);
1067 printf "item with index %i in list is 4", lastidx { $_ == 4 } @list;
1068 __END__
1069 item with index 4 in list is 4
1070 Returns -1 if no such item could be found.
1072 "last_index" is an alias for "lastidx".
1074 Sorting
1076 sort_by BLOCK LIST
1077 Returns the list of values sorted according to the string values
1079 returned by the KEYFUNC block or function. A typical use of this may be
1080 to sort objects according to the string value of some accessor, such as
1081 sort_by { $_->name } @people
1083 The key function is called in scalar context, being passed each value
1085 in turn as both $_ and the only argument in the parameters, @_. The
1086 values are then sorted according to string comparisons on the values
1087 returned. This is equivalent to
1088 sort { $a->name cmp $b->name } @people
1090 except that it guarantees the name accessor will be executed only once
1092 per value. One interesting use-case is to sort strings which may have
1093 numbers embedded in them "naturally", rather than lexically.
1094 sort_by { s/(\d+)/sprintf "%09d", $1/eg; $_ } @strings
1096 This sorts strings by generating sort keys which zero-pad the embedded
1098 numbers to some level (9 digits in this case), helping to ensure the
1099 lexical sort puts them in the correct order.
1100 nsort_by BLOCK LIST
1102 Similar to sort_by but compares its key values numerically.
1104 Counting and calculation
1106 true BLOCK LIST
1107 Counts the number of elements in LIST for which the criterion in BLOCK
1109 is true. Sets $_ for each item in LIST in turn:
1110 printf "%i item(s) are defined", true { defined($_) } @list;
1112 false BLOCK LIST
1114 Counts the number of elements in LIST for which the criterion in BLOCK
1116 is false. Sets $_ for each item in LIST in turn:
1117 printf "%i item(s) are not defined", false { defined($_) } @list;
1119 minmax LIST
1121 Calculates the minimum and maximum of LIST and returns a two element
1123 list with the first element being the minimum and the second the
1124 maximum. Returns the empty list if LIST was empty.
1125 The "minmax" algorithm differs from a naive iteration over the list
1127 where each element is compared to two values being the so far
1128 calculated min and max value in that it only requires 3n/2 - 2
1129 comparisons. Thus it is the most efficient possible algorithm.
1130 However, the Perl implementation of it has some overhead simply due to
1132 the fact that there are more lines of Perl code involved. Therefore,
1133 LIST needs to be fairly big in order for "minmax" to win over a naive
1134 implementation. This limitation does not apply to the XS version.
1135 mode LIST
1137 Calculates the most common items in the list and returns them as a
1139 list. This is effectively done by string comparisons, so references
1140 will be stringified. If they implement string overloading, this will be
1141 used.
1142 If more than one item appears the same number of times in the list, all
1144 such items will be returned. For example, the mode of a unique list is
1145 the list itself.
1146 This function returns a list in list context. In scalar context it
1148 returns a count indicating the number of modes in the list.
1149
1151 All functions added since version 0.04 unless otherwise stated, as the
1152 original names for earlier versions were renamed.
1153 sort_by
1155 @vals = sort_by { KEYFUNC } @vals
1156 Returns the list of values sorted according to the string values
1158 returned by the "KEYFUNC" block or function. A typical use of this may
1159 be to sort objects according to the string value of some accessor, such
1160 as
1161 sort_by { $_->name } @people
1163 The key function is called in scalar context, being passed each value
1165 in turn as both $_ and the only argument in the parameters, @_. The
1166 values are then sorted according to string comparisons on the values
1167 returned.
1168 This is equivalent to
1170 sort { $a->name cmp $b->name } @people
1172 except that it guarantees the "name" accessor will be executed only
1174 once per value.
1175 One interesting use-case is to sort strings which may have numbers
1177 embedded in them "naturally", rather than lexically.
1178 sort_by { s/(\d+)/sprintf "%09d", $1/eg; $_ } @strings
1180 This sorts strings by generating sort keys which zero-pad the embedded
1182 numbers to some level (9 digits in this case), helping to ensure the
1183 lexical sort puts them in the correct order.
1184 nsort_by
1186 @vals = nsort_by { KEYFUNC } @vals
1187 Similar to "sort_by" but compares its key values numerically.
1189 rev_sort_by
1191 rev_nsort_by
1192 @vals = rev_sort_by { KEYFUNC } @vals
1193 @vals = rev_nsort_by { KEYFUNC } @vals
1195 Since version 0.06.
1197 Similar to "sort_by" and "nsort_by" but returns the list in the reverse
1199 order. Equivalent to
1200 @vals = reverse sort_by { KEYFUNC } @vals
1202 except that these functions are slightly more efficient because they
1204 avoid the final "reverse" operation.
1205 max_by
1207 $optimal = max_by { KEYFUNC } @vals
1208 @optimal = max_by { KEYFUNC } @vals
1210 Returns the (first) value from @vals that gives the numerically largest
1212 result from the key function.
1213 my $tallest = max_by { $_->height } @people
1215 use File::stat qw( stat );
1217 my $newest = max_by { stat($_)->mtime } @files;
1218 In scalar context, the first maximal value is returned. In list
1220 context, a list of all the maximal values is returned. This may be used
1221 to obtain positions other than the first, if order is significant.
1222 If called on an empty list, an empty list is returned.
1224 For symmetry with the "nsort_by" function, this is also provided under
1226 the name "nmax_by" since it behaves numerically.
1227 min_by
1229 $optimal = min_by { KEYFUNC } @vals
1230 @optimal = min_by { KEYFUNC } @vals
1232 Similar to "max_by" but returns values which give the numerically
1234 smallest result from the key function. Also provided as "nmin_by"
1235 minmax_by
1237 ( $minimal, $maximal ) = minmax_by { KEYFUNC } @vals
1238 Since version 0.11.
1240 Similar to calling both "min_by" and "max_by" with the same key
1242 function on the same list. This version is more efficient than calling
1243 the two other functions individually, as it has less work to perform
1244 overall. In the case of ties, only the first optimal element found in
1245 each case is returned. Also provided as "nminmax_by".
1246 uniq_by
1248 @vals = uniq_by { KEYFUNC } @vals
1249 Returns a list of the subset of values for which the key function block
1251 returns unique values. The first value yielding a particular key is
1252 chosen, subsequent values are rejected.
1253 my @some_fruit = uniq_by { $_->colour } @fruit;
1255 To select instead the last value per key, reverse the input list. If
1257 the order of the results is significant, don't forget to reverse the
1258 result as well:
1259 my @some_fruit = reverse uniq_by { $_->colour } reverse @fruit;
1261 Because the values returned by the key function are used as hash keys,
1263 they ought to either be strings, or at least well-behaved as strings
1264 (such as numbers, or object references which overload stringification
1265 in a suitable manner).
1266 partition_by
1268 %parts = partition_by { KEYFUNC } @vals
1269 Returns a key/value list of ARRAY refs containing all the original
1271 values distributed according to the result of the key function block.
1272 Each value will be an ARRAY ref containing all the values which
1273 returned the string from the key function, in their original order.
1274 my %balls_by_colour = partition_by { $_->colour } @balls;
1276 Because the values returned by the key function are used as hash keys,
1278 they ought to either be strings, or at least well-behaved as strings
1279 (such as numbers, or object references which overload stringification
1280 in a suitable manner).
1281 count_by
1283 %counts = count_by { KEYFUNC } @vals
1284 Since version 0.07.
1286 Returns a key/value list of integers, giving the number of times the
1288 key function block returned the key, for each value in the list.
1289 my %count_of_balls = count_by { $_->colour } @balls;
1291 Because the values returned by the key function are used as hash keys,
1293 they ought to either be strings, or at least well-behaved as strings
1294 (such as numbers, or object references which overload stringification
1295 in a suitable manner).
1296 zip_by
1298 @vals = zip_by { ITEMFUNC } \@arr0, \@arr1, \@arr2,...
1299 Returns a list of each of the values returned by the function block,
1301 when invoked with values from across each each of the given ARRAY
1302 references. Each value in the returned list will be the result of the
1303 function having been invoked with arguments at that position, from
1304 across each of the arrays given.
1305 my @transposition = zip_by { [ @_ ] } @matrix;
1307 my @names = zip_by { "$_[1], $_[0]" } \@firstnames, \@surnames;
1309 print zip_by { "$_[0] => $_[1]\n" } [ keys %hash ], [ values %hash ];
1311 If some of the arrays are shorter than others, the function will behave
1313 as if they had "undef" in the trailing positions. The following two
1314 lines are equivalent:
1315 zip_by { f(@_) } [ 1, 2, 3 ], [ "a", "b" ]
1317 f( 1, "a" ), f( 2, "b" ), f( 3, undef )
1318 The item function is called by "map", so if it returns a list, the
1320 entire list is included in the result. This can be useful for example,
1321 for generating a hash from two separate lists of keys and values
1322 my %nums = zip_by { @_ } [qw( one two three )], [ 1, 2, 3 ];
1324 # %nums = ( one => 1, two => 2, three => 3 )
1325 (A function having this behaviour is sometimes called "zipWith", e.g.
1327 in Haskell, but that name would not fit the naming scheme used by this
1328 module).
1329 unzip_by
1331 $arr0, $arr1, $arr2, ... = unzip_by { ITEMFUNC } @vals
1332 Since version 0.09.
1334 Returns a list of ARRAY references containing the values returned by
1336 the function block, when invoked for each of the values given in the
1337 input list. Each of the returned ARRAY references will contain the
1338 values returned at that corresponding position by the function block.
1339 That is, the first returned ARRAY reference will contain all the values
1340 returned in the first position by the function block, the second will
1341 contain all the values from the second position, and so on.
1342 my ( $firstnames, $lastnames ) = unzip_by { m/^(.*?) (.*)$/ } @names;
1344 If the function returns lists of differing lengths, the result will be
1346 padded with "undef" in the missing elements.
1347 This function is an inverse of "zip_by", if given a corresponding
1349 inverse function.
1350 extract_by
1352 @vals = extract_by { SELECTFUNC } @arr
1353 Since version 0.05.
1355 Removes elements from the referenced array on which the selection
1357 function returns true, and returns a list containing those elements.
1358 This function is similar to "grep", except that it modifies the
1359 referenced array to remove the selected values from it, leaving only
1360 the unselected ones.
1361 my @red_balls = extract_by { $_->color eq "red" } @balls;
1363 # Now there are no red balls in the @balls array
1365 This function modifies a real array, unlike most of the other functions
1367 in this module. Because of this, it requires a real array, not just a
1368 list.
1369 This function is implemented by invoking "splice" on the array, not by
1371 constructing a new list and assigning it. One result of this is that
1372 weak references will not be disturbed.
1373 extract_by { !defined $_ } @refs;
1375 will leave weak references weakened in the @refs array, whereas
1377 @refs = grep { defined $_ } @refs;
1379 will strengthen them all again.
1381 extract_first_by
1383 $val = extract_first_by { SELECTFUNC } @arr
1384 Since version 0.10.
1386 A hybrid between "extract_by" and "List::Util::first". Removes the
1388 first element from the referenced array on which the selection function
1389 returns true, returning it.
1390 As with "extract_by", this function requires a real array and not just
1392 a list, and is also implemented using "splice" so that weak references
1393 are not disturbed.
1394 If this function fails to find a matching element, it will return an
1396 empty list in list context. This allows a caller to distinguish the
1397 case between no matching element, and the first matching element being
1398 "undef".
1399 weighted_shuffle_by
1401 @vals = weighted_shuffle_by { WEIGHTFUNC } @vals
1402 Since version 0.07.
1404 Returns the list of values shuffled into a random order. The
1406 randomisation is not uniform, but weighted by the value returned by the
1407 "WEIGHTFUNC". The probabilty of each item being returned first will be
1408 distributed with the distribution of the weights, and so on recursively
1409 for the remaining items.
1410 bundle_by
1412 @vals = bundle_by { BLOCKFUNC } $number, @vals
1413 Since version 0.07.
1415 Similar to a regular "map" functional, returns a list of the values
1417 returned by "BLOCKFUNC". Values from the input list are given to the
1418 block function in bundles of $number.
1419 If given a list of values whose length does not evenly divide by
1421 $number, the final call will be passed fewer elements than the others.
1422
1424 This module exports nothing by default. You can import functions by
1425 name, or get everything with the ":all" tag.
1426
1428 List::Util, List::SomeUtils and List::UtilsBy, obviously.
1429 Also see "Util::Any", which unifies many more util modules, and also
1431 lets you rename functions as part of the import.
1432
1434 Please report any bugs or feature requests to
1435 "bug-list-allutils@rt.cpan.org", or through the web interface at
1436 <http://rt.cpan.org>. I will be notified, and then you'll
1437 automatically be notified of progress on your bug as I make changes.
1438 Bugs may be submitted at
1440 <https://github.com/houseabsolute/List-AllUtils/issues>.
1441 I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
1443
1445 The source code repository for List-AllUtils can be found at
1446 <https://github.com/houseabsolute/List-AllUtils>.
1447
1449 If you'd like to thank me for the work I've done on this module, please
1450 consider making a "donation" to me via PayPal. I spend a lot of free
1451 time creating free software, and would appreciate any support you'd
1452 care to offer.
1453 Please note that I am not suggesting that you must do this in order for
1455 me to continue working on this particular software. I will continue to
1456 do so, inasmuch as I have in the past, for as long as it interests me.
1457 Similarly, a donation made in this way will probably not make me work
1459 on this software much more, unless I get so many donations that I can
1460 consider working on free software full time (let's all have a chuckle
1461 at that together).
1462 To donate, log into PayPal and send money to autarch@urth.org, or use
1464 the button at <https://www.urth.org/fs-donation.html>.
1465
1467 Dave Rolsky <autarch@urth.org>
1468
1470 • Andy Jack <github@veracity.ca>
1471 • Dave Jacoby <jacoby.david@gmail.com>
1473 • Karen Etheridge <ether@cpan.org>
1475 • Olaf Alders <olaf@wundersolutions.com>
1477 • Ricardo Signes <rjbs@cpan.org>
1479 • Yanick Champoux <yanick@babyl.dyndns.org>
1481
1483 This software is Copyright (c) 2021 by Dave Rolsky.
1484 This is free software, licensed under:
1486 The Artistic License 2.0 (GPL Compatible)
1488 The full text of the license can be found in the LICENSE file included
1490 with this distribution.
1491perl v5.38.0 2023-07-20 List::AllUtils(3)