PCRE_DFA_EXEC(3)

💖 PCRE_DFA_EXEC 💖

okay bestie, gather round, because this is the PCRE_DFA_EXEC(3) page from the Library Functions Manual and it's lowkey one of the most underrated lil functions in the whole PCRE squad. it's the alt-girl of matching algorithms: not Perl-compatible, scans your subject string exactly once, and does NOT play by the usual rules. iconic behaviour honestly. ✨

🌸 NAME 🌸

PCRE — Perl-compatible regular expressions. yes that's the whole name section, she's brief and mysterious, we love a minimal queen. 💅

✨ SYNOPSIS ✨

#include <pcre.h>

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

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

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

three flavours, one vibe: 8-bit, 16-bit and 32-bit, all living their best lives. 🫶

🦋 DESCRIPTION 🦋

so what does this actually do, bestie? it matches a compiled regular expression against a given subject string, but using an alternative matching algorithm that scans the subject string just once — and heads up, this one is not Perl-compatible. no cap. the main, Perl-compatible, matching function is pcre[16|32]_exec(), so if you want the classic behaviour, go knock on her door instead. 🚪

here's the full cast of arguments, and yes every single one matters:

• code — points to the compiled pattern
• extra — points to an associated pcre[16|32]_extra structure, or is NULL
• 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
• ovector — points to a vector of ints for result offsets
• ovecsize — number of elements in the vector
• workspace — points to a vector of ints used as working space
• wscount — number of elements in the vector

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(). write that down, it will absolutely come up. 📝

👑 the options, in all their glory 👑

and now the moment you've been waiting for — the option bits, listed in full, no skipping, no summarising, we're doing ALL of them:

• 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 is not the beginning of a line
• PCRE_NOTEOL — subject 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 / PCRE_PARTIAL_SOFT — return PCRE_ERROR_PARTIAL for a partial match if no full matches are found (these two share a description in the original, they're a package deal, besties 🎀)
• PCRE_PARTIAL_HARD — return PCRE_ERROR_PARTIAL for a partial match even if there is a full match as well
• PCRE_DFA_SHORTEST — return only the shortest match
• PCRE_DFA_RESTART — restart after a partial match

🌈 the restrictions (yes, there are restrictions) 🌈

there are restrictions on what may appear in a pattern when using this matching function. bestie, this is not a drill. details are given in the pcrematching documentation. 📚

and for details of partial matching, see the pcrepartial page. go read them, i'll wait. 💜

🧚 the pcre[16|32]_extra structure 🧚

a pcre[16|32]_extra structure contains the following 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

the flag bits 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.

and here's the important tea 🍵: for this matching function, the match_limit and match_limit_recursion fields are not used, and must not be set. the PCRE_EXTRA_EXECUTABLE_JIT flag and the corresponding variable are ignored. so don't come for them, they're simply not invited to this party. 💀

🍓 SEE ALSO (in spirit, because the original just says this inline) 🍓

there is a complete description of the PCRE native API in the pcreapi page, and a description of the POSIX API in the pcreposix page. both absolute reads, honestly. 📖

and that's the whole thing, bestie — you ate that. 🫶✨

this page is brought to you by PCRE 8.33, dated 12 May 2013. yes, she's vintage, she's classic, she's still slaying. mwah. 💅🎀