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.

   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".

   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.

   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.

   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.

   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.

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>