| File | /usr/local/lib/perl5/5.10.1/darwin-2level/List/Util.pm |
| Statements Executed | 20 |
| Statement Execution Time | 459µs |
| Calls | P | F | Exclusive Time |
Inclusive Time |
Subroutine |
|---|---|---|---|---|---|
| 36 | 1 | 2 | 135µs | 333µs | List::Util::first (xsub) |
| 1 | 1 | 1 | 14µs | 17µs | List::Util::BEGIN@11 |
| 1 | 1 | 1 | 5µs | 62µs | List::Util::BEGIN@12 |
| 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 | |||||
| 9 | package List::Util; | ||||
| 10 | |||||
| 11 | 3 | 27µs | 2 | 20µs | # spent 17µs (14+3) within List::Util::BEGIN@11 which was called
# once (14µs+3µs) by Moose::BEGIN@11 at line 11 # spent 17µs making 1 call to List::Util::BEGIN@11
# spent 3µs making 1 call to strict::import |
| 12 | 3 | 114µs | 2 | 119µs | # spent 62µs (5+57) within List::Util::BEGIN@12 which was called
# once (5µs+57µs) by Moose::BEGIN@11 at line 12 # spent 62µs making 1 call to List::Util::BEGIN@12
# spent 57µs making 1 call to vars::import |
| 13 | 1 | 400ns | require Exporter; | ||
| 14 | |||||
| 15 | 1 | 7µs | @ISA = qw(Exporter); | ||
| 16 | 1 | 2µs | @EXPORT_OK = qw(first min max minstr maxstr reduce sum shuffle); | ||
| 17 | 1 | 200ns | $VERSION = "1.23"; | ||
| 18 | 1 | 200ns | $XS_VERSION = $VERSION; | ||
| 19 | 1 | 18µs | $VERSION = eval $VERSION; | ||
| 20 | |||||
| 21 | 1 | 500ns | eval { | ||
| 22 | # PERL_DL_NONLAZY must be false, or any errors in loading will just | ||||
| 23 | # cause the perl code to be tested | ||||
| 24 | 1 | 600ns | local $ENV{PERL_DL_NONLAZY} = 0 if $ENV{PERL_DL_NONLAZY}; | ||
| 25 | eval { | ||||
| 26 | 1 | 200ns | require XSLoader; | ||
| 27 | 1 | 263µs | 1 | 258µs | XSLoader::load('List::Util', $XS_VERSION); # spent 258µs making 1 call to XSLoader::load |
| 28 | 1 | 800ns | 1; | ||
| 29 | 1 | 300ns | } 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 | 500ns | if (!defined &sum) { | ||
| 38 | require List::Util::PP; | ||||
| 39 | List::Util::PP->import; | ||||
| 40 | } | ||||
| 41 | |||||
| 42 | 1 | 24µ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 333µs (135+198) within List::Util::first which was called 36 times, avg 9µs/call:
# 36 times (135µs+198µs) by Data::OptList::__is_a at line 143 of Data/OptList.pm, avg 9µs/call |