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.18
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. "List::AllUtils" always favors the
35 subroutine provided by List::Util, List::SomeUtils or List::UtilsBy in
36 that order.
37 The docs below come from List::Util 1.54, List::SomeUtils 0.58, and
39 List::UtilsBy 0.11.
40
42 All this module does is load List::Util, List::SomeUtils, and
43 List::UtilsBy, and then re-export everything that they provide. That
44 means that regardless of the documentation below, you will get any
45 subroutine that your installed version provides.
46
48 The following set of functions all apply a given block of code to a
49 list of values.
50 reduce
52 $result = reduce { BLOCK } @list
53 Reduces @list by calling "BLOCK" in a scalar context multiple times,
55 setting $a and $b each time. The first call will be with $a and $b set
56 to the first two elements of the list, subsequent calls will be done by
57 setting $a to the result of the previous call and $b to the next
58 element in the list.
59 Returns the result of the last call to the "BLOCK". If @list is empty
61 then "undef" is returned. If @list only contains one element then that
62 element is returned and "BLOCK" is not executed.
63 The following examples all demonstrate how "reduce" could be used to
65 implement the other list-reduction functions in this module. (They are
66 not in fact implemented like this, but instead in a more efficient
67 manner in individual C functions).
68 $foo = reduce { defined($a) ? $a :
70 $code->(local $_ = $b) ? $b :
71 undef } undef, @list # first
72 $foo = reduce { $a > $b ? $a : $b } 1..10 # max
74 $foo = reduce { $a gt $b ? $a : $b } 'A'..'Z' # maxstr
75 $foo = reduce { $a < $b ? $a : $b } 1..10 # min
76 $foo = reduce { $a lt $b ? $a : $b } 'aa'..'zz' # minstr
77 $foo = reduce { $a + $b } 1 .. 10 # sum
78 $foo = reduce { $a . $b } @bar # concat
79 $foo = reduce { $a || $code->(local $_ = $b) } 0, @bar # any
81 $foo = reduce { $a && $code->(local $_ = $b) } 1, @bar # all
82 $foo = reduce { $a && !$code->(local $_ = $b) } 1, @bar # none
83 $foo = reduce { $a || !$code->(local $_ = $b) } 0, @bar # notall
84 # Note that these implementations do not fully short-circuit
85 If your algorithm requires that "reduce" produce an identity value,
87 then make sure that you always pass that identity value as the first
88 argument to prevent "undef" being returned
89 $foo = reduce { $a + $b } 0, @values; # sum with 0 identity value
91 The above example code blocks also suggest how to use "reduce" to build
93 a more efficient combined version of one of these basic functions and a
94 "map" block. For example, to find the total length of all the strings
95 in a list, we could use
96 $total = sum map { length } @strings;
98 However, this produces a list of temporary integer values as long as
100 the original list of strings, only to reduce it down to a single value
101 again. We can compute the same result more efficiently by using
102 "reduce" with a code block that accumulates lengths by writing this
103 instead as:
104 $total = reduce { $a + length $b } 0, @strings
106 The other scalar-returning list reduction functions are all
108 specialisations of this generic idea.
109 reductions
111 @results = reductions { BLOCK } @list
112 Since version 1.54.
114 Similar to "reduce" except that it also returns the intermediate values
116 along with the final result. As before, $a is set to the first element
117 of the given list, and the "BLOCK" is then called once for remaining
118 item in the list set into $b, with the result being captured for return
119 as well as becoming the new value for $a.
120 The returned list will begin with the initial value for $a, followed by
122 each return value from the block in order. The final value of the
123 result will be identical to what the "reduce" function would have
124 returned given the same block and list.
125 reduce { "$a-$b" } "a".."d" # "a-b-c-d"
127 reductions { "$a-$b" } "a".."d" # "a", "a-b", "a-b-c", "a-b-c-d"
128 any
130 my $bool = any { BLOCK } @list;
131 Since version 1.33.
133 Similar to "grep" in that it evaluates "BLOCK" setting $_ to each
135 element of @list in turn. "any" returns true if any element makes the
136 "BLOCK" return a true value. If "BLOCK" never returns true or @list was
137 empty then it returns false.
138 Many cases of using "grep" in a conditional can be written using "any"
140 instead, as it can short-circuit after the first true result.
141 if( any { length > 10 } @strings ) {
143 # at least one string has more than 10 characters
144 }
145 Note: Due to XS issues the block passed may be able to access the outer
147 @_ directly. This is not intentional and will break under debugger.
148 all
150 my $bool = all { BLOCK } @list;
151 Since version 1.33.
153 Similar to "any", except that it requires all elements of the @list to
155 make the "BLOCK" return true. If any element returns false, then it
156 returns false. If the "BLOCK" never returns false or the @list was
157 empty then it returns true.
158 Note: Due to XS issues the block passed may be able to access the outer
160 @_ directly. This is not intentional and will break under debugger.
161 none
163 notall
164 my $bool = none { BLOCK } @list;
165 my $bool = notall { BLOCK } @list;
167 Since version 1.33.
169 Similar to "any" and "all", but with the return sense inverted. "none"
171 returns true only if no value in the @list causes the "BLOCK" to return
172 true, and "notall" returns true only if not all of the values do.
173 Note: Due to XS issues the block passed may be able to access the outer
175 @_ directly. This is not intentional and will break under debugger.
176 first
178 my $val = first { BLOCK } @list;
179 Similar to "grep" in that it evaluates "BLOCK" setting $_ to each
181 element of @list in turn. "first" returns the first element where the
182 result from "BLOCK" is a true value. If "BLOCK" never returns true or
183 @list was empty then "undef" is returned.
184 $foo = first { defined($_) } @list # first defined value in @list
186 $foo = first { $_ > $value } @list # first value in @list which
187 # is greater than $value
188 max
190 my $num = max @list;
191 Returns the entry in the list with the highest numerical value. If the
193 list is empty then "undef" is returned.
194 $foo = max 1..10 # 10
196 $foo = max 3,9,12 # 12
197 $foo = max @bar, @baz # whatever
198 maxstr
200 my $str = maxstr @list;
201 Similar to "max", but treats all the entries in the list as strings and
203 returns the highest string as defined by the "gt" operator. If the list
204 is empty then "undef" is returned.
205 $foo = maxstr 'A'..'Z' # 'Z'
207 $foo = maxstr "hello","world" # "world"
208 $foo = maxstr @bar, @baz # whatever
209 min
211 my $num = min @list;
212 Similar to "max" but returns the entry in the list with the lowest
214 numerical value. If the list is empty then "undef" is returned.
215 $foo = min 1..10 # 1
217 $foo = min 3,9,12 # 3
218 $foo = min @bar, @baz # whatever
219 minstr
221 my $str = minstr @list;
222 Similar to "min", but treats all the entries in the list as strings and
224 returns the lowest string as defined by the "lt" operator. If the list
225 is empty then "undef" is returned.
226 $foo = minstr 'A'..'Z' # 'A'
228 $foo = minstr "hello","world" # "hello"
229 $foo = minstr @bar, @baz # whatever
230 product
232 my $num = product @list;
233 Since version 1.35.
235 Returns the numerical product of all the elements in @list. If @list is
237 empty then 1 is returned.
238 $foo = product 1..10 # 3628800
240 $foo = product 3,9,12 # 324
241 sum
243 my $num_or_undef = sum @list;
244 Returns the numerical sum of all the elements in @list. For backwards
246 compatibility, if @list is empty then "undef" is returned.
247 $foo = sum 1..10 # 55
249 $foo = sum 3,9,12 # 24
250 $foo = sum @bar, @baz # whatever
251 sum0
253 my $num = sum0 @list;
254 Since version 1.26.
256 Similar to "sum", except this returns 0 when given an empty list,
258 rather than "undef". =head1 KEY/VALUE PAIR LIST FUNCTIONS
259 The following set of functions, all inspired by List::Pairwise, consume
261 an even-sized list of pairs. The pairs may be key/value associations
262 from a hash, or just a list of values. The functions will all preserve
263 the original ordering of the pairs, and will not be confused by
264 multiple pairs having the same "key" value - nor even do they require
265 that the first of each pair be a plain string.
266 NOTE: At the time of writing, the following "pair*" functions that take
268 a block do not modify the value of $_ within the block, and instead
269 operate using the $a and $b globals instead. This has turned out to be
270 a poor design, as it precludes the ability to provide a "pairsort"
271 function. Better would be to pass pair-like objects as 2-element array
272 references in $_, in a style similar to the return value of the "pairs"
273 function. At some future version this behaviour may be added.
274 Until then, users are alerted NOT to rely on the value of $_ remaining
276 unmodified between the outside and the inside of the control block. In
277 particular, the following example is UNSAFE:
278 my @kvlist = ...
280 foreach (qw( some keys here )) {
282 my @items = pairgrep { $a eq $_ } @kvlist;
283 ...
284 }
285 Instead, write this using a lexical variable:
287 foreach my $key (qw( some keys here )) {
289 my @items = pairgrep { $a eq $key } @kvlist;
290 ...
291 }
292 pairs
294 my @pairs = pairs @kvlist;
295 Since version 1.29.
297 A convenient shortcut to operating on even-sized lists of pairs, this
299 function returns a list of "ARRAY" references, each containing two
300 items from the given list. It is a more efficient version of
301 @pairs = pairmap { [ $a, $b ] } @kvlist
303 It is most convenient to use in a "foreach" loop, for example:
305 foreach my $pair ( pairs @kvlist ) {
307 my ( $key, $value ) = @$pair;
308 ...
309 }
310 Since version 1.39 these "ARRAY" references are blessed objects,
312 recognising the two methods "key" and "value". The following code is
313 equivalent:
314 foreach my $pair ( pairs @kvlist ) {
316 my $key = $pair->key;
317 my $value = $pair->value;
318 ...
319 }
320 Since version 1.51 they also have a "TO_JSON" method to ease
322 serialisation.
323 unpairs
325 my @kvlist = unpairs @pairs
326 Since version 1.42.
328 The inverse function to "pairs"; this function takes a list of "ARRAY"
330 references containing two elements each, and returns a flattened list
331 of the two values from each of the pairs, in order. This is notionally
332 equivalent to
333 my @kvlist = map { @{$_}[0,1] } @pairs
335 except that it is implemented more efficiently internally.
337 Specifically, for any input item it will extract exactly two values for
338 the output list; using "undef" if the input array references are short.
339 Between "pairs" and "unpairs", a higher-order list function can be used
341 to operate on the pairs as single scalars; such as the following near-
342 equivalents of the other "pair*" higher-order functions:
343 @kvlist = unpairs grep { FUNC } pairs @kvlist
345 # Like pairgrep, but takes $_ instead of $a and $b
346 @kvlist = unpairs map { FUNC } pairs @kvlist
348 # Like pairmap, but takes $_ instead of $a and $b
349 Note however that these versions will not behave as nicely in scalar
351 context.
352 Finally, this technique can be used to implement a sort on a keyvalue
354 pair list; e.g.:
355 @kvlist = unpairs sort { $a->key cmp $b->key } pairs @kvlist
357 pairkeys
359 my @keys = pairkeys @kvlist;
360 Since version 1.29.
362 A convenient shortcut to operating on even-sized lists of pairs, this
364 function returns a list of the the first values of each of the pairs in
365 the given list. It is a more efficient version of
366 @keys = pairmap { $a } @kvlist
368 pairvalues
370 my @values = pairvalues @kvlist;
371 Since version 1.29.
373 A convenient shortcut to operating on even-sized lists of pairs, this
375 function returns a list of the the second values of each of the pairs
376 in the given list. It is a more efficient version of
377 @values = pairmap { $b } @kvlist
379 pairgrep
381 my @kvlist = pairgrep { BLOCK } @kvlist;
382 my $count = pairgrep { BLOCK } @kvlist;
384 Since version 1.29.
386 Similar to perl's "grep" keyword, but interprets the given list as an
388 even-sized list of pairs. It invokes the "BLOCK" multiple times, in
389 scalar context, with $a and $b set to successive pairs of values from
390 the @kvlist.
391 Returns an even-sized list of those pairs for which the "BLOCK"
393 returned true in list context, or the count of the number of pairs in
394 scalar context. (Note, therefore, in scalar context that it returns a
395 number half the size of the count of items it would have returned in
396 list context).
397 @subset = pairgrep { $a =~ m/^[[:upper:]]+$/ } @kvlist
399 As with "grep" aliasing $_ to list elements, "pairgrep" aliases $a and
401 $b to elements of the given list. Any modifications of it by the code
402 block will be visible to the caller.
403 pairfirst
405 my ( $key, $val ) = pairfirst { BLOCK } @kvlist;
406 my $found = pairfirst { BLOCK } @kvlist;
408 Since version 1.30.
410 Similar to the "first" function, but interprets the given list as an
412 even-sized list of pairs. It invokes the "BLOCK" multiple times, in
413 scalar context, with $a and $b set to successive pairs of values from
414 the @kvlist.
415 Returns the first pair of values from the list for which the "BLOCK"
417 returned true in list context, or an empty list of no such pair was
418 found. In scalar context it returns a simple boolean value, rather than
419 either the key or the value found.
420 ( $key, $value ) = pairfirst { $a =~ m/^[[:upper:]]+$/ } @kvlist
422 As with "grep" aliasing $_ to list elements, "pairfirst" aliases $a and
424 $b to elements of the given list. Any modifications of it by the code
425 block will be visible to the caller.
426 pairmap
428 my @list = pairmap { BLOCK } @kvlist;
429 my $count = pairmap { BLOCK } @kvlist;
431 Since version 1.29.
433 Similar to perl's "map" keyword, but interprets the given list as an
435 even-sized list of pairs. It invokes the "BLOCK" multiple times, in
436 list context, with $a and $b set to successive pairs of values from the
437 @kvlist.
438 Returns the concatenation of all the values returned by the "BLOCK" in
440 list context, or the count of the number of items that would have been
441 returned in scalar context.
442 @result = pairmap { "The key $a has value $b" } @kvlist
444 As with "map" aliasing $_ to list elements, "pairmap" aliases $a and $b
446 to elements of the given list. Any modifications of it by the code
447 block will be visible to the caller.
448 See "KNOWN BUGS" for a known-bug with "pairmap", and a workaround.
450
452 shuffle
453 my @values = shuffle @values;
454 Returns the values of the input in a random order
456 @cards = shuffle 0..51 # 0..51 in a random order
458 This function is affected by the $RAND variable.
460 sample
462 my @items = sample $count, @values
463 Since version 1.54.
465 Randomly select the given number of elements from the input list. Any
467 given position in the input list will be selected at most once.
468 If there are fewer than $count items in the list then the function will
470 return once all of them have been randomly selected; effectively the
471 function behaves similarly to "shuffle".
472 This function is affected by the $RAND variable.
474 uniq
476 my @subset = uniq @values
477 Since version 1.45.
479 Filters a list of values to remove subsequent duplicates, as judged by
481 a DWIM-ish string equality or "undef" test. Preserves the order of
482 unique elements, and retains the first value of any duplicate set.
483 my $count = uniq @values
485 In scalar context, returns the number of elements that would have been
487 returned as a list.
488 The "undef" value is treated by this function as distinct from the
490 empty string, and no warning will be produced. It is left as-is in the
491 returned list. Subsequent "undef" values are still considered identical
492 to the first, and will be removed.
493 uniqnum
495 my @subset = uniqnum @values
496 Since version 1.44.
498 Filters a list of values to remove subsequent duplicates, as judged by
500 a numerical equality test. Preserves the order of unique elements, and
501 retains the first value of any duplicate set.
502 my $count = uniqnum @values
504 In scalar context, returns the number of elements that would have been
506 returned as a list.
507 Note that "undef" is treated much as other numerical operations treat
509 it; it compares equal to zero but additionally produces a warning if
510 such warnings are enabled ("use warnings 'uninitialized';"). In
511 addition, an "undef" in the returned list is coerced into a numerical
512 zero, so that the entire list of values returned by "uniqnum" are well-
513 behaved as numbers.
514 Note also that multiple IEEE "NaN" values are treated as duplicates of
516 each other, regardless of any differences in their payloads, and
517 despite the fact that "0+'NaN' == 0+'NaN'" yields false.
518 uniqstr
520 my @subset = uniqstr @values
521 Since version 1.45.
523 Filters a list of values to remove subsequent duplicates, as judged by
525 a string equality test. Preserves the order of unique elements, and
526 retains the first value of any duplicate set.
527 my $count = uniqstr @values
529 In scalar context, returns the number of elements that would have been
531 returned as a list.
532 Note that "undef" is treated much as other string operations treat it;
534 it compares equal to the empty string but additionally produces a
535 warning if such warnings are enabled ("use warnings 'uninitialized';").
536 In addition, an "undef" in the returned list is coerced into an empty
537 string, so that the entire list of values returned by "uniqstr" are
538 well-behaved as strings.
539 head
541 my @values = head $size, @list;
542 Since version 1.50.
544 Returns the first $size elements from @list. If $size is negative,
546 returns all but the last $size elements from @list.
547 @result = head 2, qw( foo bar baz );
549 # foo, bar
550 @result = head -2, qw( foo bar baz );
552 # foo
553 tail
555 my @values = tail $size, @list;
556 Since version 1.50.
558 Returns the last $size elements from @list. If $size is negative,
560 returns all but the first $size elements from @list.
561 @result = tail 2, qw( foo bar baz );
563 # bar, baz
564 @result = tail -2, qw( foo bar baz );
566 # baz
567
569 Junctions
570 Treatment of an empty list
571 There are two schools of thought for how to evaluate a junction on an
573 empty list:
574 · Reduction to an identity (boolean)
576 · Result is undefined (three-valued)
578 In the first case, the result of the junction applied to the empty list
580 is determined by a mathematical reduction to an identity depending on
581 whether the underlying comparison is "or" or "and". Conceptually:
582 "any are true" "all are true"
584 -------------- --------------
585 2 elements: A || B || 0 A && B && 1
586 1 element: A || 0 A && 1
587 0 elements: 0 1
588 In the second case, three-value logic is desired, in which a junction
590 applied to an empty list returns "undef" rather than true or false
591 Junctions with a "_u" suffix implement three-valued logic. Those
593 without are boolean.
594 all BLOCK LIST
596 all_u BLOCK LIST
598 Returns a true value if all items in LIST meet the criterion given
600 through BLOCK. Sets $_ for each item in LIST in turn:
601 print "All values are non-negative"
603 if all { $_ >= 0 } ($x, $y, $z);
604 For an empty LIST, "all" returns true (i.e. no values failed the
606 condition) and "all_u" returns "undef".
607 Thus, "all_u(@list)" is equivalent to "@list ? all(@list) : undef".
609 Note: because Perl treats "undef" as false, you must check the return
611 value of "all_u" with "defined" or you will get the opposite result of
612 what you expect.
613 any BLOCK LIST
615 any_u BLOCK LIST
617 Returns a true value if any item in LIST meets the criterion given
619 through BLOCK. Sets $_ for each item in LIST in turn:
620 print "At least one non-negative value"
622 if any { $_ >= 0 } ($x, $y, $z);
623 For an empty LIST, "any" returns false and "any_u" returns "undef".
625 Thus, "any_u(@list)" is equivalent to "@list ? any(@list) : undef".
627 none BLOCK LIST
629 none_u BLOCK LIST
631 Logically the negation of "any". Returns a true value if no item in
633 LIST meets the criterion given through BLOCK. Sets $_ for each item in
634 LIST in turn:
635 print "No non-negative values"
637 if none { $_ >= 0 } ($x, $y, $z);
638 For an empty LIST, "none" returns true (i.e. no values failed the
640 condition) and "none_u" returns "undef".
641 Thus, "none_u(@list)" is equivalent to "@list ? none(@list) : undef".
643 Note: because Perl treats "undef" as false, you must check the return
645 value of "none_u" with "defined" or you will get the opposite result of
646 what you expect.
647 notall BLOCK LIST
649 notall_u BLOCK LIST
651 Logically the negation of "all". Returns a true value if not all items
653 in LIST meet the criterion given through BLOCK. Sets $_ for each item
654 in LIST in turn:
655 print "Not all values are non-negative"
657 if notall { $_ >= 0 } ($x, $y, $z);
658 For an empty LIST, "notall" returns false and "notall_u" returns
660 "undef".
661 Thus, "notall_u(@list)" is equivalent to "@list ? notall(@list) :
663 undef".
664 one BLOCK LIST
666 one_u BLOCK LIST
668 Returns a true value if precisely one item in LIST meets the criterion
670 given through BLOCK. Sets $_ for each item in LIST in turn:
671 print "Precisely one value defined"
673 if one { defined($_) } @list;
674 Returns false otherwise.
676 For an empty LIST, "one" returns false and "one_u" returns "undef".
678 The expression "one BLOCK LIST" is almost equivalent to "1 == true
680 BLOCK LIST", except for short-cutting. Evaluation of BLOCK will
681 immediately stop at the second true value.
682 Transformation
684 apply BLOCK LIST
685 Makes a copy of the list and then passes each element from the copy to
687 the BLOCK. Any changes or assignments to $_ in the BLOCK will only
688 affect the elements of the new list. However, if $_ is a reference then
689 changes to the referenced value will be seen in both the original and
690 new list.
691 This function is similar to "map" but will not modify the elements of
693 the input list:
694 my @list = (1 .. 4);
696 my @mult = apply { $_ *= 2 } @list;
697 print "\@list = @list\n";
698 print "\@mult = @mult\n";
699 __END__
700 @list = 1 2 3 4
701 @mult = 2 4 6 8
702 Think of it as syntactic sugar for
704 for (my @mult = @list) { $_ *= 2 }
706 Note that you must alter $_ directly inside BLOCK in order for changes
708 to make effect. New value returned from the BLOCK are ignored:
709 # @new is identical to @list.
711 my @new = apply { $_ * 2 } @list;
712 # @new is different from @list
714 my @new = apply { $_ =* 2 } @list;
715 insert_after BLOCK VALUE LIST
717 Inserts VALUE after the first item in LIST for which the criterion in
719 BLOCK is true. Sets $_ for each item in LIST in turn.
720 my @list = qw/This is a list/;
722 insert_after { $_ eq "a" } "longer" => @list;
723 print "@list";
724 __END__
725 This is a longer list
726 insert_after_string STRING VALUE LIST
728 Inserts VALUE after the first item in LIST which is equal to STRING.
730 my @list = qw/This is a list/;
732 insert_after_string "a", "longer" => @list;
733 print "@list";
734 __END__
735 This is a longer list
736 pairwise BLOCK ARRAY1 ARRAY2
738 Evaluates BLOCK for each pair of elements in ARRAY1 and ARRAY2 and
740 returns a new list consisting of BLOCK's return values. The two
741 elements are set to $a and $b. Note that those two are aliases to the
742 original value so changing them will modify the input arrays.
743 @a = (1 .. 5);
745 @b = (11 .. 15);
746 @x = pairwise { $a + $b } @a, @b; # returns 12, 14, 16, 18, 20
747 # mesh with pairwise
749 @a = qw/a b c/;
750 @b = qw/1 2 3/;
751 @x = pairwise { ($a, $b) } @a, @b; # returns a, 1, b, 2, c, 3
752 mesh ARRAY1 ARRAY2 [ ARRAY3 ... ]
754 zip ARRAY1 ARRAY2 [ ARRAY3 ... ]
756 Returns a list consisting of the first elements of each array, then the
758 second, then the third, etc, until all arrays are exhausted.
759 Examples:
761 @x = qw/a b c d/;
763 @y = qw/1 2 3 4/;
764 @z = mesh @x, @y; # returns a, 1, b, 2, c, 3, d, 4
765 @a = ('x');
767 @b = ('1', '2');
768 @c = qw/zip zap zot/;
769 @d = mesh @a, @b, @c; # x, 1, zip, undef, 2, zap, undef, undef, zot
770 "zip" is an alias for "mesh".
772 uniq LIST
774 distinct LIST
776 Returns a new list by stripping duplicate values in LIST by comparing
778 the values as hash keys, except that undef is considered separate from
779 ''. The order of elements in the returned list is the same as in LIST.
780 In scalar context, returns the number of unique elements in LIST.
781 my @x = uniq 1, 1, 2, 2, 3, 5, 3, 4; # returns 1 2 3 5 4
783 my $x = uniq 1, 1, 2, 2, 3, 5, 3, 4; # returns 5
784 # returns "Mike", "Michael", "Richard", "Rick"
785 my @n = distinct "Mike", "Michael", "Richard", "Rick", "Michael", "Rick"
786 # returns '', undef, 'S1', A5'
787 my @s = distinct '', undef, 'S1', 'A5'
788 # returns '', undef, 'S1', A5'
789 my @w = uniq undef, '', 'S1', 'A5'
790 "distinct" is an alias for "uniq".
792 RT#49800 can be used to give feedback about this behavior.
794 singleton
796 Returns a new list by stripping values in LIST occurring more than once
798 by comparing the values as hash keys, except that undef is considered
799 separate from ''. The order of elements in the returned list is the
800 same as in LIST. In scalar context, returns the number of elements
801 occurring only once in LIST.
802 my @x = singleton 1,1,2,2,3,4,5 # returns 3 4 5
804 Partitioning
806 after BLOCK LIST
807 Returns a list of the values of LIST after (and not including) the
809 point where BLOCK returns a true value. Sets $_ for each element in
810 LIST in turn.
811 @x = after { $_ % 5 == 0 } (1..9); # returns 6, 7, 8, 9
813 after_incl BLOCK LIST
815 Same as "after" but also includes the element for which BLOCK is true.
817 before BLOCK LIST
819 Returns a list of values of LIST up to (and not including) the point
821 where BLOCK returns a true value. Sets $_ for each element in LIST in
822 turn.
823 before_incl BLOCK LIST
825 Same as "before" but also includes the element for which BLOCK is true.
827 part BLOCK LIST
829 Partitions LIST based on the return value of BLOCK which denotes into
831 which partition the current value is put.
832 Returns a list of the partitions thusly created. Each partition created
834 is a reference to an array.
835 my $i = 0;
837 my @part = part { $i++ % 2 } 1 .. 8; # returns [1, 3, 5, 7], [2, 4, 6, 8]
838 You can have a sparse list of partitions as well where non-set
840 partitions will be undef:
841 my @part = part { 2 } 1 .. 10; # returns undef, undef, [ 1 .. 10 ]
843 Be careful with negative values, though:
845 my @part = part { -1 } 1 .. 10;
847 __END__
848 Modification of non-creatable array value attempted, subscript -1 ...
849 Negative values are only ok when they refer to a partition previously
851 created:
852 my @idx = ( 0, 1, -1 );
854 my $i = 0;
855 my @part = part { $idx[$i++ % 3] } 1 .. 8; # [1, 4, 7], [2, 3, 5, 6, 8]
856 Iteration
858 each_array ARRAY1 ARRAY2 ...
859 Creates an array iterator to return the elements of the list of arrays
861 ARRAY1, ARRAY2 throughout ARRAYn in turn. That is, the first time it
862 is called, it returns the first element of each array. The next time,
863 it returns the second elements. And so on, until all elements are
864 exhausted.
865 This is useful for looping over more than one array at once:
867 my $ea = each_array(@a, @b, @c);
869 while ( my ($a, $b, $c) = $ea->() ) { .... }
870 The iterator returns the empty list when it reached the end of all
872 arrays.
873 If the iterator is passed an argument of '"index"', then it returns the
875 index of the last fetched set of values, as a scalar.
876 each_arrayref LIST
878 Like each_array, but the arguments are references to arrays, not the
880 plain arrays.
881 natatime EXPR, LIST
883 Creates an array iterator, for looping over an array in chunks of $n
885 items at a time. (n at a time, get it?). An example is probably a
886 better explanation than I could give in words.
887 Example:
889 my @x = ('a' .. 'g');
891 my $it = natatime 3, @x;
892 while (my @vals = $it->())
893 {
894 print "@vals\n";
895 }
896 This prints
898 a b c
900 d e f
901 g
902 Searching
904 bsearch BLOCK LIST
905 Performs a binary search on LIST which must be a sorted list of values.
907 BLOCK must return a negative value if the current element (stored in
908 $_) is smaller, a positive value if it is bigger and zero if it
909 matches.
910 Returns a boolean value in scalar context. In list context, it returns
912 the element if it was found, otherwise the empty list.
913 bsearchidx BLOCK LIST
915 bsearch_index BLOCK LIST
917 Performs a binary search on LIST which must be a sorted list of values.
919 BLOCK must return a negative value if the current element (stored in
920 $_) is smaller, a positive value if it is bigger and zero if it
921 matches.
922 Returns the index of found element, otherwise "-1".
924 "bsearch_index" is an alias for "bsearchidx".
926 firstval BLOCK LIST
928 first_value BLOCK LIST
930 Returns the first element in LIST for which BLOCK evaluates to true.
932 Each element of LIST is set to $_ in turn. Returns "undef" if no such
933 element has been found.
934 "first_value" is an alias for "firstval".
936 onlyval BLOCK LIST
938 only_value BLOCK LIST
940 Returns the only element in LIST for which BLOCK evaluates to true.
942 Sets $_ for each item in LIST in turn. Returns "undef" if no such
943 element has been found.
944 "only_value" is an alias for "onlyval".
946 lastval BLOCK LIST
948 last_value BLOCK LIST
950 Returns the last value in LIST for which BLOCK evaluates to true. Each
952 element of LIST is set to $_ in turn. Returns "undef" if no such
953 element has been found.
954 "last_value" is an alias for "lastval".
956 firstres BLOCK LIST
958 first_result BLOCK LIST
960 Returns the result of BLOCK for the first element in LIST for which
962 BLOCK evaluates to true. Each element of LIST is set to $_ in turn.
963 Returns "undef" if no such element has been found.
964 "first_result" is an alias for "firstres".
966 onlyres BLOCK LIST
968 only_result BLOCK LIST
970 Returns the result of BLOCK for the first element in LIST for which
972 BLOCK evaluates to true. Sets $_ for each item in LIST in turn. Returns
973 "undef" if no such element has been found.
974 "only_result" is an alias for "onlyres".
976 lastres BLOCK LIST
978 last_result BLOCK LIST
980 Returns the result of BLOCK for the last element in LIST for which
982 BLOCK evaluates to true. Each element of LIST is set to $_ in turn.
983 Returns "undef" if no such element has been found.
984 "last_result" is an alias for "lastres".
986 indexes BLOCK LIST
988 Evaluates BLOCK for each element in LIST (assigned to $_) and returns a
990 list of the indices of those elements for which BLOCK returned a true
991 value. This is just like "grep" only that it returns indices instead of
992 values:
993 @x = indexes { $_ % 2 == 0 } (1..10); # returns 1, 3, 5, 7, 9
995 firstidx BLOCK LIST
997 first_index BLOCK LIST
999 Returns the index of the first element in LIST for which the criterion
1001 in BLOCK is true. Sets $_ for each item in LIST in turn:
1002 my @list = (1, 4, 3, 2, 4, 6);
1004 printf "item with index %i in list is 4", firstidx { $_ == 4 } @list;
1005 __END__
1006 item with index 1 in list is 4
1007 Returns "-1" if no such item could be found.
1009 "first_index" is an alias for "firstidx".
1011 onlyidx BLOCK LIST
1013 only_index BLOCK LIST
1015 Returns the index of the only element in LIST for which the criterion
1017 in BLOCK is true. Sets $_ for each item in LIST in turn:
1018 my @list = (1, 3, 4, 3, 2, 4);
1020 printf "uniqe index of item 2 in list is %i", onlyidx { $_ == 2 } @list;
1021 __END__
1022 unique index of item 2 in list is 4
1023 Returns "-1" if either no such item or more than one of these has been
1025 found.
1026 "only_index" is an alias for "onlyidx".
1028 lastidx BLOCK LIST
1030 last_index BLOCK LIST
1032 Returns the index of the last element in LIST for which the criterion
1034 in BLOCK is true. Sets $_ for each item in LIST in turn:
1035 my @list = (1, 4, 3, 2, 4, 6);
1037 printf "item with index %i in list is 4", lastidx { $_ == 4 } @list;
1038 __END__
1039 item with index 4 in list is 4
1040 Returns "-1" if no such item could be found.
1042 "last_index" is an alias for "lastidx".
1044 Sorting
1046 sort_by BLOCK LIST
1047 Returns the list of values sorted according to the string values
1049 returned by the KEYFUNC block or function. A typical use of this may be
1050 to sort objects according to the string value of some accessor, such as
1051 sort_by { $_->name } @people
1053 The key function is called in scalar context, being passed each value
1055 in turn as both $_ and the only argument in the parameters, @_. The
1056 values are then sorted according to string comparisons on the values
1057 returned. This is equivalent to
1058 sort { $a->name cmp $b->name } @people
1060 except that it guarantees the name accessor will be executed only once
1062 per value. One interesting use-case is to sort strings which may have
1063 numbers embedded in them "naturally", rather than lexically.
1064 sort_by { s/(\d+)/sprintf "%09d", $1/eg; $_ } @strings
1066 This sorts strings by generating sort keys which zero-pad the embedded
1068 numbers to some level (9 digits in this case), helping to ensure the
1069 lexical sort puts them in the correct order.
1070 nsort_by BLOCK LIST
1072 Similar to sort_by but compares its key values numerically.
1074 Counting and calculation
1076 true BLOCK LIST
1077 Counts the number of elements in LIST for which the criterion in BLOCK
1079 is true. Sets $_ for each item in LIST in turn:
1080 printf "%i item(s) are defined", true { defined($_) } @list;
1082 false BLOCK LIST
1084 Counts the number of elements in LIST for which the criterion in BLOCK
1086 is false. Sets $_ for each item in LIST in turn:
1087 printf "%i item(s) are not defined", false { defined($_) } @list;
1089 minmax LIST
1091 Calculates the minimum and maximum of LIST and returns a two element
1093 list with the first element being the minimum and the second the
1094 maximum. Returns the empty list if LIST was empty.
1095 The "minmax" algorithm differs from a naive iteration over the list
1097 where each element is compared to two values being the so far
1098 calculated min and max value in that it only requires 3n/2 - 2
1099 comparisons. Thus it is the most efficient possible algorithm.
1100 However, the Perl implementation of it has some overhead simply due to
1102 the fact that there are more lines of Perl code involved. Therefore,
1103 LIST needs to be fairly big in order for "minmax" to win over a naive
1104 implementation. This limitation does not apply to the XS version.
1105 mode LIST
1107 Calculates the most common items in the list and returns them as a
1109 list. This is effectively done by string comparisons, so references
1110 will be stringified. If they implement string overloading, this will be
1111 used.
1112 If more than one item appears the same number of times in the list, all
1114 such items will be returned. For example, the mode of a unique list is
1115 the list itself.
1116 This function returns a list in list context. In scalar context it
1118 returns a count indicating the number of modes in the list.
1119
1121 All functions added since version 0.04 unless otherwise stated, as the
1122 original names for earlier versions were renamed.
1123 sort_by
1125 @vals = sort_by { KEYFUNC } @vals
1126 Returns the list of values sorted according to the string values
1128 returned by the "KEYFUNC" block or function. A typical use of this may
1129 be to sort objects according to the string value of some accessor, such
1130 as
1131 sort_by { $_->name } @people
1133 The key function is called in scalar context, being passed each value
1135 in turn as both $_ and the only argument in the parameters, @_. The
1136 values are then sorted according to string comparisons on the values
1137 returned.
1138 This is equivalent to
1140 sort { $a->name cmp $b->name } @people
1142 except that it guarantees the "name" accessor will be executed only
1144 once per value.
1145 One interesting use-case is to sort strings which may have numbers
1147 embedded in them "naturally", rather than lexically.
1148 sort_by { s/(\d+)/sprintf "%09d", $1/eg; $_ } @strings
1150 This sorts strings by generating sort keys which zero-pad the embedded
1152 numbers to some level (9 digits in this case), helping to ensure the
1153 lexical sort puts them in the correct order.
1154 nsort_by
1156 @vals = nsort_by { KEYFUNC } @vals
1157 Similar to "sort_by" but compares its key values numerically.
1159 rev_sort_by
1161 rev_nsort_by
1162 @vals = rev_sort_by { KEYFUNC } @vals
1163 @vals = rev_nsort_by { KEYFUNC } @vals
1165 Since version 0.06.
1167 Similar to "sort_by" and "nsort_by" but returns the list in the reverse
1169 order. Equivalent to
1170 @vals = reverse sort_by { KEYFUNC } @vals
1172 except that these functions are slightly more efficient because they
1174 avoid the final "reverse" operation.
1175 max_by
1177 $optimal = max_by { KEYFUNC } @vals
1178 @optimal = max_by { KEYFUNC } @vals
1180 Returns the (first) value from @vals that gives the numerically largest
1182 result from the key function.
1183 my $tallest = max_by { $_->height } @people
1185 use File::stat qw( stat );
1187 my $newest = max_by { stat($_)->mtime } @files;
1188 In scalar context, the first maximal value is returned. In list
1190 context, a list of all the maximal values is returned. This may be used
1191 to obtain positions other than the first, if order is significant.
1192 If called on an empty list, an empty list is returned.
1194 For symmetry with the "nsort_by" function, this is also provided under
1196 the name "nmax_by" since it behaves numerically.
1197 min_by
1199 $optimal = min_by { KEYFUNC } @vals
1200 @optimal = min_by { KEYFUNC } @vals
1202 Similar to "max_by" but returns values which give the numerically
1204 smallest result from the key function. Also provided as "nmin_by"
1205 minmax_by
1207 ( $minimal, $maximal ) = minmax_by { KEYFUNC } @vals
1208 Since version 0.11.
1210 Similar to calling both "min_by" and "max_by" with the same key
1212 function on the same list. This version is more efficient than calling
1213 the two other functions individually, as it has less work to perform
1214 overall. In the case of ties, only the first optimal element found in
1215 each case is returned. Also provided as "nminmax_by".
1216 uniq_by
1218 @vals = uniq_by { KEYFUNC } @vals
1219 Returns a list of the subset of values for which the key function block
1221 returns unique values. The first value yielding a particular key is
1222 chosen, subsequent values are rejected.
1223 my @some_fruit = uniq_by { $_->colour } @fruit;
1225 To select instead the last value per key, reverse the input list. If
1227 the order of the results is significant, don't forget to reverse the
1228 result as well:
1229 my @some_fruit = reverse uniq_by { $_->colour } reverse @fruit;
1231 Because the values returned by the key function are used as hash keys,
1233 they ought to either be strings, or at least well-behaved as strings
1234 (such as numbers, or object references which overload stringification
1235 in a suitable manner).
1236 partition_by
1238 %parts = partition_by { KEYFUNC } @vals
1239 Returns a key/value list of ARRAY refs containing all the original
1241 values distributed according to the result of the key function block.
1242 Each value will be an ARRAY ref containing all the values which
1243 returned the string from the key function, in their original order.
1244 my %balls_by_colour = partition_by { $_->colour } @balls;
1246 Because the values returned by the key function are used as hash keys,
1248 they ought to either be strings, or at least well-behaved as strings
1249 (such as numbers, or object references which overload stringification
1250 in a suitable manner).
1251 count_by
1253 %counts = count_by { KEYFUNC } @vals
1254 Since version 0.07.
1256 Returns a key/value list of integers, giving the number of times the
1258 key function block returned the key, for each value in the list.
1259 my %count_of_balls = count_by { $_->colour } @balls;
1261 Because the values returned by the key function are used as hash keys,
1263 they ought to either be strings, or at least well-behaved as strings
1264 (such as numbers, or object references which overload stringification
1265 in a suitable manner).
1266 zip_by
1268 @vals = zip_by { ITEMFUNC } \@arr0, \@arr1, \@arr2,...
1269 Returns a list of each of the values returned by the function block,
1271 when invoked with values from across each each of the given ARRAY
1272 references. Each value in the returned list will be the result of the
1273 function having been invoked with arguments at that position, from
1274 across each of the arrays given.
1275 my @transposition = zip_by { [ @_ ] } @matrix;
1277 my @names = zip_by { "$_[1], $_[0]" } \@firstnames, \@surnames;
1279 print zip_by { "$_[0] => $_[1]\n" } [ keys %hash ], [ values %hash ];
1281 If some of the arrays are shorter than others, the function will behave
1283 as if they had "undef" in the trailing positions. The following two
1284 lines are equivalent:
1285 zip_by { f(@_) } [ 1, 2, 3 ], [ "a", "b" ]
1287 f( 1, "a" ), f( 2, "b" ), f( 3, undef )
1288 The item function is called by "map", so if it returns a list, the
1290 entire list is included in the result. This can be useful for example,
1291 for generating a hash from two separate lists of keys and values
1292 my %nums = zip_by { @_ } [qw( one two three )], [ 1, 2, 3 ];
1294 # %nums = ( one => 1, two => 2, three => 3 )
1295 (A function having this behaviour is sometimes called "zipWith", e.g.
1297 in Haskell, but that name would not fit the naming scheme used by this
1298 module).
1299 unzip_by
1301 $arr0, $arr1, $arr2, ... = unzip_by { ITEMFUNC } @vals
1302 Since version 0.09.
1304 Returns a list of ARRAY references containing the values returned by
1306 the function block, when invoked for each of the values given in the
1307 input list. Each of the returned ARRAY references will contain the
1308 values returned at that corresponding position by the function block.
1309 That is, the first returned ARRAY reference will contain all the values
1310 returned in the first position by the function block, the second will
1311 contain all the values from the second position, and so on.
1312 my ( $firstnames, $lastnames ) = unzip_by { m/^(.*?) (.*)$/ } @names;
1314 If the function returns lists of differing lengths, the result will be
1316 padded with "undef" in the missing elements.
1317 This function is an inverse of "zip_by", if given a corresponding
1319 inverse function.
1320 extract_by
1322 @vals = extract_by { SELECTFUNC } @arr
1323 Since version 0.05.
1325 Removes elements from the referenced array on which the selection
1327 function returns true, and returns a list containing those elements.
1328 This function is similar to "grep", except that it modifies the
1329 referenced array to remove the selected values from it, leaving only
1330 the unselected ones.
1331 my @red_balls = extract_by { $_->color eq "red" } @balls;
1333 # Now there are no red balls in the @balls array
1335 This function modifies a real array, unlike most of the other functions
1337 in this module. Because of this, it requires a real array, not just a
1338 list.
1339 This function is implemented by invoking "splice" on the array, not by
1341 constructing a new list and assigning it. One result of this is that
1342 weak references will not be disturbed.
1343 extract_by { !defined $_ } @refs;
1345 will leave weak references weakened in the @refs array, whereas
1347 @refs = grep { defined $_ } @refs;
1349 will strengthen them all again.
1351 extract_first_by
1353 $val = extract_first_by { SELECTFUNC } @arr
1354 Since version 0.10.
1356 A hybrid between "extract_by" and "List::Util::first". Removes the
1358 first element from the referenced array on which the selection function
1359 returns true, returning it.
1360 As with "extract_by", this function requires a real array and not just
1362 a list, and is also implemented using "splice" so that weak references
1363 are not disturbed.
1364 If this function fails to find a matching element, it will return an
1366 empty list in list context. This allows a caller to distinguish the
1367 case between no matching element, and the first matching element being
1368 "undef".
1369 weighted_shuffle_by
1371 @vals = weighted_shuffle_by { WEIGHTFUNC } @vals
1372 Since version 0.07.
1374 Returns the list of values shuffled into a random order. The
1376 randomisation is not uniform, but weighted by the value returned by the
1377 "WEIGHTFUNC". The probabilty of each item being returned first will be
1378 distributed with the distribution of the weights, and so on recursively
1379 for the remaining items.
1380 bundle_by
1382 @vals = bundle_by { BLOCKFUNC } $number, @vals
1383 Since version 0.07.
1385 Similar to a regular "map" functional, returns a list of the values
1387 returned by "BLOCKFUNC". Values from the input list are given to the
1388 block function in bundles of $number.
1389 If given a list of values whose length does not evenly divide by
1391 $number, the final call will be passed fewer elements than the others.
1392
1394 This module exports nothing by default. You can import functions by
1395 name, or get everything with the ":all" tag.
1396
1398 List::Util, List::SomeUtils and List::UtilsBy, obviously.
1399 Also see "Util::Any", which unifies many more util modules, and also
1401 lets you rename functions as part of the import.
1402
1404 Please report any bugs or feature requests to
1405 "bug-list-allutils@rt.cpan.org", or through the web interface at
1406 <http://rt.cpan.org>. I will be notified, and then you'll
1407 automatically be notified of progress on your bug as I make changes.
1408 Bugs may be submitted at
1410 <https://github.com/houseabsolute/List-AllUtils/issues>.
1411 I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
1413
1415 The source code repository for List-AllUtils can be found at
1416 <https://github.com/houseabsolute/List-AllUtils>.
1417
1419 If you'd like to thank me for the work I've done on this module, please
1420 consider making a "donation" to me via PayPal. I spend a lot of free
1421 time creating free software, and would appreciate any support you'd
1422 care to offer.
1423 Please note that I am not suggesting that you must do this in order for
1425 me to continue working on this particular software. I will continue to
1426 do so, inasmuch as I have in the past, for as long as it interests me.
1427 Similarly, a donation made in this way will probably not make me work
1429 on this software much more, unless I get so many donations that I can
1430 consider working on free software full time (let's all have a chuckle
1431 at that together).
1432 To donate, log into PayPal and send money to autarch@urth.org, or use
1434 the button at <https://www.urth.org/fs-donation.html>.
1435
1437 Dave Rolsky <autarch@urth.org>
1438
1440 · Andy Jack <github@veracity.ca>
1441 · Dave Jacoby <jacoby.david@gmail.com>
1443 · Karen Etheridge <ether@cpan.org>
1445 · Olaf Alders <olaf@wundersolutions.com>
1447 · Ricardo Signes <rjbs@cpan.org>
1449 · Yanick Champoux <yanick@babyl.dyndns.org>
1451
1453 This software is Copyright (c) 2020 by Dave Rolsky.
1454 This is free software, licensed under:
1456 The Artistic License 2.0 (GPL Compatible)
1458 The full text of the license can be found in the LICENSE file included
1460 with this distribution.
1461perl v5.32.0 2020-09-07 List::AllUtils(3)