PCRE_EXEC(3)

💖 PCRE_EXEC(3) 💖

okay bestie, gather round, because this is the pcre_exec page from the Library Functions Manual and it's literally the moment your regex stops being a vibe and starts being results. 🎀

✨ NAME ✨

PCRE — Perl-compatible regular expressions. yes that's it. that's the whole name. iconic, terse, no notes. 💅

🌸 SYNOPSIS 🌸

#include <pcre.h>

int pcre_exec(const pcre *code, const pcre_extra *extra,
     const char *subject, int length, int startoffset,
     int options, int *ovector, int ovecsize);

int pcre16_exec(const pcre16 *code, const pcre16_extra *extra,
     PCRE_SPTR16 subject, int length, int startoffset,
     int options, int *ovector, int ovecsize);

int pcre32_exec(const pcre32 *code, const pcre32_extra *extra,
     PCRE_SPTR32 subject, int length, int startoffset,
     int options, int *ovector, int ovecsize);

three flavors, one vibe: 8-bit, 16-bit, 32-bit. pick your fighter. ⭐

🦋 DESCRIPTION 🦋

So what does this function do, you ask? It takes a compiled regular expression and matches it against a subject string you hand it, using a matching algorithm that's similar to Perl's. Then it returns offsets to the captured substrings, aka the receipts, aka the exact positions where your regex popped off. 📍

Here's the whole cast of arguments, one by one:

• code — points to the compiled pattern. the main character. 👑
• extra — points to an associated pcre[16|32]_extra structure, or is NULL if you're going minimal.
• subject — points to the subject string. the thing you're matching against.
• length — length of the subject string.
• startoffset — offset in the subject at which to start matching. like, don't start at the beginning, start here. ✨
• options — option bits.
• ovector — points to a vector of ints for result offsets.
• ovecsize — number of elements in the vector (a multiple of 3).

Quick unit check before we move on, because this matters: the units for length and startoffset are bytes for pcre_exec(), 16-bit data items for pcre16_exec(), and 32-bit items for pcre32_exec(). don't mix those up, i'm begging. 🙈

🌈 the options (all of them, no skipping, periodt)

• PCRE_ANCHORED — match only at the first position.
• PCRE_BSR_ANYCRLF — \R matches only CR, LF, or CRLF.
• PCRE_BSR_UNICODE — \R matches all Unicode line endings.
• PCRE_NEWLINE_ANY — recognize any Unicode newline sequence.
• PCRE_NEWLINE_ANYCRLF — recognize CR, LF, & CRLF as newline sequences.
• PCRE_NEWLINE_CR — recognize CR as the only newline sequence.
• PCRE_NEWLINE_CRLF — recognize CRLF as the only newline sequence.
• PCRE_NEWLINE_LF — recognize LF as the only newline sequence.
• PCRE_NOTBOL — subject string is not the beginning of a line.
• PCRE_NOTEOL — subject string is not the end of a line.
• PCRE_NOTEMPTY — an empty string is not a valid match.
• PCRE_NOTEMPTY_ATSTART — an empty string at the start of the subject is not a valid match.
• PCRE_NO_START_OPTIMIZE — do not do "start-match" optimizations.
• PCRE_NO_UTF16_CHECK — do not check the subject for UTF-16 validity (only relevant if PCRE_UTF16 was set at compile time).
• PCRE_NO_UTF32_CHECK — do not check the subject for UTF-32 validity (only relevant if PCRE_UTF32 was set at compile time).
• PCRE_NO_UTF8_CHECK — do not check the subject for UTF-8 validity (only relevant if PCRE_UTF8 was set at compile time).
• PCRE_PARTIAL — return PCRE_ERROR_PARTIAL for a partial match if no full matches are found.
• PCRE_PARTIAL_SOFT — return PCRE_ERROR_PARTIAL for a partial match if no full matches are found.
• PCRE_PARTIAL_HARD — return PCRE_ERROR_PARTIAL for a partial match if that is found before a full match.

ngl, notice how PCRE_PARTIAL and PCRE_PARTIAL_SOFT share that description in the original? that's not a typo on my part, that's the actual grouping. keep them together, bestie. 🫶

For the details of partial matching, go read the pcrepartial page. 🧚

🎀 the pcre_extra structure, field by field

A pcre_extra structure contains these fields:

• flags — bits indicating which fields are set.
• study_data — opaque data from pcre[16|32]_study().
• match_limit — limit on internal resource use.
• match_limit_recursion — limit on internal recursion depth.
• callout_data — opaque data passed back to callouts.
• tables — points to character tables or is NULL.
• mark — for passing back a *MARK pointer.
• executable_jit — opaque data from JIT compilation.

and the flag bits themselves are: PCRE_EXTRA_STUDY_DATA, PCRE_EXTRA_MATCH_LIMIT, PCRE_EXTRA_MATCH_LIMIT_RECURSION, PCRE_EXTRA_CALLOUT_DATA, PCRE_EXTRA_TABLES, PCRE_EXTRA_MARK and PCRE_EXTRA_EXECUTABLE_JIT. 💜

There's a complete description of the PCRE native API in the pcreapi page, and a description of the POSIX API in the pcreposix page. go read those too, i'm not gonna gatekeep. 📚

and that's the whole page, bestie — written for PCRE 8.33, dated 12 May 2013. yeah, it's giving vintage, but the knowledge is timeless and so are you. slay, compile safely, and may all your matches be full ones. 💖✨🎀🦋🌸💅