| 1 |
NAME |
| 2 |
|
| 3 |
List::Keywords - a selection of list utility keywords |
| 4 |
|
| 5 |
SYNOPSIS |
| 6 |
|
| 7 |
use List::Keywords 'any'; |
| 8 |
|
| 9 |
my @boxes = ...; |
| 10 |
|
| 11 |
if( any { $_->size > 100 } @boxes ) { |
| 12 |
say "There are some large boxes here"; |
| 13 |
} |
| 14 |
|
| 15 |
DESCRIPTION |
| 16 |
|
| 17 |
This module provides keywords that behave (almost) identically to |
| 18 |
familiar functions from List::Util, but implemented as keyword plugins |
| 19 |
instead of functions. As a result these run more efficiently, |
| 20 |
especially in small code cases. |
| 21 |
|
| 22 |
Blocks vs Anonymous Subs |
| 23 |
|
| 24 |
In the description above the word "almost" refers to the fact that as |
| 25 |
this module provides true keywords, the code blocks to them can be |
| 26 |
parsed as true blocks rather than anonymous functions. As a result, |
| 27 |
both caller and return will behave rather differently here. |
| 28 |
|
| 29 |
For example, |
| 30 |
|
| 31 |
use List::Keywords 'any'; |
| 32 |
|
| 33 |
sub func { |
| 34 |
any { say "My caller is ", caller; return "ret" } 1, 2, 3; |
| 35 |
say "This is never printed"; |
| 36 |
} |
| 37 |
|
| 38 |
Here, the caller will see func as its caller, and the return statement |
| 39 |
makes the entire containing function return, so the second line is |
| 40 |
never printed. The same example written using List::Util will instead |
| 41 |
print the List::Util::any function as being the caller, before making |
| 42 |
just that one item return the value, then the message on the second |
| 43 |
line is printed as normal. |
| 44 |
|
| 45 |
In regular operation where the code is just performing some test on |
| 46 |
each item, and does not make use of caller or return, this should not |
| 47 |
cause any noticable differences. |
| 48 |
|
| 49 |
Lexical Variable Syntax |
| 50 |
|
| 51 |
Newly added in version 0.09 many of the functions in this module |
| 52 |
support a new syntax idea that may be added to Perl core eventually, |
| 53 |
whereby a lexical variable can be declared before the code block. In |
| 54 |
that case, this lexical variable takes the place of the global $_ for |
| 55 |
the purpose of carrying values from the input list. |
| 56 |
|
| 57 |
This syntax is currently under discussion for Perl's map and grep |
| 58 |
blocks, and may be added in a future release of Perl. |
| 59 |
|
| 60 |
https://github.com/Perl/RFCs/pull/33 |
| 61 |
|
| 62 |
Aliasing and Modification |
| 63 |
|
| 64 |
Each time the block code is executed, the global $_ or the lexical |
| 65 |
variable being used is aliased to an element of the input list (in the |
| 66 |
same way as it would be for perl's map or foreach loops, for example). |
| 67 |
If the block attempts to modify the value of this variable, such |
| 68 |
modifications are visible in the input list. You almost certainly want |
| 69 |
to avoid doing this. |
| 70 |
|
| 71 |
For example: |
| 72 |
|
| 73 |
my @numbers = ...; |
| 74 |
my $x = first my $x { $x++ > 10 } @numbers; |
| 75 |
|
| 76 |
This will modify values in the @numbers array, but due to the |
| 77 |
short-circuit nature of first, will only have modified values up to the |
| 78 |
selected element by the time it returns. This will likely confuse later |
| 79 |
uses of the input array. |
| 80 |
|
| 81 |
Additionally, the result of first is also aliased to the input list, |
| 82 |
much as it is for core perl's grep. This may mean that values passed in |
| 83 |
to other functions have an ability to mutate at a distance. |
| 84 |
|
| 85 |
For example: |
| 86 |
|
| 87 |
func( first { ... } @numbers ); |
| 88 |
|
| 89 |
Here, the invoked func() may be able to modify the @numbers array, for |
| 90 |
example by modifying its own @_ array. |
| 91 |
|
| 92 |
Performance |
| 93 |
|
| 94 |
The following example demonstrates a simple case and shows how the |
| 95 |
performance differs. |
| 96 |
|
| 97 |
my @nums = (1 .. 100); |
| 98 |
|
| 99 |
my $ret = any { $_ > 50 } @nums; |
| 100 |
|
| 101 |
When run for 5 seconds each, the following results were obtained on my |
| 102 |
machine: |
| 103 |
|
| 104 |
List::Util::any 648083/s |
| 105 |
List::Keyword/any 816135/s |
| 106 |
|
| 107 |
The List::Keyword version here ran 26% faster. |
| 108 |
|
| 109 |
KEYWORDS |
| 110 |
|
| 111 |
first |
| 112 |
|
| 113 |
$val = first { CODE } LIST |
| 114 |
|
| 115 |
Since verison 0.03. |
| 116 |
|
| 117 |
Repeatedly calls the block of code, with $_ locally set to successive |
| 118 |
values from the given list. Returns the value and stops at the first |
| 119 |
item to make the block yield a true value. If no such item exists, |
| 120 |
returns undef. |
| 121 |
|
| 122 |
$val = first my $var { CODE } LIST |
| 123 |
|
| 124 |
Since version 0.09. |
| 125 |
|
| 126 |
Optionally the code block can be prefixed with a lexical variable |
| 127 |
declaration. In this case, that variable will contain each value from |
| 128 |
the list, and the global $_ will remain untouched. |
| 129 |
|
| 130 |
any |
| 131 |
|
| 132 |
$bool = any { CODE } LIST |
| 133 |
|
| 134 |
Repeatedly calls the block of code, with $_ locally set to successive |
| 135 |
values from the given list. Returns true and stops at the first item to |
| 136 |
make the block yield a true value. If no such item exists, returns |
| 137 |
false. |
| 138 |
|
| 139 |
$val = any my $var { CODE } LIST |
| 140 |
|
| 141 |
Since version 0.09. |
| 142 |
|
| 143 |
Uses the lexical variable instead of global $_, similar to "first". |
| 144 |
|
| 145 |
all |
| 146 |
|
| 147 |
$bool = all { CODE } LIST |
| 148 |
|
| 149 |
Repeatedly calls the block of code, with $_ locally set to successive |
| 150 |
values from the given list. Returns false and stops at the first item |
| 151 |
to make the block yield a false value. If no such item exists, returns |
| 152 |
true. |
| 153 |
|
| 154 |
$val = all my $var { CODE } LIST |
| 155 |
|
| 156 |
Since version 0.09. |
| 157 |
|
| 158 |
Uses the lexical variable instead of global $_, similar to "first". |
| 159 |
|
| 160 |
none |
| 161 |
|
| 162 |
notall |
| 163 |
|
| 164 |
$bool = none { CODE } LIST |
| 165 |
$bool = notall { CODE } LISt |
| 166 |
|
| 167 |
Since verison 0.03. |
| 168 |
|
| 169 |
Same as "any" and "all" but with the return value inverted. |
| 170 |
|
| 171 |
$val = none my $var { CODE } LIST |
| 172 |
$val = notall my $var { CODE } LIST |
| 173 |
|
| 174 |
Since version 0.09. |
| 175 |
|
| 176 |
Uses the lexical variable instead of global $_, similar to "first". |
| 177 |
|
| 178 |
reduce |
| 179 |
|
| 180 |
$final = reduce { CODE } INITIAL, LIST |
| 181 |
|
| 182 |
Since verison 0.05. |
| 183 |
|
| 184 |
Repeatedly calls a block of code, using the $a package lexical as an |
| 185 |
accumulator and setting $b to each successive value from the list in |
| 186 |
turn. The first value of the list sets the initial value of the |
| 187 |
accumulator, and each returned result from the code block gives its new |
| 188 |
value. The final value of the accumulator is returned. |
| 189 |
|
| 190 |
reductions |
| 191 |
|
| 192 |
@partials = reductions { CODE } INITIAL, LIST |
| 193 |
|
| 194 |
Since version 0.06. |
| 195 |
|
| 196 |
Similar to reduce, but returns a full list of all the partial results |
| 197 |
of every invocation, beginning with the initial value itself and ending |
| 198 |
with the final result. |
| 199 |
|
| 200 |
N-AT-A-TIME FUNCTIONS |
| 201 |
|
| 202 |
The following two functions are a further experiment to try out |
| 203 |
n-at-a-time lexical variable support on the core grep and map |
| 204 |
operators. They are differently named, because keyword plugins cannot |
| 205 |
replace existing core keywords, only add new ones. |
| 206 |
|
| 207 |
ngrep |
| 208 |
|
| 209 |
@values = ngrep my ($var1, $var2, ...) { CODE } LIST |
| 210 |
|
| 211 |
$values = ngrep my ($var1, $var2, ...) { CODE } LIST |
| 212 |
|
| 213 |
Since version 0.10. |
| 214 |
|
| 215 |
A variation on core's grep, which uses lexical variable syntax to |
| 216 |
request a number of items at once. The input list is broken into |
| 217 |
bundles sized according to the number of variables declared. The block |
| 218 |
of code is called in scalar context with the variables set to each |
| 219 |
corresponding bundle of values, and the bundles for which the block |
| 220 |
returned true are saved for the resulting list. |
| 221 |
|
| 222 |
In scalar context, returns the number of values that would have been |
| 223 |
present in the resulting list (i.e. this is not the same as the number |
| 224 |
of times the block returned true). |
| 225 |
|
| 226 |
nmap |
| 227 |
|
| 228 |
@results = nmap my ($var1, $var2, ...) { CODE } LIST |
| 229 |
|
| 230 |
$results = nmap my ($var1, $var2, ...) { CODE } LIST |
| 231 |
|
| 232 |
Since version 0.10. |
| 233 |
|
| 234 |
A variation on core's map, which uses lexical variable syntax to |
| 235 |
request a number of items at once. The input list is broken into |
| 236 |
bundles sized according to the number of variables declared. The block |
| 237 |
of code is called in list context with the variables set to each |
| 238 |
corresponding bundle of values, and the results of the block from each |
| 239 |
bundle are concatenated together to form the result list. |
| 240 |
|
| 241 |
In scalar context, returns the number of values that would have been |
| 242 |
present in the resulting list. |
| 243 |
|
| 244 |
TODO |
| 245 |
|
| 246 |
More functions from List::Util: |
| 247 |
|
| 248 |
pairfirst pairgrep pairmap |
| 249 |
|
| 250 |
Maybe also consider some from List::UtilsBy. |
| 251 |
|
| 252 |
ACKNOWLEDGEMENTS |
| 253 |
|
| 254 |
With thanks to Matthew Horsfall (alh) for much assistance with |
| 255 |
performance optimizations. |
| 256 |
|
| 257 |
AUTHOR |
| 258 |
|
| 259 |
Paul Evans <[email protected]> |
| 260 |
|