List::Util#

📦 std

The standard library of list reductions and scanners.

List::Util is the first stop when you need to collapse a list to a single answer (sum, max, product, reduce), find or test elements by predicate (first, any, all, none, notall), strip duplicates (uniq, uniqnum, uniqint, uniqstr), or reshape an even-sized key/value list (pairs, pairkeys, pairmap, pairgrep). It also covers slicing (head, tail), randomisation (shuffle, sample), and lockstep iteration over multiple arrays (zip, mesh, and their _shortest / _longest variants).

The block-taking reductions — reduce, reductions, pairmap, pairgrep, pairfirst — expose the current pair or accumulator through $a and $b. The per-element scanners — first, any, all, none, notall — expose the current element through $_.

This module also re-exports Sub::Util (subname, set_subname, set_prototype); in upstream perl5 these live in the same XS source file and pperl mirrors that arrangement.

Functions#

Reductions#

sum#

Add up every value in the list and return the numerical total.

sum0#

Add up every value in the list, returning 0 for an empty list.

min#

Return the numerically smallest value in the list.

max#

Return the numerically largest value in the list.

product#

Multiply every value in the list and return the numerical product.

minstr#

Return the lexically smallest value in the list.

maxstr#

Return the lexically largest value in the list.

reduce#

Collapse a list to a single value by repeated pairwise combination.

reductions#

Like reduce, but also return every intermediate accumulator value.

Scanners#

first#

Return the first list element for which a block returns true.

any#

True if the block returns true for at least one element.

all#

True if the block returns true for every element (including empty list).

none#

True if the block returns true for no element (including empty list).

notall#

True if the block returns false for at least one element.

Pair handling#

pairs#

Group an even-sized list into key/value pair objects.

unpairs#

Flatten a list of two-element arrayrefs into a key/value list.

pairkeys#

Extract just the keys from an even-sized key/value list.

pairvalues#

Extract just the values from an even-sized key/value list.

pairmap#

Run a block for each pair and concatenate the results.

pairgrep#

Keep the pairs for which a block returns true.

pairfirst#

Return the first pair for which a block returns true.

Selection#

tail#

Return the last $size elements of a list.

uniq#

Remove subsequent duplicates by string equality, preserving order.

uniqnum#

Remove subsequent duplicates by numerical equality, preserving order.

uniqint#

Remove subsequent duplicates by integer equality, preserving order.

Misc#

shuffle#

Return the input list in a uniformly random order.

sample#

Pick $count distinct elements from the list at random.

mesh#

Interleave multiple arrays, padding shorter ones with undef.

mesh_shortest#

Interleave multiple arrays, stopping at the shortest.

zip#

Walk multiple arrays in lockstep, returning one arrayref per row.

zip_shortest#

Walk multiple arrays in lockstep, stopping at the shortest.

sub_util_subname#

Return the fully qualified name of a subroutine reference.

sub_util_set_subname#

Assign a name to a subroutine reference in place.

sub_util_set_prototype#

Set or clear the prototype on a subroutine reference.