| 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]>. |