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.16
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. Similar, List::SomeUtils has some small
34 overlap with List::UtilsBy. "List::AllUtils" always favors the version
35 provided by List::Util, List::SomeUtils or List::UtilsBy in that order.
36 The docs below come from List::Util 1.54, List::SomeUtils 0.58, and
38 List::UtilsBy 0.11.
39
41 All this module does is load List::Util, List::SomeUtils, and
42 List::UtilsBy, and then re-export everything that they provide. That
43 means that regardless of the documentation below, you will get any
44 subroutine that your installed version provides.
45
47 The following set of functions all apply a given block of code to a
48 list of values. =head2 reduce
49 $result = reduce { BLOCK } @list
51 Reduces @list by calling "BLOCK" in a scalar context multiple times,
53 setting $a and $b each time. The first call will be with $a and $b set
54 to the first two elements of the list, subsequent calls will be done by
55 setting $a to the result of the previous call and $b to the next
56 element in the list.
57 Returns the result of the last call to the "BLOCK". If @list is empty
59 then "undef" is returned. If @list only contains one element then that
60 element is returned and "BLOCK" is not executed.
61 The following examples all demonstrate how "reduce" could be used to
63 implement the other list-reduction functions in this module. (They are
64 not in fact implemented like this, but instead in a more efficient
65 manner in individual C functions).
66 $foo = reduce { defined($a) ? $a :
68 $code->(local $_ = $b) ? $b :
69 undef } undef, @list # first
70 $foo = reduce { $a > $b ? $a : $b } 1..10 # max
72 $foo = reduce { $a gt $b ? $a : $b } 'A'..'Z' # maxstr
73 $foo = reduce { $a < $b ? $a : $b } 1..10 # min
74 $foo = reduce { $a lt $b ? $a : $b } 'aa'..'zz' # minstr
75 $foo = reduce { $a + $b } 1 .. 10 # sum
76 $foo = reduce { $a . $b } @bar # concat
77 $foo = reduce { $a || $code->(local $_ = $b) } 0, @bar # any
79 $foo = reduce { $a && $code->(local $_ = $b) } 1, @bar # all
80 $foo = reduce { $a && !$code->(local $_ = $b) } 1, @bar # none
81 $foo = reduce { $a || !$code->(local $_ = $b) } 0, @bar # notall
82 # Note that these implementations do not fully short-circuit
83 If your algorithm requires that "reduce" produce an identity value,
85 then make sure that you always pass that identity value as the first
86 argument to prevent "undef" being returned
87 $foo = reduce { $a + $b } 0, @values; # sum with 0 identity value
89 The above example code blocks also suggest how to use "reduce" to build
91 a more efficient combined version of one of these basic functions and a
92 "map" block. For example, to find the total length of all the strings
93 in a list, we could use
94 $total = sum map { length } @strings;
96 However, this produces a list of temporary integer values as long as
98 the original list of strings, only to reduce it down to a single value
99 again. We can compute the same result more efficiently by using
100 "reduce" with a code block that accumulates lengths by writing this
101 instead as:
102 $total = reduce { $a + length $b } 0, @strings
104 The other scalar-returning list reduction functions are all
106 specialisations of this generic idea.
107 reductions
109 @results = reductions { BLOCK } @list
110 Since version 1.54.
112 Similar to "reduce" except that it also returns the intermediate values
114 along with the final result. As before, $a is set to the first element
115 of the given list, and the "BLOCK" is then called once for remaining
116 item in the list set into $b, with the result being captured for return
117 as well as becoming the new value for $a.
118 The returned list will begin with the initial value for $a, followed by
120 each return value from the block in order. The final value of the
121 result will be identical to what the "reduce" function would have
122 returned given the same block and list.
123 reduce { "$a-$b" } "a".."d" # "a-b-c-d"
125 reductions { "$a-$b" } "a".."d" # "a", "a-b", "a-b-c", "a-b-c-d"
126 any
128 my $bool = any { BLOCK } @list;
129 Since version 1.33.
131 Similar to "grep" in that it evaluates "BLOCK" setting $_ to each
133 element of @list in turn. "any" returns true if any element makes the
134 "BLOCK" return a true value. If "BLOCK" never returns true or @list was
135 empty then it returns false.
136 Many cases of using "grep" in a conditional can be written using "any"
138 instead, as it can short-circuit after the first true result.
139 if( any { length > 10 } @strings ) {
141 # at least one string has more than 10 characters
142 }
143 Note: Due to XS issues the block passed may be able to access the outer
145 @_ directly. This is not intentional and will break under debugger.
146 all
148 my $bool = all { BLOCK } @list;
149 Since version 1.33.
151 Similar to "any", except that it requires all elements of the @list to
153 make the "BLOCK" return true. If any element returns false, then it
154 returns false. If the "BLOCK" never returns false or the @list was
155 empty then it returns true.
156 Note: Due to XS issues the block passed may be able to access the outer
158 @_ directly. This is not intentional and will break under debugger.
159 none
161 notall
162 my $bool = none { BLOCK } @list;
163 my $bool = notall { BLOCK } @list;
165 Since version 1.33.
167 Similar to "any" and "all", but with the return sense inverted. "none"
169 returns true only if no value in the @list causes the "BLOCK" to return
170 true, and "notall" returns true only if not all of the values do.
171 Note: Due to XS issues the block passed may be able to access the outer
173 @_ directly. This is not intentional and will break under debugger.
174 first
176 my $val = first { BLOCK } @list;
177 Similar to "grep" in that it evaluates "BLOCK" setting $_ to each
179 element of @list in turn. "first" returns the first element where the
180 result from "BLOCK" is a true value. If "BLOCK" never returns true or
181 @list was empty then "undef" is returned.
182 $foo = first { defined($_) } @list # first defined value in @list
184 $foo = first { $_ > $value } @list # first value in @list which
185 # is greater than $value
186 max
188 my $num = max @list;
189 Returns the entry in the list with the highest numerical value. If the
191 list is empty then "undef" is returned.
192 $foo = max 1..10 # 10
194 $foo = max 3,9,12 # 12
195 $foo = max @bar, @baz # whatever
196 maxstr
198 my $str = maxstr @list;
199 Similar to "max", but treats all the entries in the list as strings and
201 returns the highest string as defined by the "gt" operator. If the list
202 is empty then "undef" is returned.
203 $foo = maxstr 'A'..'Z' # 'Z'
205 $foo = maxstr "hello","world" # "world"
206 $foo = maxstr @bar, @baz # whatever
207 min
209 my $num = min @list;
210 Similar to "max" but returns the entry in the list with the lowest
212 numerical value. If the list is empty then "undef" is returned.
213 $foo = min 1..10 # 1
215 $foo = min 3,9,12 # 3
216 $foo = min @bar, @baz # whatever
217 minstr
219 my $str = minstr @list;
220 Similar to "min", but treats all the entries in the list as strings and
222 returns the lowest string as defined by the "lt" operator. If the list
223 is empty then "undef" is returned.
224 $foo = minstr 'A'..'Z' # 'A'
226 $foo = minstr "hello","world" # "hello"
227 $foo = minstr @bar, @baz # whatever
228 product
230 my $num = product @list;
231 Since version 1.35.
233 Returns the numerical product of all the elements in @list. If @list is
235 empty then 1 is returned.
236 $foo = product 1..10 # 3628800
238 $foo = product 3,9,12 # 324
239 sum
241 my $num_or_undef = sum @list;
242 Returns the numerical sum of all the elements in @list. For backwards
244 compatibility, if @list is empty then "undef" is returned.
245 $foo = sum 1..10 # 55
247 $foo = sum 3,9,12 # 24
248 $foo = sum @bar, @baz # whatever
249 sum0
251 my $num = sum0 @list;
252 Since version 1.26.
254 Similar to "sum", except this returns 0 when given an empty list,
256 rather than "undef". =head1 KEY/VALUE PAIR LIST FUNCTIONS
257 The following set of functions, all inspired by List::Pairwise, consume
259 an even-sized list of pairs. The pairs may be key/value associations
260 from a hash, or just a list of values. The functions will all preserve
261 the original ordering of the pairs, and will not be confused by
262 multiple pairs having the same "key" value - nor even do they require
263 that the first of each pair be a plain string.
264 NOTE: At the time of writing, the following "pair*" functions that take
266 a block do not modify the value of $_ within the block, and instead
267 operate using the $a and $b globals instead. This has turned out to be
268 a poor design, as it precludes the ability to provide a "pairsort"
269 function. Better would be to pass pair-like objects as 2-element array
270 references in $_, in a style similar to the return value of the "pairs"
271 function. At some future version this behaviour may be added.
272 Until then, users are alerted NOT to rely on the value of $_ remaining
274 unmodified between the outside and the inside of the control block. In
275 particular, the following example is UNSAFE:
276 my @kvlist = ...
278 foreach (qw( some keys here )) {
280 my @items = pairgrep { $a eq $_ } @kvlist;
281 ...
282 }
283 Instead, write this using a lexical variable:
285 foreach my $key (qw( some keys here )) {
287 my @items = pairgrep { $a eq $key } @kvlist;
288 ...
289 }
290 =head2 pairs
291 my @pairs = pairs @kvlist;
293 Since version 1.29.
295 A convenient shortcut to operating on even-sized lists of pairs, this
297 function returns a list of "ARRAY" references, each containing two
298 items from the given list. It is a more efficient version of
299 @pairs = pairmap { [ $a, $b ] } @kvlist
301 It is most convenient to use in a "foreach" loop, for example:
303 foreach my $pair ( pairs @kvlist ) {
305 my ( $key, $value ) = @$pair;
306 ...
307 }
308 Since version 1.39 these "ARRAY" references are blessed objects,
310 recognising the two methods "key" and "value". The following code is
311 equivalent:
312 foreach my $pair ( pairs @kvlist ) {
314 my $key = $pair->key;
315 my $value = $pair->value;
316 ...
317 }
318 Since version 1.51 they also have a "TO_JSON" method to ease
320 serialisation.
321 unpairs
323 my @kvlist = unpairs @pairs
324 Since version 1.42.
326 The inverse function to "pairs"; this function takes a list of "ARRAY"
328 references containing two elements each, and returns a flattened list
329 of the two values from each of the pairs, in order. This is notionally
330 equivalent to
331 my @kvlist = map { @{$_}[0,1] } @pairs
333 except that it is implemented more efficiently internally.
335 Specifically, for any input item it will extract exactly two values for
336 the output list; using "undef" if the input array references are short.
337 Between "pairs" and "unpairs", a higher-order list function can be used
339 to operate on the pairs as single scalars; such as the following near-
340 equivalents of the other "pair*" higher-order functions:
341 @kvlist = unpairs grep { FUNC } pairs @kvlist
343 # Like pairgrep, but takes $_ instead of $a and $b
344 @kvlist = unpairs map { FUNC } pairs @kvlist
346 # Like pairmap, but takes $_ instead of $a and $b
347 Note however that these versions will not behave as nicely in scalar
349 context.
350 Finally, this technique can be used to implement a sort on a keyvalue
352 pair list; e.g.:
353 @kvlist = unpairs sort { $a->key cmp $b->key } pairs @kvlist
355 pairkeys
357 my @keys = pairkeys @kvlist;
358 Since version 1.29.
360 A convenient shortcut to operating on even-sized lists of pairs, this
362 function returns a list of the the first values of each of the pairs in
363 the given list. It is a more efficient version of
364 @keys = pairmap { $a } @kvlist
366 pairvalues
368 my @values = pairvalues @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 second values of each of the pairs
374 in the given list. It is a more efficient version of
375 @values = pairmap { $b } @kvlist
377 pairgrep
379 my @kvlist = pairgrep { BLOCK } @kvlist;
380 my $count = pairgrep { BLOCK } @kvlist;
382 Since version 1.29.
384 Similar to perl's "grep" keyword, but interprets the given list as an
386 even-sized list of pairs. It invokes the "BLOCK" multiple times, in
387 scalar context, with $a and $b set to successive pairs of values from
388 the @kvlist.
389 Returns an even-sized list of those pairs for which the "BLOCK"
391 returned true in list context, or the count of the number of pairs in
392 scalar context. (Note, therefore, in scalar context that it returns a
393 number half the size of the count of items it would have returned in
394 list context).
395 @subset = pairgrep { $a =~ m/^[[:upper:]]+$/ } @kvlist
397 As with "grep" aliasing $_ to list elements, "pairgrep" aliases $a and
399 $b to elements of the given list. Any modifications of it by the code
400 block will be visible to the caller.
401 pairfirst
403 my ( $key, $val ) = pairfirst { BLOCK } @kvlist;
404 my $found = pairfirst { BLOCK } @kvlist;
406 Since version 1.30.
408 Similar to the "first" function, but interprets the given list as an
410 even-sized list of pairs. It invokes the "BLOCK" multiple times, in
411 scalar context, with $a and $b set to successive pairs of values from
412 the @kvlist.
413 Returns the first pair of values from the list for which the "BLOCK"
415 returned true in list context, or an empty list of no such pair was
416 found. In scalar context it returns a simple boolean value, rather than
417 either the key or the value found.
418 ( $key, $value ) = pairfirst { $a =~ m/^[[:upper:]]+$/ } @kvlist
420 As with "grep" aliasing $_ to list elements, "pairfirst" aliases $a and
422 $b to elements of the given list. Any modifications of it by the code
423 block will be visible to the caller.
424 pairmap
426 my @list = pairmap { BLOCK } @kvlist;
427 my $count = pairmap { BLOCK } @kvlist;
429 Since version 1.29.
431 Similar to perl's "map" keyword, but interprets the given list as an
433 even-sized list of pairs. It invokes the "BLOCK" multiple times, in
434 list context, with $a and $b set to successive pairs of values from the
435 @kvlist.
436 Returns the concatenation of all the values returned by the "BLOCK" in
438 list context, or the count of the number of items that would have been
439 returned in scalar context.
440 @result = pairmap { "The key $a has value $b" } @kvlist
442 As with "map" aliasing $_ to list elements, "pairmap" aliases $a and $b
444 to elements of the given list. Any modifications of it by the code
445 block will be visible to the caller.
446 See "KNOWN BUGS" for a known-bug with "pairmap", and a workaround.
448 =head1 OTHER FUNCTIONS =head2 shuffle
449 my @values = shuffle @values;
451 Returns the values of the input in a random order
453 @cards = shuffle 0..51 # 0..51 in a random order
455 This function is affected by the $RAND variable. =head2 sample
457 my @items = sample $count, @values
459 Since version 1.54.
461 Randomly select the given number of elements from the input list. Any
463 given position in the input list will be selected at most once.
464 If there are fewer than $count items in the list then the function will
466 return once all of them have been randomly selected; effectively the
467 function behaves similarly to "shuffle".
468 This function is affected by the $RAND variable.
470 uniq
472 my @subset = uniq @values
473 Since version 1.45.
475 Filters a list of values to remove subsequent duplicates, as judged by
477 a DWIM-ish string equality or "undef" test. Preserves the order of
478 unique elements, and retains the first value of any duplicate set.
479 my $count = uniq @values
481 In scalar context, returns the number of elements that would have been
483 returned as a list.
484 The "undef" value is treated by this function as distinct from the
486 empty string, and no warning will be produced. It is left as-is in the
487 returned list. Subsequent "undef" values are still considered identical
488 to the first, and will be removed.
489 uniqnum
491 my @subset = uniqnum @values
492 Since version 1.44.
494 Filters a list of values to remove subsequent duplicates, as judged by
496 a numerical equality test. Preserves the order of unique elements, and
497 retains the first value of any duplicate set.
498 my $count = uniqnum @values
500 In scalar context, returns the number of elements that would have been
502 returned as a list.
503 Note that "undef" is treated much as other numerical operations treat
505 it; it compares equal to zero but additionally produces a warning if
506 such warnings are enabled ("use warnings 'uninitialized';"). In
507 addition, an "undef" in the returned list is coerced into a numerical
508 zero, so that the entire list of values returned by "uniqnum" are well-
509 behaved as numbers.
510 Note also that multiple IEEE "NaN" values are treated as duplicates of
512 each other, regardless of any differences in their payloads, and
513 despite the fact that "0+'NaN' == 0+'NaN'" yields false.
514 uniqstr
516 my @subset = uniqstr @values
517 Since version 1.45.
519 Filters a list of values to remove subsequent duplicates, as judged by
521 a string equality test. Preserves the order of unique elements, and
522 retains the first value of any duplicate set.
523 my $count = uniqstr @values
525 In scalar context, returns the number of elements that would have been
527 returned as a list.
528 Note that "undef" is treated much as other string operations treat it;
530 it compares equal to the empty string but additionally produces a
531 warning if such warnings are enabled ("use warnings 'uninitialized';").
532 In addition, an "undef" in the returned list is coerced into an empty
533 string, so that the entire list of values returned by "uniqstr" are
534 well-behaved as strings. =head2 head
535 my @values = head $size, @list;
537 Since version 1.50.
539 Returns the first $size elements from @list. If $size is negative,
541 returns all but the last $size elements from @list.
542 @result = head 2, qw( foo bar baz );
544 # foo, bar
545 @result = head -2, qw( foo bar baz );
547 # foo
548 tail
550 my @values = tail $size, @list;
551 Since version 1.50.
553 Returns the last $size elements from @list. If $size is negative,
555 returns all but the first $size elements from @list.
556 @result = tail 2, qw( foo bar baz );
558 # bar, baz
559 @result = tail -2, qw( foo bar baz );
561 # baz
562
564 Junctions
565 Treatment of an empty list
566 There are two schools of thought for how to evaluate a junction on an
568 empty list:
569 · Reduction to an identity (boolean)
571 · Result is undefined (three-valued)
573 In the first case, the result of the junction applied to the empty list
575 is determined by a mathematical reduction to an identity depending on
576 whether the underlying comparison is "or" or "and". Conceptually:
577 "any are true" "all are true"
579 -------------- --------------
580 2 elements: A || B || 0 A && B && 1
581 1 element: A || 0 A && 1
582 0 elements: 0 1
583 In the second case, three-value logic is desired, in which a junction
585 applied to an empty list returns "undef" rather than true or false
586 Junctions with a "_u" suffix implement three-valued logic. Those
588 without are boolean.
589 all BLOCK LIST
591 all_u BLOCK LIST
593 Returns a true value if all items in LIST meet the criterion given
595 through BLOCK. Sets $_ for each item in LIST in turn:
596 print "All values are non-negative"
598 if all { $_ >= 0 } ($x, $y, $z);
599 For an empty LIST, "all" returns true (i.e. no values failed the
601 condition) and "all_u" returns "undef".
602 Thus, "all_u(@list)" is equivalent to "@list ? all(@list) : undef".
604 Note: because Perl treats "undef" as false, you must check the return
606 value of "all_u" with "defined" or you will get the opposite result of
607 what you expect.
608 any BLOCK LIST
610 any_u BLOCK LIST
612 Returns a true value if any item in LIST meets the criterion given
614 through BLOCK. Sets $_ for each item in LIST in turn:
615 print "At least one non-negative value"
617 if any { $_ >= 0 } ($x, $y, $z);
618 For an empty LIST, "any" returns false and "any_u" returns "undef".
620 Thus, "any_u(@list)" is equivalent to "@list ? any(@list) : undef".
622 none BLOCK LIST
624 none_u BLOCK LIST
626 Logically the negation of "any". Returns a true value if no item in
628 LIST meets the criterion given through BLOCK. Sets $_ for each item in
629 LIST in turn:
630 print "No non-negative values"
632 if none { $_ >= 0 } ($x, $y, $z);
633 For an empty LIST, "none" returns true (i.e. no values failed the
635 condition) and "none_u" returns "undef".
636 Thus, "none_u(@list)" is equivalent to "@list ? none(@list) : undef".
638 Note: because Perl treats "undef" as false, you must check the return
640 value of "none_u" with "defined" or you will get the opposite result of
641 what you expect.
642 notall BLOCK LIST
644 notall_u BLOCK LIST
646 Logically the negation of "all". Returns a true value if not all items
648 in LIST meet the criterion given through BLOCK. Sets $_ for each item
649 in LIST in turn:
650 print "Not all values are non-negative"
652 if notall { $_ >= 0 } ($x, $y, $z);
653 For an empty LIST, "notall" returns false and "notall_u" returns
655 "undef".
656 Thus, "notall_u(@list)" is equivalent to "@list ? notall(@list) :
658 undef".
659 one BLOCK LIST
661 one_u BLOCK LIST
663 Returns a true value if precisely one item in LIST meets the criterion
665 given through BLOCK. Sets $_ for each item in LIST in turn:
666 print "Precisely one value defined"
668 if one { defined($_) } @list;
669 Returns false otherwise.
671 For an empty LIST, "one" returns false and "one_u" returns "undef".
673 The expression "one BLOCK LIST" is almost equivalent to "1 == true
675 BLOCK LIST", except for short-cutting. Evaluation of BLOCK will
676 immediately stop at the second true value.
677 Transformation
679 apply BLOCK LIST
680 Makes a copy of the list and then passes each element from the copy to
682 the BLOCK. Any changes or assignments to $_ in the BLOCK will only
683 affect the elements of the new list. However, if $_ is a reference then
684 changes to the referenced value will be seen in both the original and
685 new list.
686 This function is similar to "map" but will not modify the elements of
688 the input list:
689 my @list = (1 .. 4);
691 my @mult = apply { $_ *= 2 } @list;
692 print "\@list = @list\n";
693 print "\@mult = @mult\n";
694 __END__
695 @list = 1 2 3 4
696 @mult = 2 4 6 8
697 Think of it as syntactic sugar for
699 for (my @mult = @list) { $_ *= 2 }
701 Note that you must alter $_ directly inside BLOCK in order for changes
703 to make effect. New value returned from the BLOCK are ignored:
704 # @new is identical to @list.
706 my @new = apply { $_ * 2 } @list;
707 # @new is different from @list
709 my @new = apply { $_ =* 2 } @list;
710 insert_after BLOCK VALUE LIST
712 Inserts VALUE after the first item in LIST for which the criterion in
714 BLOCK is true. Sets $_ for each item in LIST in turn.
715 my @list = qw/This is a list/;
717 insert_after { $_ eq "a" } "longer" => @list;
718 print "@list";
719 __END__
720 This is a longer list
721 insert_after_string STRING VALUE LIST
723 Inserts VALUE after the first item in LIST which is equal to STRING.
725 my @list = qw/This is a list/;
727 insert_after_string "a", "longer" => @list;
728 print "@list";
729 __END__
730 This is a longer list
731 pairwise BLOCK ARRAY1 ARRAY2
733 Evaluates BLOCK for each pair of elements in ARRAY1 and ARRAY2 and
735 returns a new list consisting of BLOCK's return values. The two
736 elements are set to $a and $b. Note that those two are aliases to the
737 original value so changing them will modify the input arrays.
738 @a = (1 .. 5);
740 @b = (11 .. 15);
741 @x = pairwise { $a + $b } @a, @b; # returns 12, 14, 16, 18, 20
742 # mesh with pairwise
744 @a = qw/a b c/;
745 @b = qw/1 2 3/;
746 @x = pairwise { ($a, $b) } @a, @b; # returns a, 1, b, 2, c, 3
747 mesh ARRAY1 ARRAY2 [ ARRAY3 ... ]
749 zip ARRAY1 ARRAY2 [ ARRAY3 ... ]
751 Returns a list consisting of the first elements of each array, then the
753 second, then the third, etc, until all arrays are exhausted.
754 Examples:
756 @x = qw/a b c d/;
758 @y = qw/1 2 3 4/;
759 @z = mesh @x, @y; # returns a, 1, b, 2, c, 3, d, 4
760 @a = ('x');
762 @b = ('1', '2');
763 @c = qw/zip zap zot/;
764 @d = mesh @a, @b, @c; # x, 1, zip, undef, 2, zap, undef, undef, zot
765 "zip" is an alias for "mesh".
767 uniq LIST
769 distinct LIST
771 Returns a new list by stripping duplicate values in LIST by comparing
773 the values as hash keys, except that undef is considered separate from
774 ''. The order of elements in the returned list is the same as in LIST.
775 In scalar context, returns the number of unique elements in LIST.
776 my @x = uniq 1, 1, 2, 2, 3, 5, 3, 4; # returns 1 2 3 5 4
778 my $x = uniq 1, 1, 2, 2, 3, 5, 3, 4; # returns 5
779 # returns "Mike", "Michael", "Richard", "Rick"
780 my @n = distinct "Mike", "Michael", "Richard", "Rick", "Michael", "Rick"
781 # returns '', undef, 'S1', A5'
782 my @s = distinct '', undef, 'S1', 'A5'
783 # returns '', undef, 'S1', A5'
784 my @w = uniq undef, '', 'S1', 'A5'
785 "distinct" is an alias for "uniq".
787 RT#49800 can be used to give feedback about this behavior.
789 singleton
791 Returns a new list by stripping values in LIST occurring more than once
793 by comparing the values as hash keys, except that undef is considered
794 separate from ''. The order of elements in the returned list is the
795 same as in LIST. In scalar context, returns the number of elements
796 occurring only once in LIST.
797 my @x = singleton 1,1,2,2,3,4,5 # returns 3 4 5
799 Partitioning
801 after BLOCK LIST
802 Returns a list of the values of LIST after (and not including) the
804 point where BLOCK returns a true value. Sets $_ for each element in
805 LIST in turn.
806 @x = after { $_ % 5 == 0 } (1..9); # returns 6, 7, 8, 9
808 after_incl BLOCK LIST
810 Same as "after" but also includes the element for which BLOCK is true.
812 before BLOCK LIST
814 Returns a list of values of LIST up to (and not including) the point
816 where BLOCK returns a true value. Sets $_ for each element in LIST in
817 turn.
818 before_incl BLOCK LIST
820 Same as "before" but also includes the element for which BLOCK is true.
822 part BLOCK LIST
824 Partitions LIST based on the return value of BLOCK which denotes into
826 which partition the current value is put.
827 Returns a list of the partitions thusly created. Each partition created
829 is a reference to an array.
830 my $i = 0;
832 my @part = part { $i++ % 2 } 1 .. 8; # returns [1, 3, 5, 7], [2, 4, 6, 8]
833 You can have a sparse list of partitions as well where non-set
835 partitions will be undef:
836 my @part = part { 2 } 1 .. 10; # returns undef, undef, [ 1 .. 10 ]
838 Be careful with negative values, though:
840 my @part = part { -1 } 1 .. 10;
842 __END__
843 Modification of non-creatable array value attempted, subscript -1 ...
844 Negative values are only ok when they refer to a partition previously
846 created:
847 my @idx = ( 0, 1, -1 );
849 my $i = 0;
850 my @part = part { $idx[$i++ % 3] } 1 .. 8; # [1, 4, 7], [2, 3, 5, 6, 8]
851 Iteration
853 each_array ARRAY1 ARRAY2 ...
854 Creates an array iterator to return the elements of the list of arrays
856 ARRAY1, ARRAY2 throughout ARRAYn in turn. That is, the first time it
857 is called, it returns the first element of each array. The next time,
858 it returns the second elements. And so on, until all elements are
859 exhausted.
860 This is useful for looping over more than one array at once:
862 my $ea = each_array(@a, @b, @c);
864 while ( my ($a, $b, $c) = $ea->() ) { .... }
865 The iterator returns the empty list when it reached the end of all
867 arrays.
868 If the iterator is passed an argument of '"index"', then it returns the
870 index of the last fetched set of values, as a scalar.
871 each_arrayref LIST
873 Like each_array, but the arguments are references to arrays, not the
875 plain arrays.
876 natatime EXPR, LIST
878 Creates an array iterator, for looping over an array in chunks of $n
880 items at a time. (n at a time, get it?). An example is probably a
881 better explanation than I could give in words.
882 Example:
884 my @x = ('a' .. 'g');
886 my $it = natatime 3, @x;
887 while (my @vals = $it->())
888 {
889 print "@vals\n";
890 }
891 This prints
893 a b c
895 d e f
896 g
897 Searching
899 bsearch BLOCK LIST
900 Performs a binary search on LIST which must be a sorted list of values.
902 BLOCK must return a negative value if the current element (stored in
903 $_) is smaller, a positive value if it is bigger and zero if it
904 matches.
905 Returns a boolean value in scalar context. In list context, it returns
907 the element if it was found, otherwise the empty list.
908 bsearchidx BLOCK LIST
910 bsearch_index BLOCK LIST
912 Performs a binary search on LIST which must be a sorted list of values.
914 BLOCK must return a negative value if the current element (stored in
915 $_) is smaller, a positive value if it is bigger and zero if it
916 matches.
917 Returns the index of found element, otherwise "-1".
919 "bsearch_index" is an alias for "bsearchidx".
921 firstval BLOCK LIST
923 first_value BLOCK LIST
925 Returns the first element in LIST for which BLOCK evaluates to true.
927 Each element of LIST is set to $_ in turn. Returns "undef" if no such
928 element has been found.
929 "first_value" is an alias for "firstval".
931 onlyval BLOCK LIST
933 only_value BLOCK LIST
935 Returns the only element in LIST for which BLOCK evaluates to true.
937 Sets $_ for each item in LIST in turn. Returns "undef" if no such
938 element has been found.
939 "only_value" is an alias for "onlyval".
941 lastval BLOCK LIST
943 last_value BLOCK LIST
945 Returns the last value in LIST for which BLOCK evaluates to true. Each
947 element of LIST is set to $_ in turn. Returns "undef" if no such
948 element has been found.
949 "last_value" is an alias for "lastval".
951 firstres BLOCK LIST
953 first_result BLOCK LIST
955 Returns the result of BLOCK for the first element in LIST for which
957 BLOCK evaluates to true. Each element of LIST is set to $_ in turn.
958 Returns "undef" if no such element has been found.
959 "first_result" is an alias for "firstres".
961 onlyres BLOCK LIST
963 only_result BLOCK LIST
965 Returns the result of BLOCK for the first element in LIST for which
967 BLOCK evaluates to true. Sets $_ for each item in LIST in turn. Returns
968 "undef" if no such element has been found.
969 "only_result" is an alias for "onlyres".
971 lastres BLOCK LIST
973 last_result BLOCK LIST
975 Returns the result of BLOCK for the last element in LIST for which
977 BLOCK evaluates to true. Each element of LIST is set to $_ in turn.
978 Returns "undef" if no such element has been found.
979 "last_result" is an alias for "lastres".
981 indexes BLOCK LIST
983 Evaluates BLOCK for each element in LIST (assigned to $_) and returns a
985 list of the indices of those elements for which BLOCK returned a true
986 value. This is just like "grep" only that it returns indices instead of
987 values:
988 @x = indexes { $_ % 2 == 0 } (1..10); # returns 1, 3, 5, 7, 9
990 firstidx BLOCK LIST
992 first_index BLOCK LIST
994 Returns the index of the first element in LIST for which the criterion
996 in BLOCK is true. Sets $_ for each item in LIST in turn:
997 my @list = (1, 4, 3, 2, 4, 6);
999 printf "item with index %i in list is 4", firstidx { $_ == 4 } @list;
1000 __END__
1001 item with index 1 in list is 4
1002 Returns "-1" if no such item could be found.
1004 "first_index" is an alias for "firstidx".
1006 onlyidx BLOCK LIST
1008 only_index BLOCK LIST
1010 Returns the index of the only element in LIST for which the criterion
1012 in BLOCK is true. Sets $_ for each item in LIST in turn:
1013 my @list = (1, 3, 4, 3, 2, 4);
1015 printf "uniqe index of item 2 in list is %i", onlyidx { $_ == 2 } @list;
1016 __END__
1017 unique index of item 2 in list is 4
1018 Returns "-1" if either no such item or more than one of these has been
1020 found.
1021 "only_index" is an alias for "onlyidx".
1023 lastidx BLOCK LIST
1025 last_index BLOCK LIST
1027 Returns the index of the last element in LIST for which the criterion
1029 in BLOCK is true. Sets $_ for each item in LIST in turn:
1030 my @list = (1, 4, 3, 2, 4, 6);
1032 printf "item with index %i in list is 4", lastidx { $_ == 4 } @list;
1033 __END__
1034 item with index 4 in list is 4
1035 Returns "-1" if no such item could be found.
1037 "last_index" is an alias for "lastidx".
1039 Sorting
1041 sort_by BLOCK LIST
1042 Returns the list of values sorted according to the string values
1044 returned by the KEYFUNC block or function. A typical use of this may be
1045 to sort objects according to the string value of some accessor, such as
1046 sort_by { $_->name } @people
1048 The key function is called in scalar context, being passed each value
1050 in turn as both $_ and the only argument in the parameters, @_. The
1051 values are then sorted according to string comparisons on the values
1052 returned. This is equivalent to
1053 sort { $a->name cmp $b->name } @people
1055 except that it guarantees the name accessor will be executed only once
1057 per value. One interesting use-case is to sort strings which may have
1058 numbers embedded in them "naturally", rather than lexically.
1059 sort_by { s/(\d+)/sprintf "%09d", $1/eg; $_ } @strings
1061 This sorts strings by generating sort keys which zero-pad the embedded
1063 numbers to some level (9 digits in this case), helping to ensure the
1064 lexical sort puts them in the correct order.
1065 nsort_by BLOCK LIST
1067 Similar to sort_by but compares its key values numerically.
1069 Counting and calculation
1071 true BLOCK LIST
1072 Counts the number of elements in LIST for which the criterion in BLOCK
1074 is true. Sets $_ for each item in LIST in turn:
1075 printf "%i item(s) are defined", true { defined($_) } @list;
1077 false BLOCK LIST
1079 Counts the number of elements in LIST for which the criterion in BLOCK
1081 is false. Sets $_ for each item in LIST in turn:
1082 printf "%i item(s) are not defined", false { defined($_) } @list;
1084 minmax LIST
1086 Calculates the minimum and maximum of LIST and returns a two element
1088 list with the first element being the minimum and the second the
1089 maximum. Returns the empty list if LIST was empty.
1090 The "minmax" algorithm differs from a naive iteration over the list
1092 where each element is compared to two values being the so far
1093 calculated min and max value in that it only requires 3n/2 - 2
1094 comparisons. Thus it is the most efficient possible algorithm.
1095 However, the Perl implementation of it has some overhead simply due to
1097 the fact that there are more lines of Perl code involved. Therefore,
1098 LIST needs to be fairly big in order for "minmax" to win over a naive
1099 implementation. This limitation does not apply to the XS version.
1100 mode LIST
1102 Calculates the most common items in the list and returns them as a
1104 list. This is effectively done by string comparisons, so references
1105 will be stringified. If they implement string overloading, this will be
1106 used.
1107 If more than one item appears the same number of times in the list, all
1109 such items will be returned. For example, the mode of a unique list is
1110 the list itself.
1111 This function returns a list in list context. In scalar context it
1113 returns a count indicating the number of modes in the list.
1114
1116 All functions added since version 0.04 unless otherwise stated, as the
1117 original names for earlier versions were renamed.
1118 sort_by
1120 @vals = sort_by { KEYFUNC } @vals
1121 Returns the list of values sorted according to the string values
1123 returned by the "KEYFUNC" block or function. A typical use of this may
1124 be to sort objects according to the string value of some accessor, such
1125 as
1126 sort_by { $_->name } @people
1128 The key function is called in scalar context, being passed each value
1130 in turn as both $_ and the only argument in the parameters, @_. The
1131 values are then sorted according to string comparisons on the values
1132 returned.
1133 This is equivalent to
1135 sort { $a->name cmp $b->name } @people
1137 except that it guarantees the "name" accessor will be executed only
1139 once per value.
1140 One interesting use-case is to sort strings which may have numbers
1142 embedded in them "naturally", rather than lexically.
1143 sort_by { s/(\d+)/sprintf "%09d", $1/eg; $_ } @strings
1145 This sorts strings by generating sort keys which zero-pad the embedded
1147 numbers to some level (9 digits in this case), helping to ensure the
1148 lexical sort puts them in the correct order.
1149 nsort_by
1151 @vals = nsort_by { KEYFUNC } @vals
1152 Similar to "sort_by" but compares its key values numerically.
1154 rev_sort_by
1156 rev_nsort_by
1157 @vals = rev_sort_by { KEYFUNC } @vals
1158 @vals = rev_nsort_by { KEYFUNC } @vals
1160 Since version 0.06.
1162 Similar to "sort_by" and "nsort_by" but returns the list in the reverse
1164 order. Equivalent to
1165 @vals = reverse sort_by { KEYFUNC } @vals
1167 except that these functions are slightly more efficient because they
1169 avoid the final "reverse" operation.
1170 max_by
1172 $optimal = max_by { KEYFUNC } @vals
1173 @optimal = max_by { KEYFUNC } @vals
1175 Returns the (first) value from @vals that gives the numerically largest
1177 result from the key function.
1178 my $tallest = max_by { $_->height } @people
1180 use File::stat qw( stat );
1182 my $newest = max_by { stat($_)->mtime } @files;
1183 In scalar context, the first maximal value is returned. In list
1185 context, a list of all the maximal values is returned. This may be used
1186 to obtain positions other than the first, if order is significant.
1187 If called on an empty list, an empty list is returned.
1189 For symmetry with the "nsort_by" function, this is also provided under
1191 the name "nmax_by" since it behaves numerically.
1192 min_by
1194 $optimal = min_by { KEYFUNC } @vals
1195 @optimal = min_by { KEYFUNC } @vals
1197 Similar to "max_by" but returns values which give the numerically
1199 smallest result from the key function. Also provided as "nmin_by"
1200 minmax_by
1202 ( $minimal, $maximal ) = minmax_by { KEYFUNC } @vals
1203 Since version 0.11.
1205 Similar to calling both "min_by" and "max_by" with the same key
1207 function on the same list. This version is more efficient than calling
1208 the two other functions individually, as it has less work to perform
1209 overall. In the case of ties, only the first optimal element found in
1210 each case is returned. Also provided as "nminmax_by".
1211 uniq_by
1213 @vals = uniq_by { KEYFUNC } @vals
1214 Returns a list of the subset of values for which the key function block
1216 returns unique values. The first value yielding a particular key is
1217 chosen, subsequent values are rejected.
1218 my @some_fruit = uniq_by { $_->colour } @fruit;
1220 To select instead the last value per key, reverse the input list. If
1222 the order of the results is significant, don't forget to reverse the
1223 result as well:
1224 my @some_fruit = reverse uniq_by { $_->colour } reverse @fruit;
1226 Because the values returned by the key function are used as hash keys,
1228 they ought to either be strings, or at least well-behaved as strings
1229 (such as numbers, or object references which overload stringification
1230 in a suitable manner).
1231 partition_by
1233 %parts = partition_by { KEYFUNC } @vals
1234 Returns a key/value list of ARRAY refs containing all the original
1236 values distributed according to the result of the key function block.
1237 Each value will be an ARRAY ref containing all the values which
1238 returned the string from the key function, in their original order.
1239 my %balls_by_colour = partition_by { $_->colour } @balls;
1241 Because the values returned by the key function are used as hash keys,
1243 they ought to either be strings, or at least well-behaved as strings
1244 (such as numbers, or object references which overload stringification
1245 in a suitable manner).
1246 count_by
1248 %counts = count_by { KEYFUNC } @vals
1249 Since version 0.07.
1251 Returns a key/value list of integers, giving the number of times the
1253 key function block returned the key, for each value in the list.
1254 my %count_of_balls = count_by { $_->colour } @balls;
1256 Because the values returned by the key function are used as hash keys,
1258 they ought to either be strings, or at least well-behaved as strings
1259 (such as numbers, or object references which overload stringification
1260 in a suitable manner).
1261 zip_by
1263 @vals = zip_by { ITEMFUNC } \@arr0, \@arr1, \@arr2,...
1264 Returns a list of each of the values returned by the function block,
1266 when invoked with values from across each each of the given ARRAY
1267 references. Each value in the returned list will be the result of the
1268 function having been invoked with arguments at that position, from
1269 across each of the arrays given.
1270 my @transposition = zip_by { [ @_ ] } @matrix;
1272 my @names = zip_by { "$_[1], $_[0]" } \@firstnames, \@surnames;
1274 print zip_by { "$_[0] => $_[1]\n" } [ keys %hash ], [ values %hash ];
1276 If some of the arrays are shorter than others, the function will behave
1278 as if they had "undef" in the trailing positions. The following two
1279 lines are equivalent:
1280 zip_by { f(@_) } [ 1, 2, 3 ], [ "a", "b" ]
1282 f( 1, "a" ), f( 2, "b" ), f( 3, undef )
1283 The item function is called by "map", so if it returns a list, the
1285 entire list is included in the result. This can be useful for example,
1286 for generating a hash from two separate lists of keys and values
1287 my %nums = zip_by { @_ } [qw( one two three )], [ 1, 2, 3 ];
1289 # %nums = ( one => 1, two => 2, three => 3 )
1290 (A function having this behaviour is sometimes called "zipWith", e.g.
1292 in Haskell, but that name would not fit the naming scheme used by this
1293 module).
1294 unzip_by
1296 $arr0, $arr1, $arr2, ... = unzip_by { ITEMFUNC } @vals
1297 Since version 0.09.
1299 Returns a list of ARRAY references containing the values returned by
1301 the function block, when invoked for each of the values given in the
1302 input list. Each of the returned ARRAY references will contain the
1303 values returned at that corresponding position by the function block.
1304 That is, the first returned ARRAY reference will contain all the values
1305 returned in the first position by the function block, the second will
1306 contain all the values from the second position, and so on.
1307 my ( $firstnames, $lastnames ) = unzip_by { m/^(.*?) (.*)$/ } @names;
1309 If the function returns lists of differing lengths, the result will be
1311 padded with "undef" in the missing elements.
1312 This function is an inverse of "zip_by", if given a corresponding
1314 inverse function.
1315 extract_by
1317 @vals = extract_by { SELECTFUNC } @arr
1318 Since version 0.05.
1320 Removes elements from the referenced array on which the selection
1322 function returns true, and returns a list containing those elements.
1323 This function is similar to "grep", except that it modifies the
1324 referenced array to remove the selected values from it, leaving only
1325 the unselected ones.
1326 my @red_balls = extract_by { $_->color eq "red" } @balls;
1328 # Now there are no red balls in the @balls array
1330 This function modifies a real array, unlike most of the other functions
1332 in this module. Because of this, it requires a real array, not just a
1333 list.
1334 This function is implemented by invoking "splice" on the array, not by
1336 constructing a new list and assigning it. One result of this is that
1337 weak references will not be disturbed.
1338 extract_by { !defined $_ } @refs;
1340 will leave weak references weakened in the @refs array, whereas
1342 @refs = grep { defined $_ } @refs;
1344 will strengthen them all again.
1346 extract_first_by
1348 $val = extract_first_by { SELECTFUNC } @arr
1349 Since version 0.10.
1351 A hybrid between "extract_by" and "List::Util::first". Removes the
1353 first element from the referenced array on which the selection function
1354 returns true, returning it.
1355 As with "extract_by", this function requires a real array and not just
1357 a list, and is also implemented using "splice" so that weak references
1358 are not disturbed.
1359 If this function fails to find a matching element, it will return an
1361 empty list in list context. This allows a caller to distinguish the
1362 case between no matching element, and the first matching element being
1363 "undef".
1364 weighted_shuffle_by
1366 @vals = weighted_shuffle_by { WEIGHTFUNC } @vals
1367 Since version 0.07.
1369 Returns the list of values shuffled into a random order. The
1371 randomisation is not uniform, but weighted by the value returned by the
1372 "WEIGHTFUNC". The probabilty of each item being returned first will be
1373 distributed with the distribution of the weights, and so on recursively
1374 for the remaining items.
1375 bundle_by
1377 @vals = bundle_by { BLOCKFUNC } $number, @vals
1378 Since version 0.07.
1380 Similar to a regular "map" functional, returns a list of the values
1382 returned by "BLOCKFUNC". Values from the input list are given to the
1383 block function in bundles of $number.
1384 If given a list of values whose length does not evenly divide by
1386 $number, the final call will be passed fewer elements than the others.
1387
1389 This module exports nothing by default. You can import functions by
1390 name, or get everything with the ":all" tag.
1391
1393 List::Util, List::SomeUtils and List::UtilsBy, obviously.
1394 Also see "Util::Any", which unifies many more util modules, and also
1396 lets you rename functions as part of the import.
1397
1399 Please report any bugs or feature requests to
1400 "bug-list-allutils@rt.cpan.org", or through the web interface at
1401 <http://rt.cpan.org>. I will be notified, and then you'll
1402 automatically be notified of progress on your bug as I make changes.
1403 Bugs may be submitted at
1405 <http://rt.cpan.org/Public/Dist/Display.html?Name=List-AllUtils> or via
1406 email to bug-list-allutils@rt.cpan.org <mailto:bug-list-
1407 allutils@rt.cpan.org>.
1408 I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
1410
1412 The source code repository for List-AllUtils can be found at
1413 <https://github.com/houseabsolute/List-AllUtils>.
1414
1416 If you'd like to thank me for the work I've done on this module, please
1417 consider making a "donation" to me via PayPal. I spend a lot of free
1418 time creating free software, and would appreciate any support you'd
1419 care to offer.
1420 Please note that I am not suggesting that you must do this in order for
1422 me to continue working on this particular software. I will continue to
1423 do so, inasmuch as I have in the past, for as long as it interests me.
1424 Similarly, a donation made in this way will probably not make me work
1426 on this software much more, unless I get so many donations that I can
1427 consider working on free software full time (let's all have a chuckle
1428 at that together).
1429 To donate, log into PayPal and send money to autarch@urth.org, or use
1431 the button at <http://www.urth.org/~autarch/fs-donation.html>.
1432
1434 Dave Rolsky <autarch@urth.org>
1435
1437 · Andy Jack <github@veracity.ca>
1438 · Dave Jacoby <jacoby.david@gmail.com>
1440 · Karen Etheridge <ether@cpan.org>
1442 · Ricardo Signes <rjbs@cpan.org>
1444 · Yanick Champoux <yanick@babyl.dyndns.org>
1446
1448 This software is Copyright (c) 2020 by Dave Rolsky.
1449 This is free software, licensed under:
1451 The Artistic License 2.0 (GPL Compatible)
1453 The full text of the license can be found in the LICENSE file included
1455 with this distribution.
1456perl v5.30.1 2020-03-02 List::AllUtils(3)