real Namespace Reference

REAL's public API: real::regex, real::static_regex, real::flags and the match/iterator types built on them. More...

Namespaces
namespace	compat
	Drop-in replacements for <regex>: basic_regex, regex_search / regex_match / regex_replace and the iterator types – backed by REAL's linear-time engine where it can serve the pattern, and by std::regex otherwise, never by a silent divergence.
namespace	detail
	DFA construction internals: subset construction over a flattened NFA. Not a stable API.

Classes
class	basic_match_iterator
	Forward iterator over the non-overlapping matches in a text. More...
class	basic_match_range
	A range of matches, returned by find_iter() and usable in range-for. More...
class	basic_match_result
	The result of a match attempt: success, spans and captures. More...
class	basic_regex
	A compiled regular expression, parameterized on its storage policy. More...
class	dfa
	A multi-rule DFA: maximal-munch (dfa_mode::munch) or which-matched unanchored scan (dfa_mode::which_matched). More...
class	dfa_error
	Thrown when a pattern cannot be represented as a DFA. More...
struct	dfa_match
	The outcome of dfa::match — which rule won, and how many bytes it spans. More...
struct	fixed_string
	A fixed-size string usable as a non-type template parameter. More...
class	regex_error
	The exception every rejected pattern throws: a message with the pattern offset it was found at, plus an error_kind a caller can branch on without parsing what. In a constexpr context (static_regex) reaching the throw is a compile-time error, the message appearing in the diagnostic trace. More...
class	regex_set
	Multi-pattern set: which patterns match the subject at least once. More...

Typedefs
using	regex = basic_regex< detail::dynamic_storage >
	The runtime-compiled regex type — the primary entry point.
using	match_result = regex::result_type
	The result type of the default, runtime-compiled real::regex.
using	owning_match_result = regex::owning_result_type
	What a single attempt on a TEMPORARY real::regex returns, owning its name context rather than borrowing it (see real::basic_regex::owning_result_type).
template<fixed_string Pattern, flags F = flags::none>
using	static_regex = basic_regex< detail::static_storage< Pattern, F > >
	A fully compile-time regex.

Enumerations
enum class	flags : std::uint16_t {   none = 0 , icase = 1 , multiline = 2 , dotall = 4 ,   bytes = 8 , verbose = 16 , ecma = 32 , ascii = 64 ,   dollar_endonly = 128 , allow_raw_byte = 256 , ungreedy = 512 }
	Compilation flags, mirroring Python's re.I, re.M and re.S. More...
enum class	match_semantics : std::uint8_t { first = 0 , longest = 1 }
	Which match a search returns among those starting at the leftmost position. Opt-in: first below is what a search uses unless asked otherwise. More...
enum class	error_kind : std::uint8_t { syntax , unsupported }
	Whether a rejected pattern is malformed (syntax) or well formed but beyond REAL's linear engine (unsupported). More...
enum class	dfa_mode : std::uint8_t { munch = 0 , which_matched = 1 }
	Build mode for real::dfa. More...

Functions
constexpr flags	operator| (flags lhs, flags rhs)
	Bitwise-OR of two flag sets.
constexpr flags	operator& (flags lhs, flags rhs)
	Bitwise-AND of two flag sets.
constexpr flags	flags_without (flags value, flags removed)
	value with every flag in removed cleared – the (?flags-flags) removal.
constexpr bool	has_flag (flags value, flags flag)
	Tests whether flag is set in value.

Variables
constexpr std::size_t	npos {std::numeric_limits<std::size_t>::max()}
	Sentinel for "no position" / unset capture slot (akin to std::string::npos).

Detailed Description

REAL's public API: real::regex, real::static_regex, real::flags and the match/iterator types built on them.

Typedef Documentation

match_result

using real::match_result = typedef regex::result_type

The result type of the default, runtime-compiled real::regex.

DERIVED, not re-spelled, and that is the whole point. Until v2026.8.8 this alias named basic_match_result<std::vector<std::size_t>> while the dynamic policy's slots are SBO-backed, so the type documented as "what `real::regex` returns" was not that type and declaring a variable with it did not compile. Nothing detected it because the alias RESTATED a type instead of asking for it; the restatement and the thing it restated were free to drift apart, and did, from the first commit. Deriving it makes that class of drift unrepresentable rather than merely detectable — the same reason real::regex and real::static_regex never drifted.

static_regex

template<fixed_string Pattern, flags F = flags::none>

using real::static_regex = typedef basic_regex<detail::static_storage<Pattern, F> >

A fully compile-time regex.

The pattern is parsed, compiled and exactly sized at compile time; matching allocates nothing and also works in a constexpr context. An invalid pattern is a compile error.

Template Parameters

Pattern	The pattern, as a fixed_string literal.
F	Compilation flags.

Enumeration Type Documentation

dfa_mode

enum class real::dfa_mode : std::uint8_t

strong

Build mode for real::dfa.

munch — maximal-munch at the cursor (lexer; default, SciLex). which_matched — unanchored multi-accept single-pass (Stage-2 RegexSet fused).

Enumerator
munch	One winner at the start of the subject (existing contract).
which_matched	Mid-stream restart; full accept-mask per state for which-matched.

error_kind

enum class real::error_kind : std::uint8_t

strong

Whether a rejected pattern is malformed (syntax) or well formed but beyond REAL's linear engine (unsupported).

unsupported covers a backreference, a conditional, and a lookaround that is not bounded — the constructs a linear-time engine cannot represent at all. It is a stable, machine-readable classification the C ABI exposes, so a binding never has to grep regex_error::what.

There is no native escape hatch, by design — a real::regex is the linear engine or nothing. A caller who must run such a pattern anyway constructs a real::compat::regex from real/compat/std/regex.hpp with real::compat::policy::fallback, which delegates it to std::regex and forfeits the linear-time guarantee for that pattern only.

flags

enum class real::flags : std::uint16_t

strong

Compilation flags, mirroring Python's re.I, re.M and re.S.

Combinable with operator|. Case folding under flags::icase is Unicode in text mode and ASCII-only under flags::ascii (same split as the enumerator below and docs/divergences).

Enumerator
none	No flags.
icase	Case-insensitive (Unicode fold in text mode; ASCII under flags::ascii).
multiline	^ and $ also match at line boundaries.
dotall	. also matches \n.
bytes	Binary mode: . and [^…] match raw bytes, not codepoints.
verbose	Verbose mode (re.X): ignore unescaped whitespace and # comments outside classes.
ecma	ECMAScript compatibility: $ (no multiline) matches only at the very end (not before a final \n, the Python default), AND . (no dotall) also excludes \r (ECMAScript excludes \n and \r; the multi-byte U+2028/U+2029 have no byte-level effect).
ascii	ASCII mode (re.A): \d \w \s \b stay ASCII and icase folds ASCII only, even in text mode. ., explicit classes and UTF-8 literals stay code-point-aware.
dollar_endonly	$ (no multiline) matches only at the very end of the text, never before a final \n — the Rust/\z semantics. Unlike flags::ecma this touches $ ONLY, leaving . at the Python default. Used by the Rust binding for drop-in parity.
allow_raw_byte	Permits \C (RE2's raw-byte escape) outside flags::bytes too. For byte-offset-native consumers only (e.g. real::compat::re2); a \C span can land mid-codepoint. flags::bytes already allows \C.
ungreedy	Ungreedy mode (RE2 (?U)): swap the default quantifier greediness — a bare quantifier becomes lazy and the explicit ? suffix re-inverts back to greedy ((?U)a+ matches minimally, (?U)a+? maximally). Resolved entirely at parse time into each repeat node's lazy bit (the compiler and VM never read this flag), and scoped like the other inline letters: (?U:…), (?-U:…) and the constructor flag all work through the flag-scope stack.

match_semantics

enum class real::match_semantics : std::uint8_t

strong

Which match a search returns among those starting at the leftmost position. Opt-in: first below is what a search uses unless asked otherwise.

Enumerator
first	Leftmost-first (Perl / Python re / the crate): source-order thread priority decides. Default.
longest	Leftmost-longest (POSIX / RE2 set_longest_match): the longest overall match wins the bounds.

Function Documentation

flags_without()

constexpr flags real::flags_without ( flags  value, flags  removed  )

constexpr

value with every flag in removed cleared – the (?flags-flags) removal.

There is no operator~ for flags on purpose: complementing a 16-bit enum would set every unassigned bit, and the result would be a flag set naming flags that do not exist. This states the whole operation instead. The intermediate width is unsigned, so the complement happens before the narrowing cast – doing it in std::uint16_t would drop flags::ungreedy (512) on a std::uint8_t-width intermediate, which is the exact bug the parser's own helper was written to avoid.

Parameters

[in]	value	The flag set to clear from.
[in]	removed	The flags to clear.

Returns

value without removed.

has_flag()

constexpr bool real::has_flag ( flags  value, flags  flag  )

constexpr

Tests whether flag is set in value.

Parameters

[in]	value	The flag set to query.
[in]	flag	The single flag to look for.

Returns

true if flag is present in value.

operator&()

constexpr flags real::operator& ( flags  lhs, flags  rhs  )

constexpr

Bitwise-AND of two flag sets.

Parameters

[in]	lhs	First flag set.
[in]	rhs	Second flag set.

Returns

The intersection of lhs and rhs.

operator|()

constexpr flags real::operator| ( flags  lhs, flags  rhs  )

constexpr

Bitwise-OR of two flag sets.

Parameters

[in]	lhs	First flag set.
[in]	rhs	Second flag set.

Returns

The union of lhs and rhs.