Provided by: liblist-keywords-perl_0.11-2build4_amd64 
NAME
"List::Keywords" - a selection of list utility keywords
SYNOPSIS
use List::Keywords 'any';
my @boxes = ...;
if( any { $_->size > 100 } @boxes ) {
say "There are some large boxes here";
}
DESCRIPTION
This module provides keywords that behave (almost) identically to familiar functions from List::Util, but
implemented as keyword plugins instead of functions. As a result these run more efficiently, especially
in small code cases.
Blocks vs Anonymous Subs
In the description above the word "almost" refers to the fact that as this module provides true keywords,
the code blocks to them can be parsed as true blocks rather than anonymous functions. As a result, both
"caller" and "return" will behave rather differently here.
For example,
use List::Keywords 'any';
sub func {
any { say "My caller is ", caller; return "ret" } 1, 2, 3;
say "This is never printed";
}
Here, the "caller" will see "func" as its caller, and the "return" statement makes the entire containing
function return, so the second line is never printed. The same example written using "List::Util" will
instead print the "List::Util::any" function as being the caller, before making just that one item return
the value, then the message on the second line is printed as normal.
In regular operation where the code is just performing some test on each item, and does not make use of
"caller" or "return", this should not cause any noticable differences.
Lexical Variable Syntax
Newly added in version 0.09 many of the functions in this module support a new syntax idea that may be
added to Perl core eventually, whereby a lexical variable can be declared before the code block. In that
case, this lexical variable takes the place of the global $_ for the purpose of carrying values from the
input list.
This syntax is currently under discussion for Perl's "map" and "grep" blocks, and may be added in a
future release of Perl.
<https://github.com/Perl/RFCs/pull/33>
Aliasing and Modification
Each time the block code is executed, the global $_ or the lexical variable being used is aliased to an
element of the input list (in the same way as it would be for perl's "map" or "foreach" loops, for
example). If the block attempts to modify the value of this variable, such modifications are visible in
the input list. You almost certainly want to avoid doing this.
For example:
my @numbers = ...;
my $x = first my $x { $x++ > 10 } @numbers;
This will modify values in the @numbers array, but due to the short-circuit nature of "first", will only
have modified values up to the selected element by the time it returns. This will likely confuse later
uses of the input array.
Additionally, the result of "first" is also aliased to the input list, much as it is for core perl's
"grep". This may mean that values passed in to other functions have an ability to mutate at a distance.
For example:
func( first { ... } @numbers );
Here, the invoked func() may be able to modify the @numbers array, for example by modifying its own @_
array.
Performance
The following example demonstrates a simple case and shows how the performance differs.
my @nums = (1 .. 100);
my $ret = any { $_ > 50 } @nums;
When run for 5 seconds each, the following results were obtained on my machine:
List::Util::any 648083/s
List::Keyword/any 816135/s
The "List::Keyword" version here ran 26% faster.
KEYWORDS
first
$val = first { CODE } LIST
Since verison 0.03.
Repeatedly calls the block of code, with $_ locally set to successive values from the given list. Returns
the value and stops at the first item to make the block yield a true value. If no such item exists,
returns "undef".
$val = first my $var { CODE } LIST
Since version 0.09.
Optionally the code block can be prefixed with a lexical variable declaration. In this case, that
variable will contain each value from the list, and the global $_ will remain untouched.
any
$bool = any { CODE } LIST
Repeatedly calls the block of code, with $_ locally set to successive values from the given list. Returns
true and stops at the first item to make the block yield a true value. If no such item exists, returns
false.
$val = any my $var { CODE } LIST
Since version 0.09.
Uses the lexical variable instead of global $_, similar to "first".
all
$bool = all { CODE } LIST
Repeatedly calls the block of code, with $_ locally set to successive values from the given list. Returns
false and stops at the first item to make the block yield a false value. If no such item exists, returns
true.
$val = all my $var { CODE } LIST
Since version 0.09.
Uses the lexical variable instead of global $_, similar to "first".
none
notall
$bool = none { CODE } LIST
$bool = notall { CODE } LISt
Since verison 0.03.
Same as "any" and "all" but with the return value inverted.
$val = none my $var { CODE } LIST
$val = notall my $var { CODE } LIST
Since version 0.09.
Uses the lexical variable instead of global $_, similar to "first".
reduce
$final = reduce { CODE } INITIAL, LIST
Since verison 0.05.
Repeatedly calls a block of code, using the $a package lexical as an accumulator and setting $b to each
successive value from the list in turn. The first value of the list sets the initial value of the
accumulator, and each returned result from the code block gives its new value. The final value of the
accumulator is returned.
reductions
@partials = reductions { CODE } INITIAL, LIST
Since version 0.06.
Similar to "reduce", but returns a full list of all the partial results of every invocation, beginning
with the initial value itself and ending with the final result.
N-AT-A-TIME FUNCTIONS
The following two functions are a further experiment to try out n-at-a-time lexical variable support on
the core "grep" and "map" operators. They are differently named, because keyword plugins cannot replace
existing core keywords, only add new ones.
ngrep
@values = ngrep my ($var1, $var2, ...) { CODE } LIST
$values = ngrep my ($var1, $var2, ...) { CODE } LIST
Since version 0.10.
A variation on core's "grep", which uses lexical variable syntax to request a number of items at once.
The input list is broken into bundles sized according to the number of variables declared. The block of
code is called in scalar context with the variables set to each corresponding bundle of values, and the
bundles for which the block returned true are saved for the resulting list.
In scalar context, returns the number of values that would have been present in the resulting list (i.e.
this is not the same as the number of times the block returned true).
nmap
@results = nmap my ($var1, $var2, ...) { CODE } LIST
$results = nmap my ($var1, $var2, ...) { CODE } LIST
Since version 0.10.
A variation on core's "map", which uses lexical variable syntax to request a number of items at once. The
input list is broken into bundles sized according to the number of variables declared. The block of code
is called in list context with the variables set to each corresponding bundle of values, and the results
of the block from each bundle are concatenated together to form the result list.
In scalar context, returns the number of values that would have been present in the resulting list.
TODO
More functions from "List::Util":
pairfirst pairgrep pairmap
Maybe also consider some from List::UtilsBy.
ACKNOWLEDGEMENTS
With thanks to Matthew Horsfall (alh) for much assistance with performance optimizations.
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>
perl v5.40.0 2024-10-20 List::Keywords(3pm)