← Index
NYTProf Performance Profile   « line view »
For split.pl
  Run on Thu Apr 20 02:05:47 2023
Reported on Thu Apr 20 18:31:09 2023

Filename/home/hejohns/perl5/lib/perl5/x86_64-linux-gnu-thread-multi/List/Util.pm
StatementsExecuted 15 statements in 604µs
Subroutines
Calls P F Exclusive
Time		 Inclusive
Time		 Subroutine
1118µs9µsList::Util::::BEGIN@9 List::Util::BEGIN@9
1114µs9µsList::Util::::BEGIN@35 List::Util::BEGIN@35
1113µs16µsList::Util::::BEGIN@10 List::Util::BEGIN@10
0000s0sList::Util::_Pair::::TO_JSONList::Util::_Pair::TO_JSON
0000s0sList::Util::_Pair::::keyList::Util::_Pair::key
0000s0sList::Util::_Pair::::valueList::Util::_Pair::value
0000s0sList::Util::::import List::Util::import
Call graph for these subroutines as a Graphviz dot language file.
Line State
ments		 Time
on line		 Calls Time
in subs		 Code
1# Copyright (c) 1997-2009 Graham Barr <gbarr@pobox.com>. All rights reserved.
2# This program is free software; you can redistribute it and/or
3# modify it under the same terms as Perl itself.
4#
5# Maintained since 2013 by Paul Evans <leonerd@leonerd.org.uk>
6
7package List::Util;
8
9217µs210µs
# spent 9µs (8+1) within List::Util::BEGIN@9 which was called: # once (8µs+1µs) by File::Temp::BEGIN@153 at line 9
use strict;
# spent 9µs making 1 call to List::Util::BEGIN@9 # spent 1µs making 1 call to strict::import
10280µs229µs
# spent 16µs (3+13) within List::Util::BEGIN@10 which was called: # once (3µs+13µs) by File::Temp::BEGIN@153 at line 10
use warnings;
# spent 16µs making 1 call to List::Util::BEGIN@10 # spent 13µs making 1 call to warnings::import
111300nsrequire Exporter;
12
1316µsour @ISA = qw(Exporter);
1412µsour @EXPORT_OK = qw(
15 all any first min max minstr maxstr none notall product reduce reductions sum sum0
16 sample shuffle uniq uniqint uniqnum uniqstr zip zip_longest zip_shortest mesh mesh_longest mesh_shortest
17 head tail pairs unpairs pairkeys pairvalues pairmap pairgrep pairfirst
18);
191100nsour $VERSION = "1.63";
201100nsour $XS_VERSION = $VERSION;
211500ns$VERSION =~ tr/_//d;
22
231200nsrequire XSLoader;
241158µs1154µsXSLoader::load('List::Util', $XS_VERSION);
# spent 154µs making 1 call to XSLoader::load
25
26# Used by shuffle()
27our $RAND;
28
29sub import
30{
31 my $pkg = caller;
32
33 # (RT88848) Touch the caller's $a and $b, to avoid the warning of
34 # Name "main::a" used only once: possible typo" warning
352334µs213µs
# spent 9µs (4+5) within List::Util::BEGIN@35 which was called: # once (4µs+5µs) by File::Temp::BEGIN@153 at line 35
no strict 'refs';
# spent 9µs making 1 call to List::Util::BEGIN@35 # spent 5µs making 1 call to strict::unimport
36 ${"${pkg}::a"} = ${"${pkg}::a"};
37 ${"${pkg}::b"} = ${"${pkg}::b"};
38
39 goto &Exporter::import;
40}
41
42# For objects returned by pairs()
43sub List::Util::_Pair::key { shift->[0] }
44sub List::Util::_Pair::value { shift->[1] }
45sub List::Util::_Pair::TO_JSON { [ @{+shift} ] }
46
47=head1 NAME
48
49List::Util - A selection of general-utility list subroutines
50
51=head1 SYNOPSIS
52
53 use List::Util qw(
54 reduce any all none notall first reductions
55
56 max maxstr min minstr product sum sum0
57
58 pairs unpairs pairkeys pairvalues pairfirst pairgrep pairmap
59
60 shuffle uniq uniqint uniqnum uniqstr zip mesh
61 );
62
63=head1 DESCRIPTION
64
65C<List::Util> contains a selection of subroutines that people have expressed
66would be nice to have in the perl core, but the usage would not really be high
67enough to warrant the use of a keyword, and the size so small such that being
68individual extensions would be wasteful.
69
70By default C<List::Util> does not export any subroutines.
71
72=cut
73
74=head1 LIST-REDUCTION FUNCTIONS
75
76The following set of functions all apply a given block of code to a list of
77values.
78
79=cut
80
81=head2 reduce
82
83 $result = reduce { BLOCK } @list
84
85Reduces C<@list> by calling C<BLOCK> in a scalar context multiple times,
86setting C<$a> and C<$b> each time. The first call will be with C<$a> and C<$b>
87set to the first two elements of the list, subsequent calls will be done by
88setting C<$a> to the result of the previous call and C<$b> to the next element
89in the list.
90
91Returns the result of the last call to the C<BLOCK>. If C<@list> is empty then
92C<undef> is returned. If C<@list> only contains one element then that element
93is returned and C<BLOCK> is not executed.
94
95The following examples all demonstrate how C<reduce> could be used to implement
96the other list-reduction functions in this module. (They are not in fact
97implemented like this, but instead in a more efficient manner in individual C
98functions).
99
100 $foo = reduce { defined($a) ? $a :
101 $code->(local $_ = $b) ? $b :
102 undef } undef, @list # first
103
104 $foo = reduce { $a > $b ? $a : $b } 1..10 # max
105 $foo = reduce { $a gt $b ? $a : $b } 'A'..'Z' # maxstr
106 $foo = reduce { $a < $b ? $a : $b } 1..10 # min
107 $foo = reduce { $a lt $b ? $a : $b } 'aa'..'zz' # minstr
108 $foo = reduce { $a + $b } 1 .. 10 # sum
109 $foo = reduce { $a . $b } @bar # concat
110
111 $foo = reduce { $a || $code->(local $_ = $b) } 0, @bar # any
112 $foo = reduce { $a && $code->(local $_ = $b) } 1, @bar # all
113 $foo = reduce { $a && !$code->(local $_ = $b) } 1, @bar # none
114 $foo = reduce { $a || !$code->(local $_ = $b) } 0, @bar # notall
115 # Note that these implementations do not fully short-circuit
116
117If your algorithm requires that C<reduce> produce an identity value, then make
118sure that you always pass that identity value as the first argument to prevent
119C<undef> being returned
120
121 $foo = reduce { $a + $b } 0, @values; # sum with 0 identity value
122
123The above example code blocks also suggest how to use C<reduce> to build a
124more efficient combined version of one of these basic functions and a C<map>
125block. For example, to find the total length of all the strings in a list,
126we could use
127
128 $total = sum map { length } @strings;
129
130However, this produces a list of temporary integer values as long as the
131original list of strings, only to reduce it down to a single value again. We
132can compute the same result more efficiently by using C<reduce> with a code
133block that accumulates lengths by writing this instead as:
134
135 $total = reduce { $a + length $b } 0, @strings
136
137The other scalar-returning list reduction functions are all specialisations of
138this generic idea.
139
140=head2 reductions
141
142 @results = reductions { BLOCK } @list
143
144I<Since version 1.54.>
145
146Similar to C<reduce> except that it also returns the intermediate values along
147with the final result. As before, C<$a> is set to the first element of the
148given list, and the C<BLOCK> is then called once for remaining item in the
149list set into C<$b>, with the result being captured for return as well as
150becoming the new value for C<$a>.
151
152The returned list will begin with the initial value for C<$a>, followed by
153each return value from the block in order. The final value of the result will
154be identical to what the C<reduce> function would have returned given the same
155block and list.
156
157 reduce { "$a-$b" } "a".."d" # "a-b-c-d"
158 reductions { "$a-$b" } "a".."d" # "a", "a-b", "a-b-c", "a-b-c-d"
159
160=head2 any
161
162 my $bool = any { BLOCK } @list;
163
164I<Since version 1.33.>
165
166Similar to C<grep> in that it evaluates C<BLOCK> setting C<$_> to each element
167of C<@list> in turn. C<any> returns true if any element makes the C<BLOCK>
168return a true value. If C<BLOCK> never returns true or C<@list> was empty then
169it returns false.
170
171Many cases of using C<grep> in a conditional can be written using C<any>
172instead, as it can short-circuit after the first true result.
173
174 if( any { length > 10 } @strings ) {
175 # at least one string has more than 10 characters
176 }
177
178Note: Due to XS issues the block passed may be able to access the outer @_
179directly. This is not intentional and will break under debugger.
180
181=head2 all
182
183 my $bool = all { BLOCK } @list;
184
185I<Since version 1.33.>
186
187Similar to L</any>, except that it requires all elements of the C<@list> to
188make the C<BLOCK> return true. If any element returns false, then it returns
189false. If the C<BLOCK> never returns false or the C<@list> was empty then it
190returns true.
191
192Note: Due to XS issues the block passed may be able to access the outer @_
193directly. This is not intentional and will break under debugger.
194
195=head2 none
196
197=head2 notall
198
199 my $bool = none { BLOCK } @list;
200
201 my $bool = notall { BLOCK } @list;
202
203I<Since version 1.33.>
204
205Similar to L</any> and L</all>, but with the return sense inverted. C<none>
206returns true only if no value in the C<@list> causes the C<BLOCK> to return
207true, and C<notall> returns true only if not all of the values do.
208
209Note: Due to XS issues the block passed may be able to access the outer @_
210directly. This is not intentional and will break under debugger.
211
212=head2 first
213
214 my $val = first { BLOCK } @list;
215
216Similar to C<grep> in that it evaluates C<BLOCK> setting C<$_> to each element
217of C<@list> in turn. C<first> returns the first element where the result from
218C<BLOCK> is a true value. If C<BLOCK> never returns true or C<@list> was empty
219then C<undef> is returned.
220
221 $foo = first { defined($_) } @list # first defined value in @list
222 $foo = first { $_ > $value } @list # first value in @list which
223 # is greater than $value
224
225=head2 max
226
227 my $num = max @list;
228
229Returns the entry in the list with the highest numerical value. If the list is
230empty then C<undef> is returned.
231
232 $foo = max 1..10 # 10
233 $foo = max 3,9,12 # 12
234 $foo = max @bar, @baz # whatever
235
236=head2 maxstr
237
238 my $str = maxstr @list;
239
240Similar to L</max>, but treats all the entries in the list as strings and
241returns the highest string as defined by the C<gt> operator. If the list is
242empty then C<undef> is returned.
243
244 $foo = maxstr 'A'..'Z' # 'Z'
245 $foo = maxstr "hello","world" # "world"
246 $foo = maxstr @bar, @baz # whatever
247
248=head2 min
249
250 my $num = min @list;
251
252Similar to L</max> but returns the entry in the list with the lowest numerical
253value. If the list is empty then C<undef> is returned.
254
255 $foo = min 1..10 # 1
256 $foo = min 3,9,12 # 3
257 $foo = min @bar, @baz # whatever
258
259=head2 minstr
260
261 my $str = minstr @list;
262
263Similar to L</min>, but treats all the entries in the list as strings and
264returns the lowest string as defined by the C<lt> operator. If the list is
265empty then C<undef> is returned.
266
267 $foo = minstr 'A'..'Z' # 'A'
268 $foo = minstr "hello","world" # "hello"
269 $foo = minstr @bar, @baz # whatever
270
271=head2 product
272
273 my $num = product @list;
274
275I<Since version 1.35.>
276
277Returns the numerical product of all the elements in C<@list>. If C<@list> is
278empty then C<1> is returned.
279
280 $foo = product 1..10 # 3628800
281 $foo = product 3,9,12 # 324
282
283=head2 sum
284
285 my $num_or_undef = sum @list;
286
287Returns the numerical sum of all the elements in C<@list>. For backwards
288compatibility, if C<@list> is empty then C<undef> is returned.
289
290 $foo = sum 1..10 # 55
291 $foo = sum 3,9,12 # 24
292 $foo = sum @bar, @baz # whatever
293
294=head2 sum0
295
296 my $num = sum0 @list;
297
298I<Since version 1.26.>
299
300Similar to L</sum>, except this returns 0 when given an empty list, rather
301than C<undef>.
302
303=cut
304
305=head1 KEY/VALUE PAIR LIST FUNCTIONS
306
307The following set of functions, all inspired by L<List::Pairwise>, consume an
308even-sized list of pairs. The pairs may be key/value associations from a hash,
309or just a list of values. The functions will all preserve the original ordering
310of the pairs, and will not be confused by multiple pairs having the same "key"
311value - nor even do they require that the first of each pair be a plain string.
312
313B<NOTE>: At the time of writing, the following C<pair*> functions that take a
314block do not modify the value of C<$_> within the block, and instead operate
315using the C<$a> and C<$b> globals instead. This has turned out to be a poor
316design, as it precludes the ability to provide a C<pairsort> function. Better
317would be to pass pair-like objects as 2-element array references in C<$_>, in
318a style similar to the return value of the C<pairs> function. At some future
319version this behaviour may be added.
320
321Until then, users are alerted B<NOT> to rely on the value of C<$_> remaining
322unmodified between the outside and the inside of the control block. In
323particular, the following example is B<UNSAFE>:
324
325 my @kvlist = ...
326
327 foreach (qw( some keys here )) {
328 my @items = pairgrep { $a eq $_ } @kvlist;
329 ...
330 }
331
332Instead, write this using a lexical variable:
333
334 foreach my $key (qw( some keys here )) {
335 my @items = pairgrep { $a eq $key } @kvlist;
336 ...
337 }
338
339=cut
340
341=head2 pairs
342
343 my @pairs = pairs @kvlist;
344
345I<Since version 1.29.>
346
347A convenient shortcut to operating on even-sized lists of pairs, this function
348returns a list of C<ARRAY> references, each containing two items from the
349given list. It is a more efficient version of
350
351 @pairs = pairmap { [ $a, $b ] } @kvlist
352
353It is most convenient to use in a C<foreach> loop, for example:
354
355 foreach my $pair ( pairs @kvlist ) {
356 my ( $key, $value ) = @$pair;
357 ...
358 }
359
360Since version C<1.39> these C<ARRAY> references are blessed objects,
361recognising the two methods C<key> and C<value>. The following code is
362equivalent:
363
364 foreach my $pair ( pairs @kvlist ) {
365 my $key = $pair->key;
366 my $value = $pair->value;
367 ...
368 }
369
370Since version C<1.51> they also have a C<TO_JSON> method to ease
371serialisation.
372
373=head2 unpairs
374
375 my @kvlist = unpairs @pairs
376
377I<Since version 1.42.>
378
379The inverse function to C<pairs>; this function takes a list of C<ARRAY>
380references containing two elements each, and returns a flattened list of the
381two values from each of the pairs, in order. This is notionally equivalent to
382
383 my @kvlist = map { @{$_}[0,1] } @pairs
384
385except that it is implemented more efficiently internally. Specifically, for
386any input item it will extract exactly two values for the output list; using
387C<undef> if the input array references are short.
388
389Between C<pairs> and C<unpairs>, a higher-order list function can be used to
390operate on the pairs as single scalars; such as the following near-equivalents
391of the other C<pair*> higher-order functions:
392
393 @kvlist = unpairs grep { FUNC } pairs @kvlist
394 # Like pairgrep, but takes $_ instead of $a and $b
395
396 @kvlist = unpairs map { FUNC } pairs @kvlist
397 # Like pairmap, but takes $_ instead of $a and $b
398
399Note however that these versions will not behave as nicely in scalar context.
400
401Finally, this technique can be used to implement a sort on a keyvalue pair
402list; e.g.:
403
404 @kvlist = unpairs sort { $a->key cmp $b->key } pairs @kvlist
405
406=head2 pairkeys
407
408 my @keys = pairkeys @kvlist;
409
410I<Since version 1.29.>
411
412A convenient shortcut to operating on even-sized lists of pairs, this function
413returns a list of the the first values of each of the pairs in the given list.
414It is a more efficient version of
415
416 @keys = pairmap { $a } @kvlist
417
418=head2 pairvalues
419
420 my @values = pairvalues @kvlist;
421
422I<Since version 1.29.>
423
424A convenient shortcut to operating on even-sized lists of pairs, this function
425returns a list of the the second values of each of the pairs in the given list.
426It is a more efficient version of
427
428 @values = pairmap { $b } @kvlist
429
430=head2 pairgrep
431
432 my @kvlist = pairgrep { BLOCK } @kvlist;
433
434 my $count = pairgrep { BLOCK } @kvlist;
435
436I<Since version 1.29.>
437
438Similar to perl's C<grep> keyword, but interprets the given list as an
439even-sized list of pairs. It invokes the C<BLOCK> multiple times, in scalar
440context, with C<$a> and C<$b> set to successive pairs of values from the
441C<@kvlist>.
442
443Returns an even-sized list of those pairs for which the C<BLOCK> returned true
444in list context, or the count of the B<number of pairs> in scalar context.
445(Note, therefore, in scalar context that it returns a number half the size of
446the count of items it would have returned in list context).
447
448 @subset = pairgrep { $a =~ m/^[[:upper:]]+$/ } @kvlist
449
450As with C<grep> aliasing C<$_> to list elements, C<pairgrep> aliases C<$a> and
451C<$b> to elements of the given list. Any modifications of it by the code block
452will be visible to the caller.
453
454=head2 pairfirst
455
456 my ( $key, $val ) = pairfirst { BLOCK } @kvlist;
457
458 my $found = pairfirst { BLOCK } @kvlist;
459
460I<Since version 1.30.>
461
462Similar to the L</first> function, but interprets the given list as an
463even-sized list of pairs. It invokes the C<BLOCK> multiple times, in scalar
464context, with C<$a> and C<$b> set to successive pairs of values from the
465C<@kvlist>.
466
467Returns the first pair of values from the list for which the C<BLOCK> returned
468true in list context, or an empty list of no such pair was found. In scalar
469context it returns a simple boolean value, rather than either the key or the
470value found.
471
472 ( $key, $value ) = pairfirst { $a =~ m/^[[:upper:]]+$/ } @kvlist
473
474As with C<grep> aliasing C<$_> to list elements, C<pairfirst> aliases C<$a> and
475C<$b> to elements of the given list. Any modifications of it by the code block
476will be visible to the caller.
477
478=head2 pairmap
479
480 my @list = pairmap { BLOCK } @kvlist;
481
482 my $count = pairmap { BLOCK } @kvlist;
483
484I<Since version 1.29.>
485
486Similar to perl's C<map> keyword, but interprets the given list as an
487even-sized list of pairs. It invokes the C<BLOCK> multiple times, in list
488context, with C<$a> and C<$b> set to successive pairs of values from the
489C<@kvlist>.
490
491Returns the concatenation of all the values returned by the C<BLOCK> in list
492context, or the count of the number of items that would have been returned in
493scalar context.
494
495 @result = pairmap { "The key $a has value $b" } @kvlist
496
497As with C<map> aliasing C<$_> to list elements, C<pairmap> aliases C<$a> and
498C<$b> to elements of the given list. Any modifications of it by the code block
499will be visible to the caller.
500
501See L</KNOWN BUGS> for a known-bug with C<pairmap>, and a workaround.
502
503=cut
504
505=head1 OTHER FUNCTIONS
506
507=cut
508
509=head2 shuffle
510
511 my @values = shuffle @values;
512
513Returns the values of the input in a random order
514
515 @cards = shuffle 0..51 # 0..51 in a random order
516
517This function is affected by the C<$RAND> variable.
518
519=cut
520
521=head2 sample
522
523 my @items = sample $count, @values
524
525I<Since version 1.54.>
526
527Randomly select the given number of elements from the input list. Any given
528position in the input list will be selected at most once.
529
530If there are fewer than C<$count> items in the list then the function will
531return once all of them have been randomly selected; effectively the function
532behaves similarly to L</shuffle>.
533
534This function is affected by the C<$RAND> variable.
535
536=head2 uniq
537
538 my @subset = uniq @values
539
540I<Since version 1.45.>
541
542Filters a list of values to remove subsequent duplicates, as judged by a
543DWIM-ish string equality or C<undef> test. Preserves the order of unique
544elements, and retains the first value of any duplicate set.
545
546 my $count = uniq @values
547
548In scalar context, returns the number of elements that would have been
549returned as a list.
550
551The C<undef> value is treated by this function as distinct from the empty
552string, and no warning will be produced. It is left as-is in the returned
553list. Subsequent C<undef> values are still considered identical to the first,
554and will be removed.
555
556=head2 uniqint
557
558 my @subset = uniqint @values
559
560I<Since version 1.55.>
561
562Filters a list of values to remove subsequent duplicates, as judged by an
563integer numerical equality test. Preserves the order of unique elements, and
564retains the first value of any duplicate set. Values in the returned list will
565be coerced into integers.
566
567 my $count = uniqint @values
568
569In scalar context, returns the number of elements that would have been
570returned as a list.
571
572Note that C<undef> is treated much as other numerical operations treat it; it
573compares equal to zero but additionally produces a warning if such warnings
574are enabled (C<use warnings 'uninitialized';>). In addition, an C<undef> in
575the returned list is coerced into a numerical zero, so that the entire list of
576values returned by C<uniqint> are well-behaved as integers.
577
578=head2 uniqnum
579
580 my @subset = uniqnum @values
581
582I<Since version 1.44.>
583
584Filters a list of values to remove subsequent duplicates, as judged by a
585numerical equality test. Preserves the order of unique elements, and retains
586the first value of any duplicate set.
587
588 my $count = uniqnum @values
589
590In scalar context, returns the number of elements that would have been
591returned as a list.
592
593Note that C<undef> is treated much as other numerical operations treat it; it
594compares equal to zero but additionally produces a warning if such warnings
595are enabled (C<use warnings 'uninitialized';>). In addition, an C<undef> in
596the returned list is coerced into a numerical zero, so that the entire list of
597values returned by C<uniqnum> are well-behaved as numbers.
598
599Note also that multiple IEEE C<NaN> values are treated as duplicates of
600each other, regardless of any differences in their payloads, and despite
601the fact that C<< 0+'NaN' == 0+'NaN' >> yields false.
602
603=head2 uniqstr
604
605 my @subset = uniqstr @values
606
607I<Since version 1.45.>
608
609Filters a list of values to remove subsequent duplicates, as judged by a
610string equality test. Preserves the order of unique elements, and retains the
611first value of any duplicate set.
612
613 my $count = uniqstr @values
614
615In scalar context, returns the number of elements that would have been
616returned as a list.
617
618Note that C<undef> is treated much as other string operations treat it; it
619compares equal to the empty string but additionally produces a warning if such
620warnings are enabled (C<use warnings 'uninitialized';>). In addition, an
621C<undef> in the returned list is coerced into an empty string, so that the
622entire list of values returned by C<uniqstr> are well-behaved as strings.
623
624=cut
625
626=head2 head
627
628 my @values = head $size, @list;
629
630I<Since version 1.50.>
631
632Returns the first C<$size> elements from C<@list>. If C<$size> is negative, returns
633all but the last C<$size> elements from C<@list>.
634
635 @result = head 2, qw( foo bar baz );
636 # foo, bar
637
638 @result = head -2, qw( foo bar baz );
639 # foo
640
641=head2 tail
642
643 my @values = tail $size, @list;
644
645I<Since version 1.50.>
646
647Returns the last C<$size> elements from C<@list>. If C<$size> is negative, returns
648all but the first C<$size> elements from C<@list>.
649
650 @result = tail 2, qw( foo bar baz );
651 # bar, baz
652
653 @result = tail -2, qw( foo bar baz );
654 # baz
655
656=head2 zip
657
658 my @result = zip [1..3], ['a'..'c'];
659 # [1, 'a'], [2, 'b'], [3, 'c']
660
661I<Since version 1.56.>
662
663Returns a list of array references, composed of elements from the given list
664of array references. Each array in the returned list is composed of elements
665at that corresponding position from each of the given input arrays. If any
666input arrays run out of elements before others, then C<undef> will be inserted
667into the result to fill in the gaps.
668
669The C<zip> function is particularly handy for iterating over multiple arrays
670at the same time with a C<foreach> loop, taking one element from each:
671
672 foreach ( zip \@xs, \@ys, \@zs ) {
673 my ($x, $y, $z) = @$_;
674 ...
675 }
676
677B<NOTE> to users of L<List::MoreUtils>: This function does not behave the same
678as C<List::MoreUtils::zip>, but is actually a non-prototyped equivalent to
679C<List::MoreUtils::zip_unflatten>. This function does not apply a prototype,
680so make sure to invoke it with references to arrays.
681
682For a function similar to the C<zip> function from C<List::MoreUtils>, see
683L<mesh>.
684
685 my @result = zip_shortest ...
686
687A variation of the function that differs in how it behaves when given input
688arrays of differing lengths. C<zip_shortest> will stop as soon as any one of
689the input arrays run out of elements, discarding any remaining unused values
690from the others.
691
692 my @result = zip_longest ...
693
694C<zip_longest> is an alias to the C<zip> function, provided simply to be
695explicit about that behaviour as compared to C<zip_shortest>.
696
697=head2 mesh
698
699 my @result = mesh [1..3], ['a'..'c'];
700 # (1, 'a', 2, 'b', 3, 'c')
701
702I<Since version 1.56.>
703
704Returns a list of items collected from elements of the given list of array
705references. Each section of items in the returned list is composed of elements
706at the corresponding position from each of the given input arrays. If any
707input arrays run out of elements before others, then C<undef> will be inserted
708into the result to fill in the gaps.
709
710This is similar to L<zip>, except that all of the ranges in the result are
711returned in one long flattened list, instead of being bundled into separate
712arrays.
713
714Because it returns a flat list of items, the C<mesh> function is particularly
715useful for building a hash out of two separate arrays of keys and values:
716
717 my %hash = mesh \@keys, \@values;
718
719 my $href = { mesh \@keys, \@values };
720
721B<NOTE> to users of L<List::MoreUtils>: This function is a non-prototyped
722equivalent to C<List::MoreUtils::mesh> or C<List::MoreUtils::zip> (themselves
723aliases of each other). This function does not apply a prototype, so make sure
724to invoke it with references to arrays.
725
726 my @result = mesh_shortest ...
727
728 my @result = mesh_longest ...
729
730These variations are similar to those of L<zip>, in that they differ in
731behaviour when one of the input lists runs out of elements before the others.
732
733=head1 CONFIGURATION VARIABLES
734
735=head2 $RAND
736
737 local $List::Util::RAND = sub { ... };
738
739I<Since version 1.54.>
740
741This package variable is used by code which needs to generate random numbers
742(such as the L</shuffle> and L</sample> functions). If set to a CODE reference
743it provides an alternative to perl's builtin C<rand()> function. When a new
744random number is needed this function will be invoked with no arguments and is
745expected to return a floating-point value, of which only the fractional part
746will be used.
747
748=head1 KNOWN BUGS
749
750=head2 RT #95409
751
752L<https://rt.cpan.org/Ticket/Display.html?id=95409>
753
754If the block of code given to L</pairmap> contains lexical variables that are
755captured by a returned closure, and the closure is executed after the block
756has been re-used for the next iteration, these lexicals will not see the
757correct values. For example:
758
759 my @subs = pairmap {
760 my $var = "$a is $b";
761 sub { print "$var\n" };
762 } one => 1, two => 2, three => 3;
763
764 $_->() for @subs;
765
766Will incorrectly print
767
768 three is 3
769 three is 3
770 three is 3
771
772This is due to the performance optimisation of using C<MULTICALL> for the code
773block, which means that fresh SVs do not get allocated for each call to the
774block. Instead, the same SV is re-assigned for each iteration, and all the
775closures will share the value seen on the final iteration.
776
777To work around this bug, surround the code with a second set of braces. This
778creates an inner block that defeats the C<MULTICALL> logic, and does get fresh
779SVs allocated each time:
780
781 my @subs = pairmap {
782 {
783 my $var = "$a is $b";
784 sub { print "$var\n"; }
785 }
786 } one => 1, two => 2, three => 3;
787
788This bug only affects closures that are generated by the block but used
789afterwards. Lexical variables that are only used during the lifetime of the
790block's execution will take their individual values for each invocation, as
791normal.
792
793=head2 uniqnum() on oversized bignums
794
795Due to the way that C<uniqnum()> compares numbers, it cannot distinguish
796differences between bignums (especially bigints) that are too large to fit in
797the native platform types. For example,
798
799 my $x = Math::BigInt->new( "1" x 100 );
800 my $y = $x + 1;
801
802 say for uniqnum( $x, $y );
803
804Will print just the value of C<$x>, believing that C<$y> is a numerically-
805equivalent value. This bug does not affect C<uniqstr()>, which will correctly
806observe that the two values stringify to different strings.
807
808=head1 SUGGESTED ADDITIONS
809
810The following are additions that have been requested, but I have been reluctant
811to add due to them being very simple to implement in perl
812
813 # How many elements are true
814
815 sub true { scalar grep { $_ } @_ }
816
817 # How many elements are false
818
819 sub false { scalar grep { !$_ } @_ }
820
821=head1 SEE ALSO
822
823L<Scalar::Util>, L<List::MoreUtils>
824
825=head1 COPYRIGHT
826
827Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights reserved.
828This program is free software; you can redistribute it and/or
829modify it under the same terms as Perl itself.
830
831Recent additions and current maintenance by
832Paul Evans, <leonerd@leonerd.org.uk>.
833
834=cut
835
83617µs1;
Report produced by the NYTProf 6.12 Perl profiler, developed by Tim Bunce based on work by Adam Kaplan and Salvador Fandiño García.