Debian Codegraph @

README

raw
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