Profile of List/Util.pm

← Index
NYTProf Performance Profile «line view»
For scripts/bench.pl
Run on Mon Oct 22 16:48:56 2018
Reported on Mon Oct 22 16:49:10 2018

Filename | /usr/lib/x86_64-linux-gnu/perl5/5.26/List/Util.pm
Statements | Executed 15 statements in 983µs

Subroutines
Calls | P | F | Exclusive Time | Inclusive Time | Subroutine
--- | --- | --- | --- | --- | ---
52872 | 2 | 1 | 10.9ms | 10.9ms | List::Util::::max List::Util::max (xsub)
54870 | 4 | 2 | 7.49ms | 7.49ms | List::Util::::min List::Util::min (xsub)
1 | 1 | 1 | 13µs | 16µs | List::Util::::BEGIN@9 List::Util::BEGIN@9
1 | 1 | 1 | 8µs | 19µs | List::Util::::BEGIN@31 List::Util::BEGIN@31
1 | 1 | 1 | 6µs | 11µs | List::Util::::BEGIN@10 List::Util::BEGIN@10
0 | 0 | 0 | 0s | 0s | List::Util::_Pair::::keyList::Util::_Pair::key
0 | 0 | 0 | 0s | 0s | List::Util::_Pair::::valueList::Util::_Pair::value
0 | 0 | 0 | 0s | 0s | List::Util::::import List::Util::import

Call graph for these subroutines as a Graphviz dot language file.

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 | 25µs | 2 | 19µs | # spent 16µs (13+3) within List::Util::BEGIN@9 which was called: # once (13µs+3µs) by Game::Collisions::BEGIN@28 at line 9 use strict; # spent 16µs making 1 call to List::Util::BEGIN@9 # spent 3µs making 1 call to strict::import
10 | 2 | 127µs | 2 | 16µs | # spent 11µs (6+5) within List::Util::BEGIN@10 which was called: # once (6µs+5µs) by Game::Collisions::BEGIN@28 at line 10 use warnings; # spent 11µs making 1 call to List::Util::BEGIN@10 # spent 5µs making 1 call to warnings::import
11 | 1 | 700ns |  |  | require Exporter;
12 |  |  |  |  |
13 | 1 | 8µs |  |  | our @ISA = qw(Exporter);
14 | 1 | 4µs |  |  | our @EXPORT_OK = qw(
15 |  |  |  |  | all any first min max minstr maxstr none notall product reduce sum sum0 shuffle uniq uniqnum uniqstr
16 |  |  |  |  | head tail pairs unpairs pairkeys pairvalues pairmap pairgrep pairfirst
17 |  |  |  |  | );
18 | 1 | 300ns |  |  | our $VERSION = "1.50";
19 | 1 | 200ns |  |  | our $XS_VERSION = $VERSION;
20 | 1 | 18µs |  |  | $VERSION = eval $VERSION; # spent 3µs executing statements in string eval
21 |  |  |  |  |
22 | 1 | 300ns |  |  | require XSLoader;
23 | 1 | 274µs | 1 | 266µs | XSLoader::load('List::Util', $XS_VERSION); # spent 266µ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 | 516µs | 2 | 31µs | # spent 19µs (8+12) within List::Util::BEGIN@31 which was called: # once (8µs+12µs) by Game::Collisions::BEGIN@28 at line 31 no strict 'refs'; # spent 19µs making 1 call to List::Util::BEGIN@31 # spent 12µ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 unpairs pairkeys pairvalues pairfirst pairgrep pairmap
54 |  |  |  |  |
55 |  |  |  |  | shuffle uniq 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 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 |  |  |  |  | Note: Due to XS issues the block passed may be able to access the outer @_
153 |  |  |  |  | directly. This is not intentional and will break under debugger.
154 |  |  |  |  |
155 |  |  |  |  | =head2 all
156 |  |  |  |  |
157 |  |  |  |  | my $bool = all { BLOCK } @list;
158 |  |  |  |  |
159 |  |  |  |  | I<Since version 1.33.>
160 |  |  |  |  |
161 |  |  |  |  | Similar to L</any>, except that it requires all elements of the C<@list> to
162 |  |  |  |  | make the C<BLOCK> return true. If any element returns false, then it returns
163 |  |  |  |  | false. If the C<BLOCK> never returns false or the C<@list> was empty then it
164 |  |  |  |  | returns true.
165 |  |  |  |  |
166 |  |  |  |  | Note: Due to XS issues the block passed may be able to access the outer @_
167 |  |  |  |  | directly. This is not intentional and will break under debugger.
168 |  |  |  |  |
169 |  |  |  |  | =head2 none
170 |  |  |  |  |
171 |  |  |  |  | =head2 notall
172 |  |  |  |  |
173 |  |  |  |  | my $bool = none { BLOCK } @list;
174 |  |  |  |  |
175 |  |  |  |  | my $bool = notall { BLOCK } @list;
176 |  |  |  |  |
177 |  |  |  |  | I<Since version 1.33.>
178 |  |  |  |  |
179 |  |  |  |  | Similar to L</any> and L</all>, but with the return sense inverted. C<none>
180 |  |  |  |  | returns true only if no value in the C<@list> causes the C<BLOCK> to return
181 |  |  |  |  | true, and C<notall> returns true only if not all of the values do.
182 |  |  |  |  |
183 |  |  |  |  | Note: Due to XS issues the block passed may be able to access the outer @_
184 |  |  |  |  | directly. This is not intentional and will break under debugger.
185 |  |  |  |  |
186 |  |  |  |  | =head2 first
187 |  |  |  |  |
188 |  |  |  |  | my $val = first { BLOCK } @list;
189 |  |  |  |  |
190 |  |  |  |  | Similar to C<grep> in that it evaluates C<BLOCK> setting C<$_> to each element
191 |  |  |  |  | of C<@list> in turn. C<first> returns the first element where the result from
192 |  |  |  |  | C<BLOCK> is a true value. If C<BLOCK> never returns true or C<@list> was empty
193 |  |  |  |  | then C<undef> is returned.
194 |  |  |  |  |
195 |  |  |  |  | $foo = first { defined($_) } @list # first defined value in @list
196 |  |  |  |  | $foo = first { $_ > $value } @list # first value in @list which
197 |  |  |  |  | # is greater than $value
198 |  |  |  |  |
199 |  |  |  |  | =head2 max
200 |  |  |  |  |
201 |  |  |  |  | my $num = max @list;
202 |  |  |  |  |
203 |  |  |  |  | Returns the entry in the list with the highest numerical value. If the list is
204 |  |  |  |  | empty then C<undef> is returned.
205 |  |  |  |  |
206 |  |  |  |  | $foo = max 1..10 # 10
207 |  |  |  |  | $foo = max 3,9,12 # 12
208 |  |  |  |  | $foo = max @bar, @baz # whatever
209 |  |  |  |  |
210 |  |  |  |  | =head2 maxstr
211 |  |  |  |  |
212 |  |  |  |  | my $str = maxstr @list;
213 |  |  |  |  |
214 |  |  |  |  | Similar to L</max>, but treats all the entries in the list as strings and
215 |  |  |  |  | returns the highest string as defined by the C<gt> operator. If the list is
216 |  |  |  |  | empty then C<undef> is returned.
217 |  |  |  |  |
218 |  |  |  |  | $foo = maxstr 'A'..'Z' # 'Z'
219 |  |  |  |  | $foo = maxstr "hello","world" # "world"
220 |  |  |  |  | $foo = maxstr @bar, @baz # whatever
221 |  |  |  |  |
222 |  |  |  |  | =head2 min
223 |  |  |  |  |
224 |  |  |  |  | my $num = min @list;
225 |  |  |  |  |
226 |  |  |  |  | Similar to L</max> but returns the entry in the list with the lowest numerical
227 |  |  |  |  | value. If the list is empty then C<undef> is returned.
228 |  |  |  |  |
229 |  |  |  |  | $foo = min 1..10 # 1
230 |  |  |  |  | $foo = min 3,9,12 # 3
231 |  |  |  |  | $foo = min @bar, @baz # whatever
232 |  |  |  |  |
233 |  |  |  |  | =head2 minstr
234 |  |  |  |  |
235 |  |  |  |  | my $str = minstr @list;
236 |  |  |  |  |
237 |  |  |  |  | Similar to L</min>, but treats all the entries in the list as strings and
238 |  |  |  |  | returns the lowest string as defined by the C<lt> operator. If the list is
239 |  |  |  |  | empty then C<undef> is returned.
240 |  |  |  |  |
241 |  |  |  |  | $foo = minstr 'A'..'Z' # 'A'
242 |  |  |  |  | $foo = minstr "hello","world" # "hello"
243 |  |  |  |  | $foo = minstr @bar, @baz # whatever
244 |  |  |  |  |
245 |  |  |  |  | =head2 product
246 |  |  |  |  |
247 |  |  |  |  | my $num = product @list;
248 |  |  |  |  |
249 |  |  |  |  | I<Since version 1.35.>
250 |  |  |  |  |
251 |  |  |  |  | Returns the numerical product of all the elements in C<@list>. If C<@list> is
252 |  |  |  |  | empty then C<1> is returned.
253 |  |  |  |  |
254 |  |  |  |  | $foo = product 1..10 # 3628800
255 |  |  |  |  | $foo = product 3,9,12 # 324
256 |  |  |  |  |
257 |  |  |  |  | =head2 sum
258 |  |  |  |  |
259 |  |  |  |  | my $num_or_undef = sum @list;
260 |  |  |  |  |
261 |  |  |  |  | Returns the numerical sum of all the elements in C<@list>. For backwards
262 |  |  |  |  | compatibility, if C<@list> is empty then C<undef> is returned.
263 |  |  |  |  |
264 |  |  |  |  | $foo = sum 1..10 # 55
265 |  |  |  |  | $foo = sum 3,9,12 # 24
266 |  |  |  |  | $foo = sum @bar, @baz # whatever
267 |  |  |  |  |
268 |  |  |  |  | =head2 sum0
269 |  |  |  |  |
270 |  |  |  |  | my $num = sum0 @list;
271 |  |  |  |  |
272 |  |  |  |  | I<Since version 1.26.>
273 |  |  |  |  |
274 |  |  |  |  | Similar to L</sum>, except this returns 0 when given an empty list, rather
275 |  |  |  |  | than C<undef>.
276 |  |  |  |  |
277 |  |  |  |  | =cut
278 |  |  |  |  |
279 |  |  |  |  | =head1 KEY/VALUE PAIR LIST FUNCTIONS
280 |  |  |  |  |
281 |  |  |  |  | The following set of functions, all inspired by L<List::Pairwise>, consume an
282 |  |  |  |  | even-sized list of pairs. The pairs may be key/value associations from a hash,
283 |  |  |  |  | or just a list of values. The functions will all preserve the original ordering
284 |  |  |  |  | of the pairs, and will not be confused by multiple pairs having the same "key"
285 |  |  |  |  | value - nor even do they require that the first of each pair be a plain string.
286 |  |  |  |  |
287 |  |  |  |  | B<NOTE>: At the time of writing, the following C<pair*> functions that take a
288 |  |  |  |  | block do not modify the value of C<$_> within the block, and instead operate
289 |  |  |  |  | using the C<$a> and C<$b> globals instead. This has turned out to be a poor
290 |  |  |  |  | design, as it precludes the ability to provide a C<pairsort> function. Better
291 |  |  |  |  | would be to pass pair-like objects as 2-element array references in C<$_>, in
292 |  |  |  |  | a style similar to the return value of the C<pairs> function. At some future
293 |  |  |  |  | version this behaviour may be added.
294 |  |  |  |  |
295 |  |  |  |  | Until then, users are alerted B<NOT> to rely on the value of C<$_> remaining
296 |  |  |  |  | unmodified between the outside and the inside of the control block. In
297 |  |  |  |  | particular, the following example is B<UNSAFE>:
298 |  |  |  |  |
299 |  |  |  |  | my @kvlist = ...
300 |  |  |  |  |
301 |  |  |  |  | foreach (qw( some keys here )) {
302 |  |  |  |  | my @items = pairgrep { $a eq $_ } @kvlist;
303 |  |  |  |  | ...
304 |  |  |  |  | }
305 |  |  |  |  |
306 |  |  |  |  | Instead, write this using a lexical variable:
307 |  |  |  |  |
308 |  |  |  |  | foreach my $key (qw( some keys here )) {
309 |  |  |  |  | my @items = pairgrep { $a eq $key } @kvlist;
310 |  |  |  |  | ...
311 |  |  |  |  | }
312 |  |  |  |  |
313 |  |  |  |  | =cut
314 |  |  |  |  |
315 |  |  |  |  | =head2 pairs
316 |  |  |  |  |
317 |  |  |  |  | my @pairs = pairs @kvlist;
318 |  |  |  |  |
319 |  |  |  |  | I<Since version 1.29.>
320 |  |  |  |  |
321 |  |  |  |  | A convenient shortcut to operating on even-sized lists of pairs, this function
322 |  |  |  |  | returns a list of C<ARRAY> references, each containing two items from the
323 |  |  |  |  | given list. It is a more efficient version of
324 |  |  |  |  |
325 |  |  |  |  | @pairs = pairmap { [ $a, $b ] } @kvlist
326 |  |  |  |  |
327 |  |  |  |  | It is most convenient to use in a C<foreach> loop, for example:
328 |  |  |  |  |
329 |  |  |  |  | foreach my $pair ( pairs @kvlist ) {
330 |  |  |  |  | my ( $key, $value ) = @$pair;
331 |  |  |  |  | ...
332 |  |  |  |  | }
333 |  |  |  |  |
334 |  |  |  |  | Since version C<1.39> these C<ARRAY> references are blessed objects,
335 |  |  |  |  | recognising the two methods C<key> and C<value>. The following code is
336 |  |  |  |  | equivalent:
337 |  |  |  |  |
338 |  |  |  |  | foreach my $pair ( pairs @kvlist ) {
339 |  |  |  |  | my $key = $pair->key;
340 |  |  |  |  | my $value = $pair->value;
341 |  |  |  |  | ...
342 |  |  |  |  | }
343 |  |  |  |  |
344 |  |  |  |  | =head2 unpairs
345 |  |  |  |  |
346 |  |  |  |  | my @kvlist = unpairs @pairs
347 |  |  |  |  |
348 |  |  |  |  | I<Since version 1.42.>
349 |  |  |  |  |
350 |  |  |  |  | The inverse function to C<pairs>; this function takes a list of C<ARRAY>
351 |  |  |  |  | references containing two elements each, and returns a flattened list of the
352 |  |  |  |  | two values from each of the pairs, in order. This is notionally equivalent to
353 |  |  |  |  |
354 |  |  |  |  | my @kvlist = map { @{$_}[0,1] } @pairs
355 |  |  |  |  |
356 |  |  |  |  | except that it is implemented more efficiently internally. Specifically, for
357 |  |  |  |  | any input item it will extract exactly two values for the output list; using
358 |  |  |  |  | C<undef> if the input array references are short.
359 |  |  |  |  |
360 |  |  |  |  | Between C<pairs> and C<unpairs>, a higher-order list function can be used to
361 |  |  |  |  | operate on the pairs as single scalars; such as the following near-equivalents
362 |  |  |  |  | of the other C<pair*> higher-order functions:
363 |  |  |  |  |
364 |  |  |  |  | @kvlist = unpairs grep { FUNC } pairs @kvlist
365 |  |  |  |  | # Like pairgrep, but takes $_ instead of $a and $b
366 |  |  |  |  |
367 |  |  |  |  | @kvlist = unpairs map { FUNC } pairs @kvlist
368 |  |  |  |  | # Like pairmap, but takes $_ instead of $a and $b
369 |  |  |  |  |
370 |  |  |  |  | Note however that these versions will not behave as nicely in scalar context.
371 |  |  |  |  |
372 |  |  |  |  | Finally, this technique can be used to implement a sort on a keyvalue pair
373 |  |  |  |  | list; e.g.:
374 |  |  |  |  |
375 |  |  |  |  | @kvlist = unpairs sort { $a->key cmp $b->key } pairs @kvlist
376 |  |  |  |  |
377 |  |  |  |  | =head2 pairkeys
378 |  |  |  |  |
379 |  |  |  |  | my @keys = pairkeys @kvlist;
380 |  |  |  |  |
381 |  |  |  |  | I<Since version 1.29.>
382 |  |  |  |  |
383 |  |  |  |  | A convenient shortcut to operating on even-sized lists of pairs, this function
384 |  |  |  |  | returns a list of the the first values of each of the pairs in the given list.
385 |  |  |  |  | It is a more efficient version of
386 |  |  |  |  |
387 |  |  |  |  | @keys = pairmap { $a } @kvlist
388 |  |  |  |  |
389 |  |  |  |  | =head2 pairvalues
390 |  |  |  |  |
391 |  |  |  |  | my @values = pairvalues @kvlist;
392 |  |  |  |  |
393 |  |  |  |  | I<Since version 1.29.>
394 |  |  |  |  |
395 |  |  |  |  | A convenient shortcut to operating on even-sized lists of pairs, this function
396 |  |  |  |  | returns a list of the the second values of each of the pairs in the given list.
397 |  |  |  |  | It is a more efficient version of
398 |  |  |  |  |
399 |  |  |  |  | @values = pairmap { $b } @kvlist
400 |  |  |  |  |
401 |  |  |  |  | =head2 pairgrep
402 |  |  |  |  |
403 |  |  |  |  | my @kvlist = pairgrep { BLOCK } @kvlist;
404 |  |  |  |  |
405 |  |  |  |  | my $count = pairgrep { BLOCK } @kvlist;
406 |  |  |  |  |
407 |  |  |  |  | I<Since version 1.29.>
408 |  |  |  |  |
409 |  |  |  |  | Similar to perl's C<grep> keyword, but interprets the given list as an
410 |  |  |  |  | even-sized list of pairs. It invokes the C<BLOCK> multiple times, in scalar
411 |  |  |  |  | context, with C<$a> and C<$b> set to successive pairs of values from the
412 |  |  |  |  | C<@kvlist>.
413 |  |  |  |  |
414 |  |  |  |  | Returns an even-sized list of those pairs for which the C<BLOCK> returned true
415 |  |  |  |  | in list context, or the count of the B<number of pairs> in scalar context.
416 |  |  |  |  | (Note, therefore, in scalar context that it returns a number half the size of
417 |  |  |  |  | the count of items it would have returned in list context).
418 |  |  |  |  |
419 |  |  |  |  | @subset = pairgrep { $a =~ m/^[[:upper:]]+$/ } @kvlist
420 |  |  |  |  |
421 |  |  |  |  | As with C<grep> aliasing C<$_> to list elements, C<pairgrep> aliases C<$a> and
422 |  |  |  |  | C<$b> to elements of the given list. Any modifications of it by the code block
423 |  |  |  |  | will be visible to the caller.
424 |  |  |  |  |
425 |  |  |  |  | =head2 pairfirst
426 |  |  |  |  |
427 |  |  |  |  | my ( $key, $val ) = pairfirst { BLOCK } @kvlist;
428 |  |  |  |  |
429 |  |  |  |  | my $found = pairfirst { BLOCK } @kvlist;
430 |  |  |  |  |
431 |  |  |  |  | I<Since version 1.30.>
432 |  |  |  |  |
433 |  |  |  |  | Similar to the L</first> function, but interprets the given list as an
434 |  |  |  |  | even-sized list of pairs. It invokes the C<BLOCK> multiple times, in scalar
435 |  |  |  |  | context, with C<$a> and C<$b> set to successive pairs of values from the
436 |  |  |  |  | C<@kvlist>.
437 |  |  |  |  |
438 |  |  |  |  | Returns the first pair of values from the list for which the C<BLOCK> returned
439 |  |  |  |  | true in list context, or an empty list of no such pair was found. In scalar
440 |  |  |  |  | context it returns a simple boolean value, rather than either the key or the
441 |  |  |  |  | value found.
442 |  |  |  |  |
443 |  |  |  |  | ( $key, $value ) = pairfirst { $a =~ m/^[[:upper:]]+$/ } @kvlist
444 |  |  |  |  |
445 |  |  |  |  | As with C<grep> aliasing C<$_> to list elements, C<pairfirst> aliases C<$a> and
446 |  |  |  |  | C<$b> to elements of the given list. Any modifications of it by the code block
447 |  |  |  |  | will be visible to the caller.
448 |  |  |  |  |
449 |  |  |  |  | =head2 pairmap
450 |  |  |  |  |
451 |  |  |  |  | my @list = pairmap { BLOCK } @kvlist;
452 |  |  |  |  |
453 |  |  |  |  | my $count = pairmap { BLOCK } @kvlist;
454 |  |  |  |  |
455 |  |  |  |  | I<Since version 1.29.>
456 |  |  |  |  |
457 |  |  |  |  | Similar to perl's C<map> keyword, but interprets the given list as an
458 |  |  |  |  | even-sized list of pairs. It invokes the C<BLOCK> multiple times, in list
459 |  |  |  |  | context, with C<$a> and C<$b> set to successive pairs of values from the
460 |  |  |  |  | C<@kvlist>.
461 |  |  |  |  |
462 |  |  |  |  | Returns the concatenation of all the values returned by the C<BLOCK> in list
463 |  |  |  |  | context, or the count of the number of items that would have been returned in
464 |  |  |  |  | scalar context.
465 |  |  |  |  |
466 |  |  |  |  | @result = pairmap { "The key $a has value $b" } @kvlist
467 |  |  |  |  |
468 |  |  |  |  | As with C<map> aliasing C<$_> to list elements, C<pairmap> aliases C<$a> and
469 |  |  |  |  | C<$b> to elements of the given list. Any modifications of it by the code block
470 |  |  |  |  | will be visible to the caller.
471 |  |  |  |  |
472 |  |  |  |  | See L</KNOWN BUGS> for a known-bug with C<pairmap>, and a workaround.
473 |  |  |  |  |
474 |  |  |  |  | =cut
475 |  |  |  |  |
476 |  |  |  |  | =head1 OTHER FUNCTIONS
477 |  |  |  |  |
478 |  |  |  |  | =cut
479 |  |  |  |  |
480 |  |  |  |  | =head2 shuffle
481 |  |  |  |  |
482 |  |  |  |  | my @values = shuffle @values;
483 |  |  |  |  |
484 |  |  |  |  | Returns the values of the input in a random order
485 |  |  |  |  |
486 |  |  |  |  | @cards = shuffle 0..51 # 0..51 in a random order
487 |  |  |  |  |
488 |  |  |  |  | =head2 uniq
489 |  |  |  |  |
490 |  |  |  |  | my @subset = uniq @values
491 |  |  |  |  |
492 |  |  |  |  | I<Since version 1.45.>
493 |  |  |  |  |
494 |  |  |  |  | Filters a list of values to remove subsequent duplicates, as judged by a
495 |  |  |  |  | DWIM-ish string equality or C<undef> test. Preserves the order of unique
496 |  |  |  |  | elements, and retains the first value of any duplicate set.
497 |  |  |  |  |
498 |  |  |  |  | my $count = uniq @values
499 |  |  |  |  |
500 |  |  |  |  | In scalar context, returns the number of elements that would have been
501 |  |  |  |  | returned as a list.
502 |  |  |  |  |
503 |  |  |  |  | The C<undef> value is treated by this function as distinct from the empty
504 |  |  |  |  | string, and no warning will be produced. It is left as-is in the returned
505 |  |  |  |  | list. Subsequent C<undef> values are still considered identical to the first,
506 |  |  |  |  | and will be removed.
507 |  |  |  |  |
508 |  |  |  |  | =head2 uniqnum
509 |  |  |  |  |
510 |  |  |  |  | my @subset = uniqnum @values
511 |  |  |  |  |
512 |  |  |  |  | I<Since version 1.44.>
513 |  |  |  |  |
514 |  |  |  |  | Filters a list of values to remove subsequent duplicates, as judged by a
515 |  |  |  |  | numerical equality test. Preserves the order of unique elements, and retains
516 |  |  |  |  | the first value of any duplicate set.
517 |  |  |  |  |
518 |  |  |  |  | my $count = uniqnum @values
519 |  |  |  |  |
520 |  |  |  |  | In scalar context, returns the number of elements that would have been
521 |  |  |  |  | returned as a list.
522 |  |  |  |  |
523 |  |  |  |  | Note that C<undef> is treated much as other numerical operations treat it; it
524 |  |  |  |  | compares equal to zero but additionally produces a warning if such warnings
525 |  |  |  |  | are enabled (C<use warnings 'uninitialized';>). In addition, an C<undef> in
526 |  |  |  |  | the returned list is coerced into a numerical zero, so that the entire list of
527 |  |  |  |  | values returned by C<uniqnum> are well-behaved as numbers.
528 |  |  |  |  |
529 |  |  |  |  | Note also that multiple IEEE C<NaN> values are treated as duplicates of
530 |  |  |  |  | each other, regardless of any differences in their payloads, and despite
531 |  |  |  |  | the fact that C<< 0+'NaN' == 0+'NaN' >> yields false.
532 |  |  |  |  |
533 |  |  |  |  | =head2 uniqstr
534 |  |  |  |  |
535 |  |  |  |  | my @subset = uniqstr @values
536 |  |  |  |  |
537 |  |  |  |  | I<Since version 1.45.>
538 |  |  |  |  |
539 |  |  |  |  | Filters a list of values to remove subsequent duplicates, as judged by a
540 |  |  |  |  | string equality test. Preserves the order of unique elements, and retains the
541 |  |  |  |  | first value of any duplicate set.
542 |  |  |  |  |
543 |  |  |  |  | my $count = uniqstr @values
544 |  |  |  |  |
545 |  |  |  |  | In scalar context, returns the number of elements that would have been
546 |  |  |  |  | returned as a list.
547 |  |  |  |  |
548 |  |  |  |  | Note that C<undef> is treated much as other string operations treat it; it
549 |  |  |  |  | compares equal to the empty string but additionally produces a warning if such
550 |  |  |  |  | warnings are enabled (C<use warnings 'uninitialized';>). In addition, an
551 |  |  |  |  | C<undef> in the returned list is coerced into an empty string, so that the
552 |  |  |  |  | entire list of values returned by C<uniqstr> are well-behaved as strings.
553 |  |  |  |  |
554 |  |  |  |  | =cut
555 |  |  |  |  |
556 |  |  |  |  | =head2 head
557 |  |  |  |  |
558 |  |  |  |  | my @values = head $size, @list;
559 |  |  |  |  |
560 |  |  |  |  | Returns the first C<$size> elements from C<@list>. If C<$size> is negative, returns
561 |  |  |  |  | all but the last C<$size> elements from C<@list>.
562 |  |  |  |  |
563 |  |  |  |  | @result = head 2, qw( foo bar baz );
564 |  |  |  |  | # foo, bar
565 |  |  |  |  |
566 |  |  |  |  | @result = head -2, qw( foo bar baz );
567 |  |  |  |  | # foo
568 |  |  |  |  |
569 |  |  |  |  | =head2 tail
570 |  |  |  |  |
571 |  |  |  |  | my @values = tail $size, @list;
572 |  |  |  |  |
573 |  |  |  |  | Returns the last C<$size> elements from C<@list>. If C<$size> is negative, returns
574 |  |  |  |  | all but the first C<$size> elements from C<@list>.
575 |  |  |  |  |
576 |  |  |  |  | @result = tail 2, qw( foo bar baz );
577 |  |  |  |  | # bar, baz
578 |  |  |  |  |
579 |  |  |  |  | @result = tail -2, qw( foo bar baz );
580 |  |  |  |  | # baz
581 |  |  |  |  |
582 |  |  |  |  | =head1 KNOWN BUGS
583 |  |  |  |  |
584 |  |  |  |  | =head2 RT #95409
585 |  |  |  |  |
586 |  |  |  |  | L<https://rt.cpan.org/Ticket/Display.html?id=95409>
587 |  |  |  |  |
588 |  |  |  |  | If the block of code given to L</pairmap> contains lexical variables that are
589 |  |  |  |  | captured by a returned closure, and the closure is executed after the block
590 |  |  |  |  | has been re-used for the next iteration, these lexicals will not see the
591 |  |  |  |  | correct values. For example:
592 |  |  |  |  |
593 |  |  |  |  | my @subs = pairmap {
594 |  |  |  |  | my $var = "$a is $b";
595 |  |  |  |  | sub { print "$var\n" };
596 |  |  |  |  | } one => 1, two => 2, three => 3;
597 |  |  |  |  |
598 |  |  |  |  | $_->() for @subs;
599 |  |  |  |  |
600 |  |  |  |  | Will incorrectly print
601 |  |  |  |  |
602 |  |  |  |  | three is 3
603 |  |  |  |  | three is 3
604 |  |  |  |  | three is 3
605 |  |  |  |  |
606 |  |  |  |  | This is due to the performance optimisation of using C<MULTICALL> for the code
607 |  |  |  |  | block, which means that fresh SVs do not get allocated for each call to the
608 |  |  |  |  | block. Instead, the same SV is re-assigned for each iteration, and all the
609 |  |  |  |  | closures will share the value seen on the final iteration.
610 |  |  |  |  |
611 |  |  |  |  | To work around this bug, surround the code with a second set of braces. This
612 |  |  |  |  | creates an inner block that defeats the C<MULTICALL> logic, and does get fresh
613 |  |  |  |  | SVs allocated each time:
614 |  |  |  |  |
615 |  |  |  |  | my @subs = pairmap {
616 |  |  |  |  | {
617 |  |  |  |  | my $var = "$a is $b";
618 |  |  |  |  | sub { print "$var\n"; }
619 |  |  |  |  | }
620 |  |  |  |  | } one => 1, two => 2, three => 3;
621 |  |  |  |  |
622 |  |  |  |  | This bug only affects closures that are generated by the block but used
623 |  |  |  |  | afterwards. Lexical variables that are only used during the lifetime of the
624 |  |  |  |  | block's execution will take their individual values for each invocation, as
625 |  |  |  |  | normal.
626 |  |  |  |  |
627 |  |  |  |  | =head2 uniqnum() on oversized bignums
628 |  |  |  |  |
629 |  |  |  |  | Due to the way that C<uniqnum()> compares numbers, it cannot distinguish
630 |  |  |  |  | differences between bignums (especially bigints) that are too large to fit in
631 |  |  |  |  | the native platform types. For example,
632 |  |  |  |  |
633 |  |  |  |  | my $x = Math::BigInt->new( "1" x 100 );
634 |  |  |  |  | my $y = $x + 1;
635 |  |  |  |  |
636 |  |  |  |  | say for uniqnum( $x, $y );
637 |  |  |  |  |
638 |  |  |  |  | Will print just the value of C<$x>, believing that C<$y> is a numerically-
639 |  |  |  |  | equivalent value. This bug does not affect C<uniqstr()>, which will correctly
640 |  |  |  |  | observe that the two values stringify to different strings.
641 |  |  |  |  |
642 |  |  |  |  | =head1 SUGGESTED ADDITIONS
643 |  |  |  |  |
644 |  |  |  |  | The following are additions that have been requested, but I have been reluctant
645 |  |  |  |  | to add due to them being very simple to implement in perl
646 |  |  |  |  |
647 |  |  |  |  | # How many elements are true
648 |  |  |  |  |
649 |  |  |  |  | sub true { scalar grep { $_ } @_ }
650 |  |  |  |  |
651 |  |  |  |  | # How many elements are false
652 |  |  |  |  |
653 |  |  |  |  | sub false { scalar grep { !$_ } @_ }
654 |  |  |  |  |
655 |  |  |  |  | =head1 SEE ALSO
656 |  |  |  |  |
657 |  |  |  |  | L<Scalar::Util>, L<List::MoreUtils>
658 |  |  |  |  |
659 |  |  |  |  | =head1 COPYRIGHT
660 |  |  |  |  |
661 |  |  |  |  | Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights reserved.
662 |  |  |  |  | This program is free software; you can redistribute it and/or
663 |  |  |  |  | modify it under the same terms as Perl itself.
664 |  |  |  |  |
665 |  |  |  |  | Recent additions and current maintenance by
666 |  |  |  |  | Paul Evans, <leonerd@leonerd.org.uk>.
667 |  |  |  |  |
668 |  |  |  |  | =cut
669 |  |  |  |  |
670 | 1 | 10µs |  |  | 1;
|  |  |  |  | # spent 10.9ms within List::Util::max which was called 52872 times, avg 205ns/call: # 26436 times (5.48ms+0s) by Game::Collisions::AABB::_calculate_bounding_box_for_nodes at line 212 of /home/tmurray/proj/Game-Collisions/lib/Game/Collisions/AABB.pm, avg 207ns/call # 26436 times (5.38ms+0s) by Game::Collisions::AABB::_calculate_bounding_box_for_nodes at line 216 of /home/tmurray/proj/Game-Collisions/lib/Game/Collisions/AABB.pm, avg 203ns/call sub List::Util::max; # xsub
|  |  |  |  | # spent 7.49ms within List::Util::min which was called 54870 times, avg 137ns/call: # 26436 times (4.21ms+0s) by Game::Collisions::AABB::_calculate_bounding_box_for_nodes at line 210 of /home/tmurray/proj/Game-Collisions/lib/Game/Collisions/AABB.pm, avg 159ns/call # 26436 times (2.94ms+0s) by Game::Collisions::AABB::_calculate_bounding_box_for_nodes at line 211 of /home/tmurray/proj/Game-Collisions/lib/Game/Collisions/AABB.pm, avg 111ns/call # 999 times (198µs+0s) by Game::Collisions::_add_aabb at line 113 of /home/tmurray/proj/Game-Collisions/lib/Game/Collisions.pm, avg 198ns/call # 999 times (137µs+0s) by Game::Collisions::_add_aabb at line 114 of /home/tmurray/proj/Game-Collisions/lib/Game/Collisions.pm, avg 137ns/call sub List::Util::min; # xsub