NAME
    String::Util::Match - String utilities related to matching

VERSION
    This document describes version 0.005 of String::Util::Match (from Perl
    distribution String-Util-Match), released on 2024-01-10.

SYNOPSIS
     use String::Util::Match qw(match_string match_array_or_regex num_occurs);

     match_string(str => 'foo', matcher => 'foo'); # => 1
     match_string(str => 'foo', matcher => 'FOO'); # => 0
     match_string(str => 'foo', matcher => 'FOO', ignore_case=>1); # => 1
     match_string(str => 'foo', matcher => qr/f.+/); # => 1
     match_string(str => 'foo', matcher => qr/bar/); # => 0
     match_string(str => 'foo', matcher => [qw/foo bar baz/]); # => 1
     match_string(str => 'foo', matcher => [qw/bar baz/]); # => 0
     match_string(str => 'foo', matcher => sub { $_[0] eq 'foo' }); # => 1
     match_string(str => 'foo', matcher => sub { $_[0] eq 'bar' }); # => 0

     match_array_or_regex('bar',  ['foo', 'bar', qr/[xyz]/]); # true, matches string
     match_array_or_regex('baz',  ['foo', 'bar', qr/[xyz]/]); # true, matches regex
     match_array_or_regex('oops', ['foo', 'bar', qr/[xyz]/]); # false

     print num_occurs("foobarbaz", "a"); # => 2
     print num_occurs("foobarbaz", "A"); # => 0
     print num_occurs("foobarbaz", qr/a/i); # => 2
     print num_occurs("foobarbaz", qr/[aeiou]/); # => 4

DESCRIPTION
FUNCTIONS
  match_array_or_regex
    Usage:

     match_array_or_regex($needle, $haystack) -> any

    Check whether an item matches (list of) values/regexes.

    Examples:

    *   Example #1:

         match_array_or_regex("abc", ["abc", "abd"]); # -> 1

    *   Example #2:

         match_array_or_regex("abc", qr/ab./); # -> 1

    *   Example #3:

         match_array_or_regex("abc", [qr/ab./, "abd"]); # -> 1

    This routine can be used to match an item against a regex or a list of
    strings/regexes, e.g. when matching against an ACL.

    Since the smartmatch ("~~") operator can already match against a list of
    strings or regexes, this function is currently basically equivalent to:

     if (ref($haystack) eq 'ARRAY') {
         return $needle ~~ @$haystack;
     } else {
         return $needle =~ /$haystack/;
     }

    except that the smartmatch operator covers more cases and is currently
    deprecated in the current perl versions and might be removed in future
    versions.

    This function is not exported by default, but exportable.

    Arguments ('*' denotes required arguments):

    *   $haystack* => *re|str|array[re|str]*

        (No description)

    *   $needle* => *str*

        (No description)

    Return value: (any)

  match_string
    Usage:

     match_string(%args) -> any

    Match a string (with one of several choices).

    This function is not exported by default, but exportable.

    Arguments ('*' denotes required arguments):

    *   ignore_case => *bool*

        Only relevant for string vs string matching.

    *   matcher => *str|aos|obj::re|code*

        Matcher.

    *   str* => *str*

        String to match against.

    Return value: (any)

  num_occurs
    Usage:

     num_occurs($string, $substring) -> uint

    Count how many times a substring occurs (or a regex pattern matches) a
    string.

    This function is not exported by default, but exportable.

    Arguments ('*' denotes required arguments):

    *   $string* => *str*

        (No description)

    *   $substring* => *re|str*

        (No description)

    Return value: (uint)

HOMEPAGE
    Please visit the project's homepage at
    <https://metacpan.org/release/String-Util-Match>.

SOURCE
    Source repository is at
    <https://github.com/perlancar/perl-String-Util-Match>.

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) 2024, 2023, 2017 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=String-Util-Match>

    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.