<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from List/Util.rs. Do not edit. -->


# List::Util

<div class="pperl-badges"><span class="pperl-badge pperl-tier-std" title="Minimum feature tier: std. Available in all builds from \`--features native-std\` upward.">📦 std</span></div>

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`](Util/sum.md)

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

#### [`sum0`](Util/sum0.md)

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

#### [`min`](Util/min.md)

Return the numerically smallest value in the list.

#### [`max`](Util/max.md)

Return the numerically largest value in the list.

#### [`product`](Util/product.md)

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

#### [`minstr`](Util/minstr.md)

Return the lexically smallest value in the list.

#### [`maxstr`](Util/maxstr.md)

Return the lexically largest value in the list.

#### [`reduce`](Util/reduce.md)

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

#### [`reductions`](Util/reductions.md)

Like `reduce`, but also return every intermediate accumulator value.

### Scanners

#### [`first`](Util/first.md)

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

#### [`any`](Util/any.md)

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

#### [`all`](Util/all.md)

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

#### [`none`](Util/none.md)

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

#### [`notall`](Util/notall.md)

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

### Pair handling

#### [`pairs`](Util/pairs.md)

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

#### [`unpairs`](Util/unpairs.md)

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

#### [`pairkeys`](Util/pairkeys.md)

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

#### [`pairvalues`](Util/pairvalues.md)

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

#### [`pairmap`](Util/pairmap.md)

Run a block for each pair and concatenate the results.

#### [`pairgrep`](Util/pairgrep.md)

Keep the pairs for which a block returns true.

#### [`pairfirst`](Util/pairfirst.md)

Return the first pair for which a block returns true.

### Selection

#### [`head`](Util/head.md)

Return the first `$size` elements of a list.

#### [`tail`](Util/tail.md)

Return the last `$size` elements of a list.

#### [`uniq`](Util/uniq.md)

Remove subsequent duplicates by string equality, preserving order.

#### [`uniqnum`](Util/uniqnum.md)

Remove subsequent duplicates by numerical equality, preserving order.

#### [`uniqint`](Util/uniqint.md)

Remove subsequent duplicates by integer equality, preserving order.

### Misc

#### [`shuffle`](Util/shuffle.md)

Return the input list in a uniformly random order.

#### [`sample`](Util/sample.md)

Pick `$count` distinct elements from the list at random.

#### [`mesh`](Util/mesh.md)

Interleave multiple arrays, padding shorter ones with `undef`.

#### [`mesh_shortest`](Util/mesh_shortest.md)

Interleave multiple arrays, stopping at the shortest.

#### [`zip`](Util/zip.md)

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

#### [`zip_shortest`](Util/zip_shortest.md)

Walk multiple arrays in lockstep, stopping at the shortest.

#### [`sub_util_subname`](Util/sub_util_subname.md)

Return the fully qualified name of a subroutine reference.

#### [`sub_util_set_subname`](Util/sub_util_set_subname.md)

Assign a name to a subroutine reference in place.

#### [`sub_util_set_prototype`](Util/sub_util_set_prototype.md)

Set or clear the prototype on a subroutine reference.