| 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 | List::Util::first(xsub) |
| 0 | 0 | 0 | 0s | 0s | List::Util::BEGIN |
| 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 |