Synopsis

#include <pcre2.h>

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

Description

This function 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

start_offset

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 start_offset 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.