NAME

List::Util::Find - List utilities related to finding items

VERSION

This document describes version 0.005.1 of List::Util::Find (from Perl distribution List-Util-Find), released on 2026-03-29.

SYNOPSIS

use List::Util::Find qw(
  hasnum hasstr
  lacksnum lacksstr
  hasallnums hasanynums hasnonenums
  hasallstrs hasanystrs hasnonestrs
  lacksallnums lacksanynums lacksnonenums
  lacksallstrs lacksanystrs lacksnonestrs
);

my @ary = (1,3,"foo",7,2,"bar",10,"baz");

if (hasnum 3, @ary)     { ... } # matches
if (hasnum 0, @ary)     { ... } # doesn't match
if (hasstr "baz", @ary) { ... } # matches
if (hasstr "qux", @ary) { ... } # doesn't match
if (lacksnum 3, @ary)     { ... } # doesn't match
if (lacksnum 0, @ary)     { ... } # matches
if (lacksstr "baz", @ary) { ... } # doesn't match
if (lacksstr "qux", @ary) { ... } # matches

if (hasallnums [1,2], @ary)  { ... } # matches
if (hasallnums [0,2], @ary)  { ... } # doesn't match
if (hasallnums [], @ary)     { ... } # matches, empty needle
if (hasanynums [1,2], @ary)  { ... } # matches
if (hasanynums [0,2], @ary)  { ... } # matches
if (hasanynums [0,4], @ary)  { ... } # desn't match
if (hasanynums [], @ary)     { ... } # matches, empty needle
if (hasnonenums [0,2], @ary) { ... } # doesn't match
if (hasnonenums [0,4], @ary) { ... } # matches
if (hasnonenums [], @ary)    { ... } # matches, empty needle

# TODO: examples for hasallstrs
# TODO: examples for hasanystrs
# TODO: examples for hasnonestrs
# TODO: examples for lacksallnums
# TODO: examples for lacksanynums
# TODO: examples for lacksnonenums
# TODO: examples for lacksallstrs
# TODO: examples for lacksanystrs
# TODO: examples for lacksnonestrs

DESCRIPTION

Experimental.

FUNCTIONS

Not exported by default but exportable.

hasnum

Usage:

hasnum $num, @list

Like grep { $_ == $num } ... except: 1) it short-circuits (exits early as soon as an item is found); 2) it makes sure undef does not match; 3) it makes sure non-numeric scalars don't match when $num is zero.

It is equivalent to something like:

use List::Util qw(first);
use Scalar::Util qw(looks_like_number);
defined(first { defined && looks_like_number($_) && $_ == $num } @list);

except it does not use additional modules.

hasstr

Usage:

hasstr $str, @list

Like grep { $_ eq $num } ... except: 1) it short-circuits (exits early as soon as an item is found); 2) it makes sure undef does not match empty string.

It is equivalent to something like:

use List::Util qw(first);
defined(first { defined && $_ eq $str } @list);

lacksnum

Usage:

lacksnum $num, @list

It is equivalent to:

!hasnum($num, @list)

lacksstr

Usage:

lacksstr $str, @list

It is equivalent to:

!hasstr($str, @list)

hasallnums

Usage:

hasallnums [$num1, $num2, ...], @list

The multiple-needle version of "hasnum".

hasanynums

Usage:

hasanynums [$num1, $num2, ...], @list

The multiple-needle version of "hasnum".

hasnonenums

Usage:

hasanynums [$num1, $num2, ...], @list

The multiple-needle version of "hasnum".

hasallstrs

Usage:

hasallstrs [$str1, $str2, ...], @list

The multiple-needle version of "hasstr".

hasanystrs

Usage:

hasanystrs [$str1, $str2, ...], @list

The multiple-needle version of "hasstr".

hasnonestrs

Usage:

hasnonestrs [$str1, $str2, ...], @list

The multiple-needle version of "hasstr".

lacksallnums

Usage:

lacksallnums [$num1, $num2, ...], @list

The multiple-needle version of "lacksnum".

lacksanynums

Usage:

lacksanynums [$num1, $num2, ...], @list

The multiple-needle version of "lacksnum".

lacksnonenums

Usage:

lacksanynums [$num1, $num2, ...], @list

The multiple-needle version of "lacksnum".

lacksallstrs

Usage:

lacksallstrs [$str1, $str2, ...], @list

The multiple-needle version of "lacksstr".

lacksanystrs

Usage:

lacksanystrs [$str1, $str2, ...], @list

The multiple-needle version of "lacksstr".

lacksnonestrs

Usage:

lacksnonestrs [$str1, $str2, ...], @list

The multiple-needle version of "lacksstr".

FAQ

How about hasundef, hasref, hasarrayref, ...?

They are trivial enough:

first { !defined } @list;
first { ref $_ } @list;
first { ref $_ eq 'ARRAY' } @list;
# and so on

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/List-Util-Find.

SOURCE

Source repository is at https://github.com/perlancar/perl-List-Util-Find.

SEE ALSO

List::Util

AUTHOR

perlancar <perlancar@cpan.org>

CONTRIBUTING

To contribute, you can send patches by email/via RT, or send pull requests on GitHub.

Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via:

% prove -l

If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by perlancar <perlancar@cpan.org>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=List-Util-Find

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

cpanm List::Util::Find

perl -MCPAN -e shell
install List::Util::Find