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) :
694 undef".
695 one BLOCK LIST
697 one_u BLOCK LIST
699 Returns a true value if precisely one item in LIST meets the criterion
701 given through BLOCK. Sets $_ for each item in LIST in turn:
702 print "Precisely one value defined"
704 if one { defined($_) } @list;
705 Returns false otherwise.
707 For an empty LIST, "one" returns false and "one_u" returns "undef".
709 The expression "one BLOCK LIST" is almost equivalent to "1 == true
711 BLOCK LIST", except for short-cutting. Evaluation of BLOCK will
712 immediately stop at the second true value.
713 Transformation
715 apply BLOCK LIST
716 Makes a copy of the list and then passes each element from the copy to
718 the BLOCK. Any changes or assignments to $_ in the BLOCK will only
719 affect the elements of the new list. However, if $_ is a reference then
720 changes to the referenced value will be seen in both the original and
721 new list.
722 This function is similar to "map" but will not modify the elements of
724 the input list:
725 my @list = (1 .. 4);
727 my @mult = apply { $_ *= 2 } @list;
728 print "\@list = @list\n";
729 print "\@mult = @mult\n";
730 __END__
731 @list = 1 2 3 4
732 @mult = 2 4 6 8
733 Think of it as syntactic sugar for
735 for (my @mult = @list) { $_ *= 2 }
737 Note that you must alter $_ directly inside BLOCK in order for changes
739 to make effect. New value returned from the BLOCK are ignored:
740 # @new is identical to @list.
742 my @new = apply { $_ * 2 } @list;
743 # @new is different from @list
745 my @new = apply { $_ =* 2 } @list;
746 insert_after BLOCK VALUE LIST
748 Inserts VALUE after the first item in LIST for which the criterion in
750 BLOCK is true. Sets $_ for each item in LIST in turn.
751 my @list = qw/This is a list/;
753 insert_after { $_ eq "a" } "longer" => @list;
754 print "@list";
755 __END__
756 This is a longer list
757 insert_after_string STRING VALUE LIST
759 Inserts VALUE after the first item in LIST which is equal to STRING.
761 my @list = qw/This is a list/;
763 insert_after_string "a", "longer" => @list;
764 print "@list";
765 __END__
766 This is a longer list
767 pairwise BLOCK ARRAY1 ARRAY2
769 Evaluates BLOCK for each pair of elements in ARRAY1 and ARRAY2 and
771 returns a new list consisting of BLOCK's return values. The two
772 elements are set to $a and $b. Note that those two are aliases to the
773 original value so changing them will modify the input arrays.
774 @a = (1 .. 5);
776 @b = (11 .. 15);
777 @x = pairwise { $a + $b } @a, @b; # returns 12, 14, 16, 18, 20
778 # mesh with pairwise
780 @a = qw/a b c/;
781 @b = qw/1 2 3/;
782 @x = pairwise { ($a, $b) } @a, @b; # returns a, 1, b, 2, c, 3
783 mesh ARRAY1 ARRAY2 [ ARRAY3 ... ]
785 zip ARRAY1 ARRAY2 [ ARRAY3 ... ]
787 Returns a list consisting of the first elements of each array, then the
789 second, then the third, etc, until all arrays are exhausted.
790 Examples:
792 @x = qw/a b c d/;
794 @y = qw/1 2 3 4/;
795 @z = mesh @x, @y; # returns a, 1, b, 2, c, 3, d, 4
796 @a = ('x');
798 @b = ('1', '2');
799 @c = qw/zip zap zot/;
800 @d = mesh @a, @b, @c; # x, 1, zip, undef, 2, zap, undef, undef, zot
801 "zip" is an alias for "mesh".
803 uniq LIST
805 distinct LIST
807 Returns a new list by stripping duplicate values in LIST by comparing
809 the values as hash keys, except that undef is considered separate from
810 ''. The order of elements in the returned list is the same as in LIST.
811 In scalar context, returns the number of unique elements in LIST.
812 my @x = uniq 1, 1, 2, 2, 3, 5, 3, 4; # returns 1 2 3 5 4
814 my $x = uniq 1, 1, 2, 2, 3, 5, 3, 4; # returns 5
815 # returns "Mike", "Michael", "Richard", "Rick"
816 my @n = distinct "Mike", "Michael", "Richard", "Rick", "Michael", "Rick"
817 # returns '', undef, 'S1', A5'
818 my @s = distinct '', undef, 'S1', 'A5'
819 # returns '', undef, 'S1', A5'
820 my @w = uniq undef, '', 'S1', 'A5'
821 "distinct" is an alias for "uniq".
823 RT#49800 can be used to give feedback about this behavior.
825 singleton
827 Returns a new list by stripping values in LIST occurring more than once
829 by comparing the values as hash keys, except that undef is considered
830 separate from ''. The order of elements in the returned list is the
831 same as in LIST. In scalar context, returns the number of elements
832 occurring only once in LIST.
833 my @x = singleton 1,1,2,2,3,4,5 # returns 3 4 5
835 Partitioning
837 after BLOCK LIST
838 Returns a list of the values of LIST after (and not including) the
840 point where BLOCK returns a true value. Sets $_ for each element in
841 LIST in turn.
842 @x = after { $_ % 5 == 0 } (1..9); # returns 6, 7, 8, 9
844 after_incl BLOCK LIST
846 Same as "after" but also includes the element for which BLOCK is true.
848 before BLOCK LIST
850 Returns a list of values of LIST up to (and not including) the point
852 where BLOCK returns a true value. Sets $_ for each element in LIST in
853 turn.
854 before_incl BLOCK LIST
856 Same as "before" but also includes the element for which BLOCK is true.
858 part BLOCK LIST
860 Partitions LIST based on the return value of BLOCK which denotes into
862 which partition the current value is put.
863 Returns a list of the partitions thusly created. Each partition created
865 is a reference to an array.
866 my $i = 0;
868 my @part = part { $i++ % 2 } 1 .. 8; # returns [1, 3, 5, 7], [2, 4, 6, 8]
869 You can have a sparse list of partitions as well where non-set
871 partitions will be undef:
872 my @part = part { 2 } 1 .. 10; # returns undef, undef, [ 1 .. 10 ]
874 Be careful with negative values, though:
876 my @part = part { -1 } 1 .. 10;
878 __END__
879 Modification of non-creatable array value attempted, subscript -1 ...
880 Negative values are only ok when they refer to a partition previously
882 created:
883 my @idx = ( 0, 1, -1 );
885 my $i = 0;
886 my @part = part { $idx[$i++ % 3] } 1 .. 8; # [1, 4, 7], [2, 3, 5, 6, 8]
887 Iteration
889 each_array ARRAY1 ARRAY2 ...
890 Creates an array iterator to return the elements of the list of arrays
892 ARRAY1, ARRAY2 throughout ARRAYn in turn. That is, the first time it
893 is called, it returns the first element of each array. The next time,
894 it returns the second elements. And so on, until all elements are
895 exhausted.
896 This is useful for looping over more than one array at once:
898 my $ea = each_array(@a, @b, @c);
900 while ( my ($a, $b, $c) = $ea->() ) { .... }
901 The iterator returns the empty list when it reached the end of all
903 arrays.
904 If the iterator is passed an argument of '"index"', then it returns the
906 index of the last fetched set of values, as a scalar.
907 each_arrayref LIST
909 Like each_array, but the arguments are references to arrays, not the
911 plain arrays.
912 natatime EXPR, LIST
914 Creates an array iterator, for looping over an array in chunks of $n
916 items at a time. (n at a time, get it?). An example is probably a
917 better explanation than I could give in words.
918 Example:
920 my @x = ('a' .. 'g');
922 my $it = natatime 3, @x;
923 while (my @vals = $it->())
924 {
925 print "@vals\n";
926 }
927 This prints
929 a b c
931 d e f
932 g
933 Searching
935 bsearch BLOCK LIST
936 Performs a binary search on LIST which must be a sorted list of values.
938 BLOCK must return a negative value if the current element (stored in
939 $_) is smaller, a positive value if it is bigger and zero if it
940 matches.
941 Returns a boolean value in scalar context. In list context, it returns
943 the element if it was found, otherwise the empty list.
944 bsearchidx BLOCK LIST
946 bsearch_index BLOCK LIST
948 Performs a binary search on LIST which must be a sorted list of values.
950 BLOCK must return a negative value if the current element (stored in
951 $_) is smaller, a positive value if it is bigger and zero if it
952 matches.
953 Returns the index of found element, otherwise "-1".
955 "bsearch_index" is an alias for "bsearchidx".
957 firstval BLOCK LIST
959 first_value BLOCK LIST
961 Returns the first element in LIST for which BLOCK evaluates to true.
963 Each element of LIST is set to $_ in turn. Returns "undef" if no such
964 element has been found.
965 "first_value" is an alias for "firstval".
967 onlyval BLOCK LIST
969 only_value BLOCK LIST
971 Returns the only element in LIST for which BLOCK evaluates to true.
973 Sets $_ for each item in LIST in turn. Returns "undef" if no such
974 element has been found.
975 "only_value" is an alias for "onlyval".
977 lastval BLOCK LIST
979 last_value BLOCK LIST
981 Returns the last value in LIST for which BLOCK evaluates to true. Each
983 element of LIST is set to $_ in turn. Returns "undef" if no such
984 element has been found.
985 "last_value" is an alias for "lastval".
987 firstres BLOCK LIST
989 first_result BLOCK LIST
991 Returns the result of BLOCK for the first element in LIST for which
993 BLOCK evaluates to true. Each element of LIST is set to $_ in turn.
994 Returns "undef" if no such element has been found.
995 "first_result" is an alias for "firstres".
997 onlyres BLOCK LIST
999 only_result BLOCK LIST
1001 Returns the result of BLOCK for the first element in LIST for which
1003 BLOCK evaluates to true. Sets $_ for each item in LIST in turn. Returns
1004 "undef" if no such element has been found.
1005 "only_result" is an alias for "onlyres".
1007 lastres BLOCK LIST
1009 last_result BLOCK LIST
1011 Returns the result of BLOCK for the last element in LIST for which
1013 BLOCK evaluates to true. Each element of LIST is set to $_ in turn.
1014 Returns "undef" if no such element has been found.
1015 "last_result" is an alias for "lastres".
1017 indexes BLOCK LIST
1019 Evaluates BLOCK for each element in LIST (assigned to $_) and returns a
1021 list of the indices of those elements for which BLOCK returned a true
1022 value. This is just like "grep" only that it returns indices instead of
1023 values:
1024 @x = indexes { $_ % 2 == 0 } (1..10); # returns 1, 3, 5, 7, 9
1026 firstidx BLOCK LIST
1028 first_index BLOCK LIST
1030 Returns the index of the first element in LIST for which the criterion
1032 in BLOCK is true. Sets $_ for each item in LIST in turn:
1033 my @list = (1, 4, 3, 2, 4, 6);
1035 printf "item with index %i in list is 4", firstidx { $_ == 4 } @list;
1036 __END__
1037 item with index 1 in list is 4
1038 Returns "-1" if no such item could be found.
1040 "first_index" is an alias for "firstidx".
1042 onlyidx BLOCK LIST
1044 only_index BLOCK LIST
1046 Returns the index of the only element in LIST for which the criterion
1048 in BLOCK is true. Sets $_ for each item in LIST in turn:
1049 my @list = (1, 3, 4, 3, 2, 4);
1051 printf "uniqe index of item 2 in list is %i", onlyidx { $_ == 2 } @list;
1052 __END__
1053 unique index of item 2 in list is 4
1054 Returns "-1" if either no such item or more than one of these has been
1056 found.
1057 "only_index" is an alias for "onlyidx".
1059 lastidx BLOCK LIST
1061 last_index BLOCK LIST
1063 Returns the index of the last element in LIST for which the criterion
1065 in BLOCK is true. Sets $_ for each item in LIST in turn:
1066 my @list = (1, 4, 3, 2, 4, 6);
1068 printf "item with index %i in list is 4", lastidx { $_ == 4 } @list;
1069 __END__
1070 item with index 4 in list is 4
1071 Returns "-1" if no such item could be found.
1073 "last_index" is an alias for "lastidx".
1075 Sorting
1077 sort_by BLOCK LIST
1078 Returns the list of values sorted according to the string values
1080 returned by the KEYFUNC block or function. A typical use of this may be
1081 to sort objects according to the string value of some accessor, such as
1082 sort_by { $_->name } @people
1084 The key function is called in scalar context, being passed each value
1086 in turn as both $_ and the only argument in the parameters, @_. The
1087 values are then sorted according to string comparisons on the values
1088 returned. This is equivalent to
1089 sort { $a->name cmp $b->name } @people
1091 except that it guarantees the name accessor will be executed only once
1093 per value. One interesting use-case is to sort strings which may have
1094 numbers embedded in them "naturally", rather than lexically.
1095 sort_by { s/(\d+)/sprintf "%09d", $1/eg; $_ } @strings
1097 This sorts strings by generating sort keys which zero-pad the embedded
1099 numbers to some level (9 digits in this case), helping to ensure the
1100 lexical sort puts them in the correct order.
1101 nsort_by BLOCK LIST
1103 Similar to sort_by but compares its key values numerically.
1105 Counting and calculation
1107 true BLOCK LIST
1108 Counts the number of elements in LIST for which the criterion in BLOCK
1110 is true. Sets $_ for each item in LIST in turn:
1111 printf "%i item(s) are defined", true { defined($_) } @list;
1113 false BLOCK LIST
1115 Counts the number of elements in LIST for which the criterion in BLOCK
1117 is false. Sets $_ for each item in LIST in turn:
1118 printf "%i item(s) are not defined", false { defined($_) } @list;
1120 minmax LIST
1122 Calculates the minimum and maximum of LIST and returns a two element
1124 list with the first element being the minimum and the second the
1125 maximum. Returns the empty list if LIST was empty.
1126 The "minmax" algorithm differs from a naive iteration over the list
1128 where each element is compared to two values being the so far
1129 calculated min and max value in that it only requires 3n/2 - 2
1130 comparisons. Thus it is the most efficient possible algorithm.
1131 However, the Perl implementation of it has some overhead simply due to
1133 the fact that there are more lines of Perl code involved. Therefore,
1134 LIST needs to be fairly big in order for "minmax" to win over a naive
1135 implementation. This limitation does not apply to the XS version.
1136 mode LIST
1138 Calculates the most common items in the list and returns them as a
1140 list. This is effectively done by string comparisons, so references
1141 will be stringified. If they implement string overloading, this will be
1142 used.
1143 If more than one item appears the same number of times in the list, all
1145 such items will be returned. For example, the mode of a unique list is
1146 the list itself.
1147 This function returns a list in list context. In scalar context it
1149 returns a count indicating the number of modes in the list.
1150
1152 All functions added since version 0.04 unless otherwise stated, as the
1153 original names for earlier versions were renamed.
1154 sort_by
1156 @vals = sort_by { KEYFUNC } @vals
1157 Returns the list of values sorted according to the string values
1159 returned by the "KEYFUNC" block or function. A typical use of this may
1160 be to sort objects according to the string value of some accessor, such
1161 as
1162 sort_by { $_->name } @people
1164 The key function is called in scalar context, being passed each value
1166 in turn as both $_ and the only argument in the parameters, @_. The
1167 values are then sorted according to string comparisons on the values
1168 returned.
1169 This is equivalent to
1171 sort { $a->name cmp $b->name } @people
1173 except that it guarantees the "name" accessor will be executed only
1175 once per value.
1176 One interesting use-case is to sort strings which may have numbers
1178 embedded in them "naturally", rather than lexically.
1179 sort_by { s/(\d+)/sprintf "%09d", $1/eg; $_ } @strings
1181 This sorts strings by generating sort keys which zero-pad the embedded
1183 numbers to some level (9 digits in this case), helping to ensure the
1184 lexical sort puts them in the correct order.
1185 nsort_by
1187 @vals = nsort_by { KEYFUNC } @vals
1188 Similar to "sort_by" but compares its key values numerically.
1190 rev_sort_by
1192 rev_nsort_by
1193 @vals = rev_sort_by { KEYFUNC } @vals
1194 @vals = rev_nsort_by { KEYFUNC } @vals
1196 Since version 0.06.
1198 Similar to "sort_by" and "nsort_by" but returns the list in the reverse
1200 order. Equivalent to
1201 @vals = reverse sort_by { KEYFUNC } @vals
1203 except that these functions are slightly more efficient because they
1205 avoid the final "reverse" operation.
1206 max_by
1208 $optimal = max_by { KEYFUNC } @vals
1209 @optimal = max_by { KEYFUNC } @vals
1211 Returns the (first) value from @vals that gives the numerically largest
1213 result from the key function.
1214 my $tallest = max_by { $_->height } @people
1216 use File::stat qw( stat );
1218 my $newest = max_by { stat($_)->mtime } @files;
1219 In scalar context, the first maximal value is returned. In list
1221 context, a list of all the maximal values is returned. This may be used
1222 to obtain positions other than the first, if order is significant.
1223 If called on an empty list, an empty list is returned.
1225 For symmetry with the "nsort_by" function, this is also provided under
1227 the name "nmax_by" since it behaves numerically.
1228 min_by
1230 $optimal = min_by { KEYFUNC } @vals
1231 @optimal = min_by { KEYFUNC } @vals
1233 Similar to "max_by" but returns values which give the numerically
1235 smallest result from the key function. Also provided as "nmin_by"
1236 minmax_by
1238 ( $minimal, $maximal ) = minmax_by { KEYFUNC } @vals
1239 Since version 0.11.
1241 Similar to calling both "min_by" and "max_by" with the same key
1243 function on the same list. This version is more efficient than calling
1244 the two other functions individually, as it has less work to perform
1245 overall. In the case of ties, only the first optimal element found in
1246 each case is returned. Also provided as "nminmax_by".
1247 uniq_by
1249 @vals = uniq_by { KEYFUNC } @vals
1250 Returns a list of the subset of values for which the key function block
1252 returns unique values. The first value yielding a particular key is
1253 chosen, subsequent values are rejected.
1254 my @some_fruit = uniq_by { $_->colour } @fruit;
1256 To select instead the last value per key, reverse the input list. If
1258 the order of the results is significant, don't forget to reverse the
1259 result as well:
1260 my @some_fruit = reverse uniq_by { $_->colour } reverse @fruit;
1262 Because the values returned by the key function are used as hash keys,
1264 they ought to either be strings, or at least well-behaved as strings
1265 (such as numbers, or object references which overload stringification
1266 in a suitable manner).
1267 partition_by
1269 %parts = partition_by { KEYFUNC } @vals
1270 Returns a key/value list of ARRAY refs containing all the original
1272 values distributed according to the result of the key function block.
1273 Each value will be an ARRAY ref containing all the values which
1274 returned the string from the key function, in their original order.
1275 my %balls_by_colour = partition_by { $_->colour } @balls;
1277 Because the values returned by the key function are used as hash keys,
1279 they ought to either be strings, or at least well-behaved as strings
1280 (such as numbers, or object references which overload stringification
1281 in a suitable manner).
1282 count_by
1284 %counts = count_by { KEYFUNC } @vals
1285 Since version 0.07.
1287 Returns a key/value list of integers, giving the number of times the
1289 key function block returned the key, for each value in the list.
1290 my %count_of_balls = count_by { $_->colour } @balls;
1292 Because the values returned by the key function are used as hash keys,
1294 they ought to either be strings, or at least well-behaved as strings
1295 (such as numbers, or object references which overload stringification
1296 in a suitable manner).
1297 zip_by
1299 @vals = zip_by { ITEMFUNC } \@arr0, \@arr1, \@arr2,...
1300 Returns a list of each of the values returned by the function block,
1302 when invoked with values from across each each of the given ARRAY
1303 references. Each value in the returned list will be the result of the
1304 function having been invoked with arguments at that position, from
1305 across each of the arrays given.
1306 my @transposition = zip_by { [ @_ ] } @matrix;
1308 my @names = zip_by { "$_[1], $_[0]" } \@firstnames, \@surnames;
1310 print zip_by { "$_[0] => $_[1]\n" } [ keys %hash ], [ values %hash ];
1312 If some of the arrays are shorter than others, the function will behave
1314 as if they had "undef" in the trailing positions. The following two
1315 lines are equivalent:
1316 zip_by { f(@_) } [ 1, 2, 3 ], [ "a", "b" ]
1318 f( 1, "a" ), f( 2, "b" ), f( 3, undef )
1319 The item function is called by "map", so if it returns a list, the
1321 entire list is included in the result. This can be useful for example,
1322 for generating a hash from two separate lists of keys and values
1323 my %nums = zip_by { @_ } [qw( one two three )], [ 1, 2, 3 ];
1325 # %nums = ( one => 1, two => 2, three => 3 )
1326 (A function having this behaviour is sometimes called "zipWith", e.g.
1328 in Haskell, but that name would not fit the naming scheme used by this
1329 module).
1330 unzip_by
1332 $arr0, $arr1, $arr2, ... = unzip_by { ITEMFUNC } @vals
1333 Since version 0.09.
1335 Returns a list of ARRAY references containing the values returned by
1337 the function block, when invoked for each of the values given in the
1338 input list. Each of the returned ARRAY references will contain the
1339 values returned at that corresponding position by the function block.
1340 That is, the first returned ARRAY reference will contain all the values
1341 returned in the first position by the function block, the second will
1342 contain all the values from the second position, and so on.
1343 my ( $firstnames, $lastnames ) = unzip_by { m/^(.*?) (.*)$/ } @names;
1345 If the function returns lists of differing lengths, the result will be
1347 padded with "undef" in the missing elements.
1348 This function is an inverse of "zip_by", if given a corresponding
1350 inverse function.
1351 extract_by
1353 @vals = extract_by { SELECTFUNC } @arr
1354 Since version 0.05.
1356 Removes elements from the referenced array on which the selection
1358 function returns true, and returns a list containing those elements.
1359 This function is similar to "grep", except that it modifies the
1360 referenced array to remove the selected values from it, leaving only
1361 the unselected ones.
1362 my @red_balls = extract_by { $_->color eq "red" } @balls;
1364 # Now there are no red balls in the @balls array
1366 This function modifies a real array, unlike most of the other functions
1368 in this module. Because of this, it requires a real array, not just a
1369 list.
1370 This function is implemented by invoking "splice" on the array, not by
1372 constructing a new list and assigning it. One result of this is that
1373 weak references will not be disturbed.
1374 extract_by { !defined $_ } @refs;
1376 will leave weak references weakened in the @refs array, whereas
1378 @refs = grep { defined $_ } @refs;
1380 will strengthen them all again.
1382 extract_first_by
1384 $val = extract_first_by { SELECTFUNC } @arr
1385 Since version 0.10.
1387 A hybrid between "extract_by" and "List::Util::first". Removes the
1389 first element from the referenced array on which the selection function
1390 returns true, returning it.
1391 As with "extract_by", this function requires a real array and not just
1393 a list, and is also implemented using "splice" so that weak references
1394 are not disturbed.
1395 If this function fails to find a matching element, it will return an
1397 empty list in list context. This allows a caller to distinguish the
1398 case between no matching element, and the first matching element being
1399 "undef".
1400 weighted_shuffle_by
1402 @vals = weighted_shuffle_by { WEIGHTFUNC } @vals
1403 Since version 0.07.
1405 Returns the list of values shuffled into a random order. The
1407 randomisation is not uniform, but weighted by the value returned by the
1408 "WEIGHTFUNC". The probabilty of each item being returned first will be
1409 distributed with the distribution of the weights, and so on recursively
1410 for the remaining items.
1411 bundle_by
1413 @vals = bundle_by { BLOCKFUNC } $number, @vals
1414 Since version 0.07.
1416 Similar to a regular "map" functional, returns a list of the values
1418 returned by "BLOCKFUNC". Values from the input list are given to the
1419 block function in bundles of $number.
1420 If given a list of values whose length does not evenly divide by
1422 $number, the final call will be passed fewer elements than the others.
1423
1425 This module exports nothing by default. You can import functions by
1426 name, or get everything with the ":all" tag.
1427
1429 List::Util, List::SomeUtils and List::UtilsBy, obviously.
1430 Also see "Util::Any", which unifies many more util modules, and also
1432 lets you rename functions as part of the import.
1433
1435 Please report any bugs or feature requests to
1436 "bug-list-allutils@rt.cpan.org", or through the web interface at
1437 <http://rt.cpan.org>. I will be notified, and then you'll
1438 automatically be notified of progress on your bug as I make changes.
1439 Bugs may be submitted at
1441 <https://github.com/houseabsolute/List-AllUtils/issues>.
1442 I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
1444
1446 The source code repository for List-AllUtils can be found at
1447 <https://github.com/houseabsolute/List-AllUtils>.
1448
1450 If you'd like to thank me for the work I've done on this module, please
1451 consider making a "donation" to me via PayPal. I spend a lot of free
1452 time creating free software, and would appreciate any support you'd
1453 care to offer.
1454 Please note that I am not suggesting that you must do this in order for
1456 me to continue working on this particular software. I will continue to
1457 do so, inasmuch as I have in the past, for as long as it interests me.
1458 Similarly, a donation made in this way will probably not make me work
1460 on this software much more, unless I get so many donations that I can
1461 consider working on free software full time (let's all have a chuckle
1462 at that together).
1463 To donate, log into PayPal and send money to autarch@urth.org, or use
1465 the button at <https://www.urth.org/fs-donation.html>.
1466
1468 Dave Rolsky <autarch@urth.org>
1469
1471 • Andy Jack <github@veracity.ca>
1472 • Dave Jacoby <jacoby.david@gmail.com>
1474 • Karen Etheridge <ether@cpan.org>
1476 • Olaf Alders <olaf@wundersolutions.com>
1478 • Ricardo Signes <rjbs@cpan.org>
1480 • Yanick Champoux <yanick@babyl.dyndns.org>
1482
1484 This software is Copyright (c) 2021 by Dave Rolsky.
1485 This is free software, licensed under:
1487 The Artistic License 2.0 (GPL Compatible)
1489 The full text of the license can be found in the LICENSE file included
1491 with this distribution.
1492perl v5.34.0 2022-01-21 List::AllUtils(3)