Profile of List/MoreUtils.pm

Filename	/Users/timbo/perl5/perlbrew/perls/perl-5.18.2/lib/site_perl/5.18.2/darwin-2level/List/MoreUtils.pm
Statements	Executed 40 statements in 847µs

Subroutines
Calls	P	F	Exclusive Time	Inclusive Time	Subroutine
30970	4	2	269ms	320ms	List::MoreUtils::::firstidxList::MoreUtils::firstidx (xsub)
473	5	4	31.3ms	37.2ms	List::MoreUtils::::anyList::MoreUtils::any (xsub)
1	1	1	1.46ms	1.63ms	List::MoreUtils::::BEGIN@12List::MoreUtils::BEGIN@12
1	1	1	279µs	3.85ms	List::MoreUtils::::BEGIN@13List::MoreUtils::BEGIN@13
1	1	1	94µs	94µs	List::MoreUtils::::bootstrapList::MoreUtils::bootstrap (xsub)
1	1	1	16µs	16µs	List::MoreUtils::::BEGIN@3List::MoreUtils::BEGIN@3
1	1	1	10µs	20µs	List::MoreUtils::::BEGIN@93List::MoreUtils::BEGIN@93
1	1	1	7µs	13µs	List::MoreUtils::::BEGIN@5List::MoreUtils::BEGIN@5
1	1	1	7µs	19µs	List::MoreUtils::::BEGIN@4List::MoreUtils::BEGIN@4
1	1	1	4µs	4µs	List::MoreUtils::::BEGIN@8List::MoreUtils::BEGIN@8

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

Line	State ments	Time on line	Calls	Time in subs	Code
1					package List::MoreUtils;
2
3	2	44µs	1	16µs	# spent 16µs within List::MoreUtils::BEGIN@3 which was called: # once (16µs+0s) by PPI::Element::BEGIN@28 at line 3 use 5.006; # spent 16µs making 1 call to List::MoreUtils::BEGIN@3
4	2	20µs	2	32µs	# spent 19µs (7+12) within List::MoreUtils::BEGIN@4 which was called: # once (7µs+12µs) by PPI::Element::BEGIN@28 at line 4 use strict; # spent 19µs making 1 call to List::MoreUtils::BEGIN@4 # spent 12µs making 1 call to strict::import
5	2	34µs	2	18µs	# spent 13µs (7+6) within List::MoreUtils::BEGIN@5 which was called: # once (7µs+6µs) by PPI::Element::BEGIN@28 at line 5 use warnings; # spent 13µs making 1 call to List::MoreUtils::BEGIN@5 # spent 6µs making 1 call to warnings::import
6
7					BEGIN
8					# spent 4µs within List::MoreUtils::BEGIN@8 which was called: # once (4µs+0s) by PPI::Element::BEGIN@28 at line 10 {
9	1	4µs			our $VERSION = '0.408';
10	1	17µs	1	4µs	} # spent 4µs making 1 call to List::MoreUtils::BEGIN@8
11
12	2	109µs	1	1.63ms	# spent 1.63ms (1.46+171µs) within List::MoreUtils::BEGIN@12 which was called: # once (1.46ms+171µs) by PPI::Element::BEGIN@28 at line 12 use Exporter::Tiny qw(); # spent 1.63ms making 1 call to List::MoreUtils::BEGIN@12
13	2	238µs	1	3.85ms	# spent 3.85ms (279µs+3.57) within List::MoreUtils::BEGIN@13 which was called: # once (279µs+3.57ms) by PPI::Element::BEGIN@28 at line 13 use List::MoreUtils::XS qw(); # try loading XS # spent 3.85ms making 1 call to List::MoreUtils::BEGIN@13
14
15	1	1µs			my @junctions = qw(any all none notall);
16	1	3µs			my @v0_22 = qw(
17					true false
18					firstidx lastidx
19					insert_after insert_after_string
20					apply indexes
21					after after_incl before before_incl
22					firstval lastval
23					each_array each_arrayref
24					pairwise natatime
25					mesh uniq
26					minmax part
27					);
28	1	300ns			my @v0_24 = qw(bsearch);
29	1	400ns			my @v0_33 = qw(sort_by nsort_by);
30	1	2µs			my @v0_400 = qw(one any_u all_u none_u notall_u one_u
31					firstres onlyidx onlyval onlyres lastres
32					singleton bsearchidx
33					);
34
35	1	5µs			my @all_functions = ( @junctions, @v0_22, @v0_24, @v0_33, @v0_400 );
36
37	1	8µs			my %alias_list = (
38					v0_22 => {
39					first_index => "firstidx",
40					last_index => "lastidx",
41					first_value => "firstval",
42					last_value => "lastval",
43					zip => "mesh",
44					},
45					v0_33 => {
46					distinct => "uniq",
47					},
48					v0_400 => {
49					first_result => "firstres",
50					only_index => "onlyidx",
51					only_value => "onlyval",
52					only_result => "onlyres",
53					last_result => "lastres",
54					bsearch_index => "bsearchidx",
55					},
56					);
57
58	1	7µs			our @ISA = qw(Exporter::Tiny);
59	1	10µs			our @EXPORT_OK = ( @all_functions, map { keys %$_ } values %alias_list );
60					our %EXPORT_TAGS = (
61					all => \@EXPORT_OK,
62					'like_0.22' => [
63					any_u => { -as => 'any' },
64					all_u => { -as => 'all' },
65					none_u => { -as => 'none' },
66					notall_u => { -as => 'notall' },
67					@v0_22,
68					keys %{ $alias_list{v0_22} },
69					],
70					'like_0.24' => [
71					any_u => { -as => 'any' },
72					all_u => { -as => 'all' },
73					notall_u => { -as => 'notall' },
74					'none',
75					@v0_22,
76					@v0_24,
77					keys %{ $alias_list{v0_22} },
78					],
79					'like_0.33' => [
80					@junctions,
81					@v0_22,
82					# v0_24 functions were omitted
83					@v0_33,
84					keys %{ $alias_list{v0_22} },
85	1	20µs			keys %{ $alias_list{v0_33} },
86					],
87					);
88
89	1	700ns			for my $set ( values %alias_list )
90					{
91	3	3µs			for my $alias ( keys %$set )
92					{
93	2	244µs	2	30µs	# spent 20µs (10+10) within List::MoreUtils::BEGIN@93 which was called: # once (10µs+10µs) by PPI::Element::BEGIN@28 at line 93 no strict qw(refs); # spent 20µs making 1 call to List::MoreUtils::BEGIN@93 # spent 10µs making 1 call to strict::unimport
94	12	51µs	12	11µs	*$alias = __PACKAGE__->can( $set->{$alias} ); # spent 11µs making 12 calls to UNIVERSAL::can, avg 900ns/call
95					}
96					}
97
98					=pod
99
100					=head1 NAME
101
102					List::MoreUtils - Provide the stuff missing in List::Util
103
104					=head1 SYNOPSIS
105
106					# import specific functions
107
108					use List::MoreUtils qw(any uniq);
109
110					if ( any { /foo/ } uniq @has_duplicates ) {
111					# do stuff
112					}
113
114					# import everything
115
116					use List::MoreUtils ':all';
117
118					# import by API
119
120					# has "original" any/all/none/notall behavior
121					use List::MoreUtils ':like_0.22';
122					# 0.22 + bsearch
123					use List::MoreUtils ':like_0.24';
124					# has "simplified" any/all/none/notall behavior + (n)sort_by
125					use List::MoreUtils ':like_0.33';
126
127					=head1 DESCRIPTION
128
129					B<List::MoreUtils> provides some trivial but commonly needed functionality on
130					lists which is not going to go into L<List::Util>.
131
132					All of the below functions are implementable in only a couple of lines of Perl
133					code. Using the functions from this module however should give slightly better
134					performance as everything is implemented in C. The pure-Perl implementation of
135					these functions only serves as a fallback in case the C portions of this module
136					couldn't be compiled on this machine.
137
138					=head1 EXPORTS
139
140					=head2 Default behavior
141
142					Nothing by default. To import all of this module's symbols use the C<:all> tag.
143					Otherwise functions can be imported by name as usual:
144
145					use List::MoreUtils ':all';
146
147					use List::MoreUtils qw{ any firstidx };
148
149					Because historical changes to the API might make upgrading List::MoreUtils
150					difficult for some projects, the legacy API is available via special import
151					tags.
152
153					=head2 Like version 0.22 (last release with original API)
154
155					This API was available from 2006 to 2009, returning undef for empty lists on
156					C<all>/C<any>/C<none>/C<notall>:
157
158					use List::MoreUtils ':like_0.22';
159
160					This import tag will import all functions available as of version 0.22.
161					However, it will import C<any_u> as C<any>, C<all_u> as C<all>, C<none_u> as
162					C<none>, and C<notall_u> as C<notall>.
163
164					=head2 Like version 0.24 (first incompatible change)
165
166					This API was available from 2010 to 2011. It changed the return value of C<none>
167					and added the C<bsearch> function.
168
169					use List::MoreUtils ':like_0.24';
170
171					This import tag will import all functions available as of version 0.24.
172					However it will import C<any_u> as C<any>, C<all_u> as C<all>, and
173					C<notall_u> as C<notall>. It will import C<none> as described in
174					the documentation below (true for empty list).
175
176					=head2 Like version 0.33 (second incompatible change)
177
178					This API was available from 2011 to 2014. It is widely used in several CPAN
179					modules and thus it's closest to the current API. It changed the return values
180					of C<any>, C<all>, and C<notall>. It added the C<sort_by> and C<nsort_by> functions
181					and the C<distinct> alias for C<uniq>. It omitted C<bsearch>.
182
183					use List::MoreUtils ':like_0.33';
184
185					This import tag will import all functions available as of version 0.33. Note:
186					it will not import C<bsearch> for consistency with the 0.33 API.
187
188					=head1 FUNCTIONS
189
190					=head2 Junctions
191
192					=head3 I<Treatment of an empty list>
193
194					There are two schools of thought for how to evaluate a junction on an
195					empty list:
196
197					=over
198
199					=item *
200
201					Reduction to an identity (boolean)
202
203					=item *
204
205					Result is undefined (three-valued)
206
207					=back
208
209					In the first case, the result of the junction applied to the empty list is
210					determined by a mathematical reduction to an identity depending on whether
211					the underlying comparison is "or" or "and". Conceptually:
212
213					"any are true" "all are true"
214					-------------- --------------
215					2 elements: A \|\| B \|\| 0 A && B && 1
216					1 element: A \|\| 0 A && 1
217					0 elements: 0 1
218
219					In the second case, three-value logic is desired, in which a junction
220					applied to an empty list returns C<undef> rather than true or false
221
222					Junctions with a C<_u> suffix implement three-valued logic. Those
223					without are boolean.
224
225					=head3 all BLOCK LIST
226
227					=head3 all_u BLOCK LIST
228
229					Returns a true value if all items in LIST meet the criterion given through
230					BLOCK. Sets C<$_> for each item in LIST in turn:
231
232					print "All values are non-negative"
233					if all { $_ >= 0 } ($x, $y, $z);
234
235					For an empty LIST, C<all> returns true (i.e. no values failed the condition)
236					and C<all_u> returns C<undef>.
237
238					Thus, C<< all_u(@list) >> is equivalent to C<< @list ? all(@list) : undef >>.
239
240					B<Note>: because Perl treats C<undef> as false, you must check the return value
241					of C<all_u> with C<defined> or you will get the opposite result of what you
242					expect.
243
244					=head3 any BLOCK LIST
245
246					=head3 any_u BLOCK LIST
247
248					Returns a true value if any item in LIST meets the criterion given through
249					BLOCK. Sets C<$_> for each item in LIST in turn:
250
251					print "At least one non-negative value"
252					if any { $_ >= 0 } ($x, $y, $z);
253
254					For an empty LIST, C<any> returns false and C<any_u> returns C<undef>.
255
256					Thus, C<< any_u(@list) >> is equivalent to C<< @list ? any(@list) : undef >>.
257
258					=head3 none BLOCK LIST
259
260					=head3 none_u BLOCK LIST
261
262					Logically the negation of C<any>. Returns a true value if no item in LIST meets
263					the criterion given through BLOCK. Sets C<$_> for each item in LIST in turn:
264
265					print "No non-negative values"
266					if none { $_ >= 0 } ($x, $y, $z);
267
268					For an empty LIST, C<none> returns true (i.e. no values failed the condition)
269					and C<none_u> returns C<undef>.
270
271					Thus, C<< none_u(@list) >> is equivalent to C<< @list ? none(@list) : undef >>.
272
273					B<Note>: because Perl treats C<undef> as false, you must check the return value
274					of C<none_u> with C<defined> or you will get the opposite result of what you
275					expect.
276
277					=head3 notall BLOCK LIST
278
279					=head3 notall_u BLOCK LIST
280
281					Logically the negation of C<all>. Returns a true value if not all items in LIST
282					meet the criterion given through BLOCK. Sets C<$_> for each item in LIST in
283					turn:
284
285					print "Not all values are non-negative"
286					if notall { $_ >= 0 } ($x, $y, $z);
287
288					For an empty LIST, C<notall> returns false and C<notall_u> returns C<undef>.
289
290					Thus, C<< notall_u(@list) >> is equivalent to C<< @list ? notall(@list) : undef >>.
291
292					=head3 one BLOCK LIST
293
294					=head3 one_u BLOCK LIST
295
296					Returns a true value if precisely one item in LIST meets the criterion
297					given through BLOCK. Sets C<$_> for each item in LIST in turn:
298
299					print "Precisely one value defined"
300					if one { defined($_) } @list;
301
302					Returns false otherwise.
303
304					For an empty LIST, C<one> returns false and C<one_u> returns C<undef>.
305
306					The expression C<one BLOCK LIST> is almost equivalent to
307					C<1 == true BLOCK LIST>, except for short-cutting.
308					Evaluation of BLOCK will immediately stop at the second true value.
309
310					=head2 Transformation
311
312					=head3 apply BLOCK LIST
313
314					Applies BLOCK to each item in LIST and returns a list of the values after BLOCK
315					has been applied. In scalar context, the last element is returned. This
316					function is similar to C<map> but will not modify the elements of the input
317					list:
318
319					my @list = (1 .. 4);
320					my @mult = apply { $_ *= 2 } @list;
321					print "\@list = @list\n";
322					print "\@mult = @mult\n";
323					__END__
324					@list = 1 2 3 4
325					@mult = 2 4 6 8
326
327					Think of it as syntactic sugar for
328
329					for (my @mult = @list) { $_ *= 2 }
330
331					=head3 insert_after BLOCK VALUE LIST
332
333					Inserts VALUE after the first item in LIST for which the criterion in BLOCK is
334					true. Sets C<$_> for each item in LIST in turn.
335
336					my @list = qw/This is a list/;
337					insert_after { $_ eq "a" } "longer" => @list;
338					print "@list";
339					__END__
340					This is a longer list
341
342					=head3 insert_after_string STRING VALUE LIST
343
344					Inserts VALUE after the first item in LIST which is equal to STRING.
345
346					my @list = qw/This is a list/;
347					insert_after_string "a", "longer" => @list;
348					print "@list";
349					__END__
350					This is a longer list
351
352					=head3 pairwise BLOCK ARRAY1 ARRAY2
353
354					Evaluates BLOCK for each pair of elements in ARRAY1 and ARRAY2 and returns a
355					new list consisting of BLOCK's return values. The two elements are set to C<$a>
356					and C<$b>. Note that those two are aliases to the original value so changing
357					them will modify the input arrays.
358
359					@a = (1 .. 5);
360					@b = (11 .. 15);
361					@x = pairwise { $a + $b } @a, @b; # returns 12, 14, 16, 18, 20
362
363					# mesh with pairwise
364					@a = qw/a b c/;
365					@b = qw/1 2 3/;
366					@x = pairwise { ($a, $b) } @a, @b; # returns a, 1, b, 2, c, 3
367
368					=head3 mesh ARRAY1 ARRAY2 [ ARRAY3 ... ]
369
370					=head3 zip ARRAY1 ARRAY2 [ ARRAY3 ... ]
371
372					Returns a list consisting of the first elements of each array, then
373					the second, then the third, etc, until all arrays are exhausted.
374
375					Examples:
376
377					@x = qw/a b c d/;
378					@y = qw/1 2 3 4/;
379					@z = mesh @x, @y; # returns a, 1, b, 2, c, 3, d, 4
380
381					@a = ('x');
382					@b = ('1', '2');
383					@c = qw/zip zap zot/;
384					@d = mesh @a, @b, @c; # x, 1, zip, undef, 2, zap, undef, undef, zot
385
386					C<zip> is an alias for C<mesh>.
387
388					=head3 uniq LIST
389
390					=head3 distinct LIST
391
392					Returns a new list by stripping duplicate values in LIST by comparing
393					the values as hash keys, except that undef is considered separate from ''.
394					The order of elements in the returned list is the same as in LIST. In
395					scalar context, returns the number of unique elements in LIST.
396
397					my @x = uniq 1, 1, 2, 2, 3, 5, 3, 4; # returns 1 2 3 5 4
398					my $x = uniq 1, 1, 2, 2, 3, 5, 3, 4; # returns 5
399					# returns "Mike", "Michael", "Richard", "Rick"
400					my @n = distinct "Mike", "Michael", "Richard", "Rick", "Michael", "Rick"
401					# returns '', 'S1', A5' and complains about "Use of uninitialized value"
402					my @s = distinct '', undef, 'S1', 'A5'
403					# returns undef, 'S1', A5' and complains about "Use of uninitialized value"
404					my @w = uniq undef, '', 'S1', 'A5'
405
406					C<distinct> is an alias for C<uniq>.
407
408					B<RT#49800> can be used to give feedback about this behavior.
409
410					=head3 singleton
411
412					Returns a new list by stripping values in LIST occuring more than once by
413					comparing the values as hash keys, except that undef is considered separate
414					from ''. The order of elements in the returned list is the same as in LIST.
415					In scalar context, returns the number of elements oocuring only once in LIST.
416
417					my @x = singleton 1,1,2,2,3,4,5 # returns 3 4 5
418
419					=head2 Partitioning
420
421					=head3 after BLOCK LIST
422
423					Returns a list of the values of LIST after (and not including) the point
424					where BLOCK returns a true value. Sets C<$_> for each element in LIST in turn.
425
426					@x = after { $_ % 5 == 0 } (1..9); # returns 6, 7, 8, 9
427
428					=head3 after_incl BLOCK LIST
429
430					Same as C<after> but also includes the element for which BLOCK is true.
431
432					=head3 before BLOCK LIST
433
434					Returns a list of values of LIST up to (and not including) the point where BLOCK
435					returns a true value. Sets C<$_> for each element in LIST in turn.
436
437					=head3 before_incl BLOCK LIST
438
439					Same as C<before> but also includes the element for which BLOCK is true.
440
441					=head3 part BLOCK LIST
442
443					Partitions LIST based on the return value of BLOCK which denotes into which
444					partition the current value is put.
445
446					Returns a list of the partitions thusly created. Each partition created is a
447					reference to an array.
448
449					my $i = 0;
450					my @part = part { $i++ % 2 } 1 .. 8; # returns [1, 3, 5, 7], [2, 4, 6, 8]
451
452					You can have a sparse list of partitions as well where non-set partitions will
453					be undef:
454
455					my @part = part { 2 } 1 .. 10; # returns undef, undef, [ 1 .. 10 ]
456
457					Be careful with negative values, though:
458
459					my @part = part { -1 } 1 .. 10;
460					__END__
461					Modification of non-creatable array value attempted, subscript -1 ...
462
463					Negative values are only ok when they refer to a partition previously created:
464
465					my @idx = ( 0, 1, -1 );
466					my $i = 0;
467					my @part = part { $idx[$++ % 3] } 1 .. 8; # [1, 4, 7], [2, 3, 5, 6, 8]
468
469					=head2 Iteration
470
471					=head3 each_array ARRAY1 ARRAY2 ...
472
473					Creates an array iterator to return the elements of the list of arrays ARRAY1,
474					ARRAY2 throughout ARRAYn in turn. That is, the first time it is called, it
475					returns the first element of each array. The next time, it returns the second
476					elements. And so on, until all elements are exhausted.
477
478					This is useful for looping over more than one array at once:
479
480					my $ea = each_array(@a, @b, @c);
481					while ( my ($a, $b, $c) = $ea->() ) { .... }
482
483					The iterator returns the empty list when it reached the end of all arrays.
484
485					If the iterator is passed an argument of 'C<index>', then it returns
486					the index of the last fetched set of values, as a scalar.
487
488					=head3 each_arrayref LIST
489
490					Like each_array, but the arguments are references to arrays, not the
491					plain arrays.
492
493					=head3 natatime EXPR, LIST
494
495					Creates an array iterator, for looping over an array in chunks of
496					C<$n> items at a time. (n at a time, get it?). An example is
497					probably a better explanation than I could give in words.
498
499					Example:
500
501					my @x = ('a' .. 'g');
502					my $it = natatime 3, @x;
503					while (my @vals = $it->())
504					{
505					print "@vals\n";
506					}
507
508					This prints
509
510					a b c
511					d e f
512					g
513
514					=head2 Searching
515
516					=head3 bsearch BLOCK LIST
517
518					Performs a binary search on LIST which must be a sorted list of values. BLOCK
519					must return a negative value if the current element (stored in C<$_>) is smaller,
520					a positive value if it is bigger and zero if it matches.
521
522					Returns a boolean value in scalar context. In list context, it returns the element
523					if it was found, otherwise the empty list.
524
525					=head3 bsearchidx BLOCK LIST
526
527					=head3 bsearch_index BLOCK LIST
528
529					Performs a binary search on LIST which must be a sorted list of values. BLOCK
530					must return a negative value if the current element (stored in C<$_>) is smaller,
531					a positive value if it is bigger and zero if it matches.
532
533					Returns the index of found element, otherwise C<-1>.
534
535					C<bsearch_index> is an alias for C<bsearchidx>.
536
537					=head3 firstval BLOCK LIST
538
539					=head3 first_value BLOCK LIST
540
541					Returns the first element in LIST for which BLOCK evaluates to true. Each
542					element of LIST is set to C<$_> in turn. Returns C<undef> if no such element
543					has been found.
544
545					C<first_value> is an alias for C<firstval>.
546
547					=head3 onlyval BLOCK LIST
548
549					=head3 only_value BLOCK LIST
550
551					Returns the only element in LIST for which BLOCK evaluates to true. Sets
552					C<$_> for each item in LIST in turn. Returns C<undef> if no such element
553					has been found.
554
555					C<only_value> is an alias for C<onlyval>.
556
557					=head3 lastval BLOCK LIST
558
559					=head3 last_value BLOCK LIST
560
561					Returns the last value in LIST for which BLOCK evaluates to true. Each element
562					of LIST is set to C<$_> in turn. Returns C<undef> if no such element has been
563					found.
564
565					C<last_value> is an alias for C<lastval>.
566
567					=head3 firstres BLOCK LIST
568
569					=head3 first_result BLOCK LIST
570
571					Returns the result of BLOCK for the first element in LIST for which BLOCK
572					evaluates to true. Each element of LIST is set to C<$_> in turn. Returns
573					C<undef> if no such element has been found.
574
575					C<first_result> is an alias for C<firstres>.
576
577					=head3 onlyres BLOCK LIST
578
579					=head3 only_result BLOCK LIST
580
581					Returns the result of BLOCK for the first element in LIST for which BLOCK
582					evaluates to true. Sets C<$_> for each item in LIST in turn. Returns
583					C<undef> if no such element has been found.
584
585					C<only_result> is an alias for C<onlyres>.
586
587					=head3 lastres BLOCK LIST
588
589					=head3 last_result BLOCK LIST
590
591					Returns the result of BLOCK for the last element in LIST for which BLOCK
592					evaluates to true. Each element of LIST is set to C<$_> in turn. Returns
593					C<undef> if no such element has been found.
594
595					C<last_result> is an alias for C<lastres>.
596
597					=head3 indexes BLOCK LIST
598
599					Evaluates BLOCK for each element in LIST (assigned to C<$_>) and returns a list
600					of the indices of those elements for which BLOCK returned a true value. This is
601					just like C<grep> only that it returns indices instead of values:
602
603					@x = indexes { $_ % 2 == 0 } (1..10); # returns 1, 3, 5, 7, 9
604
605					=head3 firstidx BLOCK LIST
606
607					=head3 first_index BLOCK LIST
608
609					Returns the index of the first element in LIST for which the criterion in BLOCK
610					is true. Sets C<$_> for each item in LIST in turn:
611
612					my @list = (1, 4, 3, 2, 4, 6);
613					printf "item with index %i in list is 4", firstidx { $_ == 4 } @list;
614					__END__
615					item with index 1 in list is 4
616
617					Returns C<-1> if no such item could be found.
618
619					C<first_index> is an alias for C<firstidx>.
620
621					=head3 onlyidx BLOCK LIST
622
623					=head3 only_index BLOCK LIST
624
625					Returns the index of the only element in LIST for which the criterion
626					in BLOCK is true. Sets C<$_> for each item in LIST in turn:
627
628					my @list = (1, 3, 4, 3, 2, 4);
629					printf "uniqe index of item 2 in list is %i", onlyidx { $_ == 2 } @list;
630					__END__
631					unique index of item 2 in list is 4
632
633					Returns C<-1> if either no such item or more than one of these
634					has been found.
635
636					C<only_index> is an alias for C<onlyidx>.
637
638					=head3 lastidx BLOCK LIST
639
640					=head3 last_index BLOCK LIST
641
642					Returns the index of the last element in LIST for which the criterion in BLOCK
643					is true. Sets C<$_> for each item in LIST in turn:
644
645					my @list = (1, 4, 3, 2, 4, 6);
646					printf "item with index %i in list is 4", lastidx { $_ == 4 } @list;
647					__END__
648					item with index 4 in list is 4
649
650					Returns C<-1> if no such item could be found.
651
652					C<last_index> is an alias for C<lastidx>.
653
654					=head2 Sorting
655
656					=head3 sort_by BLOCK LIST
657
658					Returns the list of values sorted according to the string values returned by the
659					KEYFUNC block or function. A typical use of this may be to sort objects according
660					to the string value of some accessor, such as
661
662					sort_by { $_->name } @people
663
664					The key function is called in scalar context, being passed each value in turn as
665					both $_ and the only argument in the parameters, @_. The values are then sorted
666					according to string comparisons on the values returned.
667					This is equivalent to
668
669					sort { $a->name cmp $b->name } @people
670
671					except that it guarantees the name accessor will be executed only once per value.
672					One interesting use-case is to sort strings which may have numbers embedded in them
673					"naturally", rather than lexically.
674
675					sort_by { s/(\d+)/sprintf "%09d", $1/eg; $_ } @strings
676
677					This sorts strings by generating sort keys which zero-pad the embedded numbers to
678					some level (9 digits in this case), helping to ensure the lexical sort puts them
679					in the correct order.
680
681					=head3 nsort_by BLOCK LIST
682
683					Similar to sort_by but compares its key values numerically.
684
685					=head2 Counting and calculation
686
687					=head3 true BLOCK LIST
688
689					Counts the number of elements in LIST for which the criterion in BLOCK is true.
690					Sets C<$_> for each item in LIST in turn:
691
692					printf "%i item(s) are defined", true { defined($_) } @list;
693
694					=head3 false BLOCK LIST
695
696					Counts the number of elements in LIST for which the criterion in BLOCK is false.
697					Sets C<$_> for each item in LIST in turn:
698
699					printf "%i item(s) are not defined", false { defined($_) } @list;
700
701					=head3 minmax LIST
702
703					Calculates the minimum and maximum of LIST and returns a two element list with
704					the first element being the minimum and the second the maximum. Returns the
705					empty list if LIST was empty.
706
707					The C<minmax> algorithm differs from a naive iteration over the list where each
708					element is compared to two values being the so far calculated min and max value
709					in that it only requires 3n/2 - 2 comparisons. Thus it is the most efficient
710					possible algorithm.
711
712					However, the Perl implementation of it has some overhead simply due to the fact
713					that there are more lines of Perl code involved. Therefore, LIST needs to be
714					fairly big in order for C<minmax> to win over a naive implementation. This
715					limitation does not apply to the XS version.
716
717					=head1 ENVIRONMENT
718
719					When C<LIST_MOREUTILS_PP> is set, the module will always use the pure-Perl
720					implementation and not the XS one. This environment variable is really just
721					there for the test-suite to force testing the Perl implementation, and possibly
722					for reporting of bugs. I don't see any reason to use it in a production
723					environment.
724
725					=head1 MAINTENANCE
726
727					The maintenance goal is to preserve the documented semantics of the API;
728					bug fixes that bring actual behavior in line with semantics are allowed.
729					New API functions may be added over time. If a backwards incompatible
730					change is unavoidable, we will attempt to provide support for the legacy
731					API using the same export tag mechanism currently in place.
732
733					This module attempts to use few non-core dependencies. Non-core
734					configuration and testing modules will be bundled when reasonable;
735					run-time dependencies will be added only if they deliver substantial
736					benefit.
737
738					=head1 BUGS
739
740					There is a problem with a bug in 5.6.x perls. It is a syntax error to write
741					things like:
742
743					my @x = apply { s/foo/bar/ } qw{ foo bar baz };
744
745					It has to be written as either
746
747					my @x = apply { s/foo/bar/ } 'foo', 'bar', 'baz';
748
749					or
750
751					my @x = apply { s/foo/bar/ } my @dummy = qw/foo bar baz/;
752
753					Perl 5.5.x and Perl 5.8.x don't suffer from this limitation.
754
755					If you have a functionality that you could imagine being in this module, please
756					drop me a line. This module's policy will be less strict than L<List::Util>'s
757					when it comes to additions as it isn't a core module.
758
759					When you report bugs, it would be nice if you could additionally give me the
760					output of your program with the environment variable C<LIST_MOREUTILS_PP> set
761					to a true value. That way I know where to look for the problem (in XS,
762					pure-Perl or possibly both).
763
764					=head1 SUPPORT
765
766					Bugs should always be submitted via the CPAN bug tracker.
767
768					You can find documentation for this module with the perldoc command.
769
770					perldoc List::MoreUtils
771
772					You can also look for information at:
773
774					=over 4
775
776					=item * RT: CPAN's request tracker
777
778					L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=List-MoreUtils>
779
780					=item * AnnoCPAN: Annotated CPAN documentation
781
782					L<http://annocpan.org/dist/List-MoreUtils>
783
784					=item * CPAN Ratings
785
786					L<http://cpanratings.perl.org/l/List-MoreUtils>
787
788					=item * CPAN Search
789
790					L<http://search.cpan.org/dist/List-MoreUtils/>
791
792					=item * Git Repository
793
794					L<https://github.com/perl5-utils/List-MoreUtils>
795
796					=back
797
798					=head2 Where can I go for help?
799
800					If you have a bug report, a patch or a suggestion, please open a new
801					report ticket at CPAN (but please check previous reports first in case
802					your issue has already been addressed) or open an issue on GitHub.
803
804					Report tickets should contain a detailed description of the bug or
805					enhancement request and at least an easily verifiable way of
806					reproducing the issue or fix. Patches are always welcome, too - and
807					it's cheap to send pull-requests on GitHub. Please keep in mind that
808					code changes are more likely accepted when they're bundled with an
809					approving test.
810
811					If you think you've found a bug then please read
812					"How to Report Bugs Effectively" by Simon Tatham:
813					L<http://www.chiark.greenend.org.uk/~sgtatham/bugs.html>.
814
815					=head2 Where can I go for help with a concrete version?
816
817					Bugs and feature requests are accepted against the latest version
818					only. To get patches for earlier versions, you need to get an
819					agreement with a developer of your choice - who may or not report the
820					issue and a suggested fix upstream (depends on the license you have
821					chosen).
822
823					=head2 Business support and maintenance
824
825					Generally, in volunteered projects, there is no right for support.
826					While every maintainer is happy to improve the provided software,
827					spare time is limited.
828
829					For those who have a use case which requires guaranteed support, one of
830					the maintainers should be hired or contracted. For business support you
831					can contact Jens via his CPAN email address rehsackATcpan.org. Please
832					keep in mind that business support is neither available for free nor
833					are you eligible to receive any support based on the license distributed
834					with this package.
835
836					=head1 THANKS
837
838					=head2 Tassilo von Parseval
839
840					Credits go to a number of people: Steve Purkis for giving me namespace advice
841					and James Keenan and Terrence Branno for their effort of keeping the CPAN
842					tidier by making L<List::Utils> obsolete.
843
844					Brian McCauley suggested the inclusion of apply() and provided the pure-Perl
845					implementation for it.
846
847					Eric J. Roode asked me to add all functions from his module C<List::MoreUtil>
848					into this one. With minor modifications, the pure-Perl implementations of those
849					are by him.
850
851					The bunch of people who almost immediately pointed out the many problems with
852					the glitchy 0.07 release (Slaven Rezic, Ron Savage, CPAN testers).
853
854					A particularly nasty memory leak was spotted by Thomas A. Lowery.
855
856					Lars Thegler made me aware of problems with older Perl versions.
857
858					Anno Siegel de-orphaned each_arrayref().
859
860					David Filmer made me aware of a problem in each_arrayref that could ultimately
861					lead to a segfault.
862
863					Ricardo Signes suggested the inclusion of part() and provided the
864					Perl-implementation.
865
866					Robin Huston kindly fixed a bug in perl's MULTICALL API to make the
867					XS-implementation of part() work.
868
869					=head2 Jens Rehsack
870
871					Credits goes to all people contributing feedback during the v0.400
872					development releases.
873
874					Special thanks goes to David Golden who spent a lot of effort to develop
875					a design to support current state of CPAN as well as ancient software
876					somewhere in the dark. He also contributed a lot of patches to refactor
877					the API frontend to welcome any user of List::MoreUtils - from ancient
878					past to recently last used.
879
880					Toby Inkster provided a lot of useful feedback for sane importer code
881					and was a nice sounding board for API discussions.
882
883					Peter Rabbitson provided a sane git repository setup containing entire
884					package history.
885
886					=head1 TODO
887
888					A pile of requests from other people is still pending further processing in
889					my mailbox. This includes:
890
891					=over 4
892
893					=item * List::Util export pass-through
894
895					Allow B<List::MoreUtils> to pass-through the regular L<List::Util>
896					functions to end users only need to C<use> the one module.
897
898					=item * uniq_by(&@)
899
900					Use code-reference to extract a key based on which the uniqueness is
901					determined. Suggested by Aaron Crane.
902
903					=item * delete_index
904
905					=item * random_item
906
907					=item * random_item_delete_index
908
909					=item * list_diff_hash
910
911					=item * list_diff_inboth
912
913					=item * list_diff_infirst
914
915					=item * list_diff_insecond
916
917					These were all suggested by Dan Muey.
918
919					=item * listify
920
921					Always return a flat list when either a simple scalar value was passed or an
922					array-reference. Suggested by Mark Summersault.
923
924					=back
925
926					=head1 SEE ALSO
927
928					L<List::Util>, L<List::AllUtils>, L<List::UtilsBy>
929
930					=head1 AUTHOR
931
932					Jens Rehsack E<lt>rehsack AT cpan.orgE<gt>
933
934					Adam Kennedy E<lt>adamk@cpan.orgE<gt>
935
936					Tassilo von Parseval E<lt>tassilo.von.parseval@rwth-aachen.deE<gt>
937
938					=head1 COPYRIGHT AND LICENSE
939
940					Some parts copyright 2011 Aaron Crane.
941
942					Copyright 2004 - 2010 by Tassilo von Parseval
943
944					Copyright 2013 - 2015 by Jens Rehsack
945
946					This library is free software; you can redistribute it and/or modify
947					it under the same terms as Perl itself, either Perl version 5.8.4 or,
948					at your option, any later version of Perl 5 you may have available.
949
950					=cut
951
952	1	27µs			1;

					# spent 37.2ms (31.3+5.94) within List::MoreUtils::any which was called 473 times, avg 79µs/call: # 144 times (30.7ms+4.15ms) by PPI::Tokenizer::new at line 211 of PPI/Tokenizer.pm, avg 242µs/call # 141 times (118µs+0s) by Perl::Critic::Config::_policy_is_included at line 299 of Perl/Critic/Config.pm, avg 835ns/call # 141 times (93µs+0s) by Perl::Critic::Config::_policy_is_excluded at line 308 of Perl/Critic/Config.pm, avg 658ns/call # 42 times (354µs+1.78ms) by Perl::Critic::Policy::ControlStructures::ProhibitMutatingListFunctions::_is_topic_mutating_func at line 209 of Perl/Critic/Policy/ControlStructures/ProhibitMutatingListFunctions.pm, avg 51µs/call # 5 times (8µs+0s) by PPI::Normal::register at line 89 of PPI/Normal.pm, avg 2µs/call sub List::MoreUtils::any; # xsub
					# spent 94µs within List::MoreUtils::bootstrap which was called: # once (94µs+0s) by DynaLoader::bootstrap at line 217 of DynaLoader.pm sub List::MoreUtils::bootstrap; # xsub
					# spent 320ms (269+51.1) within List::MoreUtils::firstidx which was called 30970 times, avg 10µs/call: # 30261 times (247ms+47.5ms) by PPI::Element::snext_sibling at line 369 of PPI/Element.pm, avg 10µs/call # 339 times (7.68ms+1.13ms) by PPI::Element::sprevious_sibling at line 417 of PPI/Element.pm, avg 26µs/call # 226 times (11.8ms+2.49ms) by PPI::Element::next_sibling at line 346 of PPI/Element.pm, avg 63µs/call # 144 times (2.77ms+0s) by Perl::Critic::_futz_with_policy_order at line 210 of Perl/Critic.pm, avg 19µs/call sub List::MoreUtils::firstidx; # xsub