← Index
NYTProf Performance Profile   « block view • line view • sub view »
For ddd2.pl
  Run on Tue May 25 16:52:24 2010
Reported on Tue May 25 16:56:45 2010

File /project/perl/lib/List/Util.pm
Statements Executed 20
Statement Execution Time 1.12ms
Subroutines — ordered by exclusive time
Calls P F Exclusive
Time		 Inclusive
Time		 Subroutine
0000s0sList::Util::::BEGINList::Util::BEGIN
Call graph for these subroutines as a Graphviz dot language file.
Line State
ments		 Time
on line		 Calls Time
in subs		 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
9package List::Util;
10
113111µs126µsuse strict;
# spent 26µs making 1 call to strict::import
123338µs1467µsuse vars qw(@ISA @EXPORT_OK $VERSION $XS_VERSION $TESTING_PERL_ONLY);
# spent 467µs making 1 call to vars::import
1316µsrequire Exporter;
14
15111µs@ISA = qw(Exporter);
1618µs@EXPORT_OK = qw(first min max minstr maxstr reduce sum shuffle);
1714µs$VERSION = "1.23";
1814µs$XS_VERSION = $VERSION;
19160µs$VERSION = eval $VERSION;
20
21110µseval {
22 # PERL_DL_NONLAZY must be false, or any errors in loading will just
23 # cause the perl code to be tested
2417µs local $ENV{PERL_DL_NONLAZY} = 0 if $ENV{PERL_DL_NONLAZY};
25 eval {
2615µs require XSLoader;
271504µs1474µs XSLoader::load('List::Util', $XS_VERSION);
# spent 474µs making 1 call to XSLoader::load
2816µs 1;
29110µ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
3716µsif (!defined &sum) {
38 require List::Util::PP;
39 List::Util::PP->import;
40}
41
42134µs1;
43
44__END__
45
46=head1 NAME
47
48List::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
56C<List::Util> contains a selection of subroutines that people have
57expressed would be nice to have in the perl core, but the usage would
58not really be high enough to warrant the use of a keyword, and the size
59so small such that being individual extensions would be wasteful.
60
61By default C<List::Util> does not export any subroutines. The
62subroutines defined are
63
64=over 4
65
66=item first BLOCK LIST
67
68Similar to C<grep> in that it evaluates BLOCK setting C<$_> to each element
69of LIST in turn. C<first> returns the first element where the result from
70BLOCK is a true value. If BLOCK never returns true or LIST was empty then
71C<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
77This function could be implemented using C<reduce> like this
78
79 $foo = reduce { defined($a) ? $a : wanted($b) ? $b : undef } undef, @list
80
81for example wanted() could be defined() which would return the first
82defined value in @list
83
84=item max LIST
85
86Returns the entry in the list with the highest numerical value. If the
87list 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
93This 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
99Similar to C<max>, but treats all the entries in the list as strings
100and returns the highest string as defined by the C<gt> operator.
101If 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
107This 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
113Similar to C<max> but returns the entry in the list with the lowest
114numerical 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
120This 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
126Similar to C<min>, but treats all the entries in the list as strings
127and returns the lowest string as defined by the C<lt> operator.
128If 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
134This 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
140Reduces LIST by calling BLOCK, in a scalar context, multiple times,
141setting C<$a> and C<$b> each time. The first call will be with C<$a>
142and C<$b> set to the first two elements of the list, subsequent
143calls will be done by setting C<$a> to the result of the previous
144call and C<$b> to the next element in the list.
145
146Returns the result of the last call to BLOCK. If LIST is empty then
147C<undef> is returned. If LIST only contains one element then that
148element 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
155If your algorithm requires that C<reduce> produce an identity value, then
156make sure that you always pass that identity value as the first argument to prevent
157C<undef> being returned
158
159 $foo = reduce { $a + $b } 0, @values; # sum with 0 identity value
160
161=item shuffle LIST
162
163Returns 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
169Returns the sum of all the elements in LIST. If LIST is empty then
170C<undef> is returned.
171
172 $foo = sum 1..10 # 55
173 $foo = sum 3,9,12 # 24
174 $foo = sum @bar, @baz # whatever
175
176This function could be implemented using C<reduce> like this
177
178 $foo = reduce { $a + $b } 1..10
179
180If your algorithm requires that C<sum> produce an identity of 0, then
181make sure that you always pass C<0> as the first argument to prevent
182C<undef> being returned
183
184 $foo = sum 0, @values;
185
186=back
187
188=head1 KNOWN BUGS
189
190With perl versions prior to 5.005 there are some cases where reduce
191will return an incorrect result. This will show up as test 7 of
192reduce.t failing.
193
194=head1 SUGGESTED ADDITIONS
195
196The following are additions that have been requested, but I have been reluctant
197to 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
225L<Scalar::Util>, L<List::MoreUtils>
226
227=head1 COPYRIGHT
228
229Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights reserved.
230This program is free software; you can redistribute it and/or
231modify it under the same terms as Perl itself.
232
233=cut
Report produced by the NYTProf 3.11 Perl profiler, developed by Tim Bunce and Adam Kaplan.