File | /usr/lib/perl/5.10/List/Util.pm |
Statements Executed | 20 |
Total Time | 0.0005058 seconds |
Calls | P | F | Exclusive Time |
Inclusive Time |
Subroutine |
---|---|---|---|---|---|
55 | 2 | 3 | 245µs | 665µs | first(xsub) | List::Util::
0 | 0 | 0 | 0s | 0s | BEGIN | List::Util::
Line | Stmts. | Exclusive Time | Avg. | Code |
---|---|---|---|---|
1 | # List::Util.pm | |||
2 | # | |||
3 | # Copyright (c) 1997-2009 Graham Barr <gbarr@pobox.com>. All rights reserved. | |||
4 | # This program is free software; you can redistribute it and/or | |||
5 | # modify it under the same terms as Perl itself. | |||
6 | # | |||
7 | # This module is normally only loaded if the XS module is not available | |||
8 | ||||
9 | package List::Util; | |||
10 | ||||
11 | 3 | 36µs | 12µs | use strict; # spent 9µs making 1 call to strict::import |
12 | 3 | 167µs | 56µs | use vars qw(@ISA @EXPORT_OK $VERSION $XS_VERSION $TESTING_PERL_ONLY); # spent 73µs making 1 call to vars::import |
13 | 1 | 600ns | 600ns | require Exporter; |
14 | ||||
15 | 1 | 12µs | 12µs | @ISA = qw(Exporter); |
16 | 1 | 3µs | 3µs | @EXPORT_OK = qw(first min max minstr maxstr reduce sum shuffle); |
17 | 1 | 600ns | 600ns | $VERSION = "1.23"; |
18 | 1 | 500ns | 500ns | $XS_VERSION = $VERSION; |
19 | 1 | 20µs | 20µs | $VERSION = eval $VERSION; |
20 | ||||
21 | 3 | 6µs | 2µs | eval { |
22 | # PERL_DL_NONLAZY must be false, or any errors in loading will just | |||
23 | # cause the perl code to be tested | |||
24 | local $ENV{PERL_DL_NONLAZY} = 0 if $ENV{PERL_DL_NONLAZY}; | |||
25 | eval { | |||
26 | require XSLoader; | |||
27 | XSLoader::load('List::Util', $XS_VERSION); # spent 231µs making 1 call to XSLoader::load | |||
28 | 1; | |||
29 | 3 | 233µs | 78µs | } or do { |
30 | require DynaLoader; | |||
31 | local @ISA = qw(DynaLoader); | |||
32 | bootstrap List::Util $XS_VERSION; | |||
33 | }; | |||
34 | } unless $TESTING_PERL_ONLY; | |||
35 | ||||
36 | ||||
37 | 1 | 700ns | 700ns | if (!defined &sum) { |
38 | require List::Util::PP; | |||
39 | List::Util::PP->import; | |||
40 | } | |||
41 | ||||
42 | 1 | 27µs | 27µs | 1; |
43 | ||||
44 | __END__ | |||
45 | ||||
46 | =head1 NAME | |||
47 | ||||
48 | List::Util - A selection of general-utility list subroutines | |||
49 | ||||
50 | =head1 SYNOPSIS | |||
51 | ||||
52 | use List::Util qw(first max maxstr min minstr reduce shuffle sum); | |||
53 | ||||
54 | =head1 DESCRIPTION | |||
55 | ||||
56 | C<List::Util> contains a selection of subroutines that people have | |||
57 | expressed would be nice to have in the perl core, but the usage would | |||
58 | not really be high enough to warrant the use of a keyword, and the size | |||
59 | so small such that being individual extensions would be wasteful. | |||
60 | ||||
61 | By default C<List::Util> does not export any subroutines. The | |||
62 | subroutines defined are | |||
63 | ||||
64 | =over 4 | |||
65 | ||||
66 | =item first BLOCK LIST | |||
67 | ||||
68 | Similar to C<grep> in that it evaluates BLOCK setting C<$_> to each element | |||
69 | of LIST in turn. C<first> returns the first element where the result from | |||
70 | BLOCK is a true value. If BLOCK never returns true or LIST was empty then | |||
71 | C<undef> is returned. | |||
72 | ||||
73 | $foo = first { defined($_) } @list # first defined value in @list | |||
74 | $foo = first { $_ > $value } @list # first value in @list which | |||
75 | # is greater than $value | |||
76 | ||||
77 | This function could be implemented using C<reduce> like this | |||
78 | ||||
79 | $foo = reduce { defined($a) ? $a : wanted($b) ? $b : undef } undef, @list | |||
80 | ||||
81 | for example wanted() could be defined() which would return the first | |||
82 | defined value in @list | |||
83 | ||||
84 | =item max LIST | |||
85 | ||||
86 | Returns the entry in the list with the highest numerical value. If the | |||
87 | list is empty then C<undef> is returned. | |||
88 | ||||
89 | $foo = max 1..10 # 10 | |||
90 | $foo = max 3,9,12 # 12 | |||
91 | $foo = max @bar, @baz # whatever | |||
92 | ||||
93 | This function could be implemented using C<reduce> like this | |||
94 | ||||
95 | $foo = reduce { $a > $b ? $a : $b } 1..10 | |||
96 | ||||
97 | =item maxstr LIST | |||
98 | ||||
99 | Similar to C<max>, but treats all the entries in the list as strings | |||
100 | and returns the highest string as defined by the C<gt> operator. | |||
101 | If the list is empty then C<undef> is returned. | |||
102 | ||||
103 | $foo = maxstr 'A'..'Z' # 'Z' | |||
104 | $foo = maxstr "hello","world" # "world" | |||
105 | $foo = maxstr @bar, @baz # whatever | |||
106 | ||||
107 | This function could be implemented using C<reduce> like this | |||
108 | ||||
109 | $foo = reduce { $a gt $b ? $a : $b } 'A'..'Z' | |||
110 | ||||
111 | =item min LIST | |||
112 | ||||
113 | Similar to C<max> but returns the entry in the list with the lowest | |||
114 | numerical value. If the list is empty then C<undef> is returned. | |||
115 | ||||
116 | $foo = min 1..10 # 1 | |||
117 | $foo = min 3,9,12 # 3 | |||
118 | $foo = min @bar, @baz # whatever | |||
119 | ||||
120 | This function could be implemented using C<reduce> like this | |||
121 | ||||
122 | $foo = reduce { $a < $b ? $a : $b } 1..10 | |||
123 | ||||
124 | =item minstr LIST | |||
125 | ||||
126 | Similar to C<min>, but treats all the entries in the list as strings | |||
127 | and returns the lowest string as defined by the C<lt> operator. | |||
128 | If the list is empty then C<undef> is returned. | |||
129 | ||||
130 | $foo = minstr 'A'..'Z' # 'A' | |||
131 | $foo = minstr "hello","world" # "hello" | |||
132 | $foo = minstr @bar, @baz # whatever | |||
133 | ||||
134 | This function could be implemented using C<reduce> like this | |||
135 | ||||
136 | $foo = reduce { $a lt $b ? $a : $b } 'A'..'Z' | |||
137 | ||||
138 | =item reduce BLOCK LIST | |||
139 | ||||
140 | Reduces LIST by calling BLOCK, in a scalar context, multiple times, | |||
141 | setting C<$a> and C<$b> each time. The first call will be with C<$a> | |||
142 | and C<$b> set to the first two elements of the list, subsequent | |||
143 | calls will be done by setting C<$a> to the result of the previous | |||
144 | call and C<$b> to the next element in the list. | |||
145 | ||||
146 | Returns the result of the last call to BLOCK. If LIST is empty then | |||
147 | C<undef> is returned. If LIST only contains one element then that | |||
148 | element is returned and BLOCK is not executed. | |||
149 | ||||
150 | $foo = reduce { $a < $b ? $a : $b } 1..10 # min | |||
151 | $foo = reduce { $a lt $b ? $a : $b } 'aa'..'zz' # minstr | |||
152 | $foo = reduce { $a + $b } 1 .. 10 # sum | |||
153 | $foo = reduce { $a . $b } @bar # concat | |||
154 | ||||
155 | If your algorithm requires that C<reduce> produce an identity value, then | |||
156 | make sure that you always pass that identity value as the first argument to prevent | |||
157 | C<undef> being returned | |||
158 | ||||
159 | $foo = reduce { $a + $b } 0, @values; # sum with 0 identity value | |||
160 | ||||
161 | =item shuffle LIST | |||
162 | ||||
163 | Returns the elements of LIST in a random order | |||
164 | ||||
165 | @cards = shuffle 0..51 # 0..51 in a random order | |||
166 | ||||
167 | =item sum LIST | |||
168 | ||||
169 | Returns the sum of all the elements in LIST. If LIST is empty then | |||
170 | C<undef> is returned. | |||
171 | ||||
172 | $foo = sum 1..10 # 55 | |||
173 | $foo = sum 3,9,12 # 24 | |||
174 | $foo = sum @bar, @baz # whatever | |||
175 | ||||
176 | This function could be implemented using C<reduce> like this | |||
177 | ||||
178 | $foo = reduce { $a + $b } 1..10 | |||
179 | ||||
180 | If your algorithm requires that C<sum> produce an identity of 0, then | |||
181 | make sure that you always pass C<0> as the first argument to prevent | |||
182 | C<undef> being returned | |||
183 | ||||
184 | $foo = sum 0, @values; | |||
185 | ||||
186 | =back | |||
187 | ||||
188 | =head1 KNOWN BUGS | |||
189 | ||||
190 | With perl versions prior to 5.005 there are some cases where reduce | |||
191 | will return an incorrect result. This will show up as test 7 of | |||
192 | reduce.t failing. | |||
193 | ||||
194 | =head1 SUGGESTED ADDITIONS | |||
195 | ||||
196 | The following are additions that have been requested, but I have been reluctant | |||
197 | to add due to them being very simple to implement in perl | |||
198 | ||||
199 | # One argument is true | |||
200 | ||||
201 | sub any { $_ && return 1 for @_; 0 } | |||
202 | ||||
203 | # All arguments are true | |||
204 | ||||
205 | sub all { $_ || return 0 for @_; 1 } | |||
206 | ||||
207 | # All arguments are false | |||
208 | ||||
209 | sub none { $_ && return 0 for @_; 1 } | |||
210 | ||||
211 | # One argument is false | |||
212 | ||||
213 | sub notall { $_ || return 1 for @_; 0 } | |||
214 | ||||
215 | # How many elements are true | |||
216 | ||||
217 | sub true { scalar grep { $_ } @_ } | |||
218 | ||||
219 | # How many elements are false | |||
220 | ||||
221 | sub false { scalar grep { !$_ } @_ } | |||
222 | ||||
223 | =head1 SEE ALSO | |||
224 | ||||
225 | L<Scalar::Util>, L<List::MoreUtils> | |||
226 | ||||
227 | =head1 COPYRIGHT | |||
228 | ||||
229 | Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights reserved. | |||
230 | This program is free software; you can redistribute it and/or | |||
231 | modify it under the same terms as Perl itself. | |||
232 | ||||
233 | =cut | |||
# spent 665µs (245+420) within List::Util::first which was called 54 times, avg 12µs/call:
# 37 times (196µs+420µs) by Data::OptList::__is_a or Data::OptList::__ANON__[/usr/local/share/perl/5.10.0/Data/OptList.pm:143] at line 143 of /usr/local/share/perl/5.10.0/Data/OptList.pm, avg 17µs/call
# 17 times (49µs+0s) by namespace::autoclean::import or namespace::autoclean::__ANON__[/usr/local/share/perl/5.10.0/namespace/autoclean.pm:57] or namespace::autoclean::__ANON__[/usr/local/share/perl/5.10.0/namespace/autoclean.pm:51] at line 51 of /usr/local/share/perl/5.10.0/namespace/autoclean.pm, avg 3µs/call |