Debian Codegraph @

upstream/opensuse-tumbleweed/man3/List::Util.3pm

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