Debian Codegraph @

upstream/debian-unstable/man3/List::Util.3perl

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