PCRE2_MATCH(3)

💖 PCRE2_MATCH(3) 💖

Hey bestie! This page comes from the Library Functions Manual, and it’s literally all about pcre2_match — the PCRE2 function that eats regexes and tells you what matched. No cap, we’re keeping every detail. 🫶

🌸 NAME 🌸

PCRE2 - Perl-compatible regular expressions (revised API). 💅

✨ SYNOPSIS ✨

       #include <pcre2.h>

       int pcre2_match(const pcre2_code *code, PCRE2_SPTR subject,
         PCRE2_SIZE length, PCRE2_SIZE startoffset,
         uint32_t options, pcre2_match_data *match_data,
         pcre2_match_context *mcontext);

🦋 DESCRIPTION 🦋

Okay so pcre2_match() matches a compiled regular expression against a given subject string, using a matching algorithm that is similar to Perl’s. It returns offsets to what it has matched and to captured substrings via the match_data block, which can be processed by functions with names that start with pcre2_get_ovector_...() or pcre2_substring_...(). The return from pcre2_match() is one more than the highest numbered capturing pair that has been set (for example, 1 if there are no captures), zero if the vector of offsets is too small, or a negative error code for no match and other errors. The function arguments are:

• code — Points to the compiled pattern.
• subject — Points to the subject string.
• length — Length of the subject string.
• startoffset — Offset in the subject at which to start matching.
• options — Option bits.
• match_data — Points to a match data block, for results.
• mcontext — Points to a match context, or is NULL.

A match context is needed only if you want to:

• Set up a callout function.
• Set a matching offset limit.
• Change the heap memory limit.
• Change the backtracking match limit.
• Change the backtracking depth limit.
• Set custom memory management specifically for the match.

The length and startoffset values are code units, not characters. The length may be given as PCRE2_ZERO_TERMINATED for a subject that is terminated by a binary zero code unit. The options are:

• PCRE2_ANCHORED — Match only at the first position.
• PCRE2_COPY_MATCHED_SUBJECT — On success, make a private subject copy.
• PCRE2_DISABLE_RECURSELOOP_CHECK — Only useful in rare cases; use with care.
• PCRE2_ENDANCHORED — Pattern can match only at end of subject.
• PCRE2_NOTBOL — Subject string is not the beginning of a line.
• PCRE2_NOTEOL — Subject string is not the end of a line.
• PCRE2_NOTEMPTY — An empty string is not a valid match.
• PCRE2_NOTEMPTY_ATSTART — An empty string at the start of the subject is not a valid match.
• PCRE2_NO_JIT — Do not use JIT matching.
• PCRE2_NO_UTF_CHECK — Do not check the subject for UTF validity (only relevant if PCRE2_UTF was set at compile time).
• PCRE2_PARTIAL_HARD — Return PCRE2_ERROR_PARTIAL for a partial match even if there is a full match.
• PCRE2_PARTIAL_SOFT — Return PCRE2_ERROR_PARTIAL for a partial match if no full matches are found.

For details of partial matching, see the pcre2partial page. There is a complete description of the PCRE2 native API in the pcre2api page and a description of the POSIX API in the pcre2posix page. 🌈

---

That’s the whole vibe check, bestie! 💖 Catch you in the next page. — PCRE2 10.47, 27 January 2024, PCRE2_MATCH(3) 🦋✨