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>

