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