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