pcre2_match

PCRE2 10.50-DEV manual; updated

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.