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.

cpanm String::Util::Match

perl -MCPAN -e shell
install String::Util::Match