PCRE2_COMPILE(3)

💖 PCRE2_COMPILE(3) — Library Functions Manual 💖

🌸 NAME 🌸

okay so this page is all about PCRE2 — Perl-compatible regular expressions (revised API) — and specifically the pcre2_compile() function. It's giving "turn my regex string into a compiled object" energy, and honestly? iconic. 💅

---

✨ SYNOPSIS ✨

first things first, include the header and call it like this:

#include <pcre2.h>

pcre2_code *pcre2_compile(PCRE2_SPTR pattern, PCRE2_SIZE length,
  uint32_t options, int *errorcode, PCRE2_SIZE *erroroffset,
  pcre2_compile_context *ccontext);

---

💅 DESCRIPTION 💅

This function compiles a regular expression pattern into an internal form. Its arguments are:

• pattern — a string containing expression to be compiled
• length — the length of the string or PCRE2_ZERO_TERMINATED
• options — primary option bits
• errorcode — where to put an error code
• erroffset — where to put an error offset
• ccontext — pointer to a compile context or NULL

The length of the pattern and any error offset that is returned are in code units, not characters. A NULL pattern with zero length is treated as an empty string. A compile context is needed only if you want to provide custom memory allocation functions, or to provide an external function for system stack size checking (see pcre2_set_compile_recursion_guard()), or to change one or more of these parameters:

• What \R matches (Unicode newlines, or CR, LF, CRLF only);
• PCRE2's character tables;
• The newline character sequence;
• The compile time nested parentheses limit;
• The maximum pattern length (in code units) that is allowed;
• The additional options bits.

The primary option bits are:

• PCRE2_ANCHORED — force pattern anchoring
• PCRE2_ALLOW_EMPTY_CLASS — allow empty classes
• PCRE2_ALT_BSUX — alternative handling of \u, \U, and \x
• PCRE2_ALT_CIRCUMFLEX — alternative handling of ^ in multiline mode
• PCRE2_ALT_EXTENDED_CLASS — alternative extended character class syntax
• PCRE2_ALT_VERBNAMES — process backslashes in verb names
• PCRE2_AUTO_CALLOUT — compile automatic callouts
• PCRE2_CASELESS — do caseless matching
• PCRE2_DOLLAR_ENDONLY — $ not to match newline at end
• PCRE2_DOTALL — . matches anything including NL
• PCRE2_DUPNAMES — allow duplicate names for subpatterns
• PCRE2_ENDANCHORED — pattern can match only at end of subject
• PCRE2_EXTENDED — ignore white space and # comments
• PCRE2_FIRSTLINE — force matching to be before newline
• PCRE2_LITERAL — pattern characters are all literal
• PCRE2_MATCH_INVALID_UTF — enable support for matching invalid UTF
• PCRE2_MATCH_UNSET_BACKREF — match unset backreferences
• PCRE2_MULTILINE — ^ and $ match newlines within data
• PCRE2_NEVER_BACKSLASH_C — lock out the use of \C in patterns
• PCRE2_NEVER_UCP — lock out PCRE2_UCP, e.g. via (*UCP)
• PCRE2_NEVER_UTF — lock out PCRE2_UTF, e.g. via (*UTF)
• PCRE2_NO_AUTO_CAPTURE — disable numbered capturing parentheses (named ones available)
• PCRE2_NO_AUTO_POSSESS — disable auto-possessification
• PCRE2_NO_DOTSTAR_ANCHOR — disable automatic anchoring for .*
• PCRE2_NO_START_OPTIMIZE — disable match-time start optimizations
• PCRE2_NO_UTF_CHECK — do not check the pattern for UTF validity (only relevant if PCRE2_UTF is set)
• PCRE2_UCP — use Unicode properties for \d, \w, etc.
• PCRE2_UNGREEDY — invert greediness of quantifiers
• PCRE2_USE_OFFSET_LIMIT — enable offset limit for unanchored matching
• PCRE2_UTF — treat pattern and subjects as UTF strings

PCRE2 must be built with Unicode support (the default) in order to use PCRE2_UTF, PCRE2_UCP and related options.

Additional options may be set in the compile context via the pcre2_set_compile_extra_options function.

If either of errorcode or erroroffset is NULL, the function returns NULL immediately. Otherwise, the yield of this function is a pointer to a private data structure that contains the compiled pattern, or NULL if an error was detected. In the error case, a text error message can be obtained by passing the value returned via the errorcode argument to the pcre2_get_error_message() function. The offset (in code units) where the error was encountered is returned via the erroroffset argument.

If there is no error, the value passed via errorcode returns the message "no error" if passed to pcre2_get_error_message(), and the value passed via erroroffset is zero.

There is a complete description of the PCRE2 native API, with more detail on each option, in the pcre2api page, and a description of the POSIX API in the pcre2posix page.

---

🌈 signed with love and exact bytes: PCRE2 10.47, 30 October 2024 — bye bestie, go compile something iconic 💅✨