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>, 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_fidelity
	The answer of real::dfa_faithful. More...
struct	dfa_match
	The outcome of dfa::match — which rule won, and how many bytes it spans. More...
struct	dfa_munch
	A munch, and whether text after the subject could change it (dfa::munch). More...
class	dfa_munch_memo
	What successive munches over ONE subject have learnt, so that tokenizing the whole subject costs O(states × length) instead of O(length²) (Reps, "Maximal-munch tokenization in linear time", 1998). 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, the pattern offset, and an error_kind to branch on. In a constexpr context (static_regex) the throw is a compile-time error whose trace carries the message. 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 (default first). 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: maximal munch at the cursor (a lexer; the default), or an unanchored multi-accept single pass (which patterns match anywhere). More...
enum class	dfa_fidelity_outcome : std::uint8_t { faithful = 0 , divergent = 1 , undecided = 2 }
	The three answers real::dfa_faithful can give. 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.
dfa_fidelity	dfa_faithful (const regex &pattern, std::size_t state_budget=dfa_default_state_budget)
	Decides whether pattern's match() is always its longest match – whether a dfa built from it reproduces pattern.match() on every input.
dfa_fidelity	dfa_faithful (std::span< const regex > patterns, std::size_t state_budget=dfa_default_state_budget)
	Decides real::dfa_faithful for each of patterns, in order, and answers for the first one not proven faithful (its index in dfa_fidelity::rule_index).

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).
constexpr std::size_t	dfa_default_state_budget {65536}
	The default search budget of real::dfa_faithful, in product states: the default cap a dfa's own construction runs under. A build that lowers that cap (REAL_MAX_DFA_STATES) keeps this budget; its construction then refuses, with real::dfa_error, what the search accepts.

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, so it cannot drift from what real::regex returns.

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_fidelity_outcome

enum class real::dfa_fidelity_outcome : std::uint8_t

strong

The three answers real::dfa_faithful can give.

Enumerator
faithful	match() equals the longest match on every input: the DFA reproduces it.
divergent	Some input separates them; dfa_fidelity::witness is one.
undecided	The search hit its state budget. Treat as not faithful; never as faithful.

dfa_mode

enum class real::dfa_mode : std::uint8_t

strong

Build mode for real::dfa: maximal munch at the cursor (a lexer; the default), or an unanchored multi-accept single pass (which patterns match anywhere).

Enumerator
munch	One winner at the start of the subject.
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 an unbounded lookaround, which a linear-time engine cannot represent. Stable and exposed by the C ABI, so a binding never parses regex_error::what.

real::regex has no escape hatch. To run such a pattern anyway, construct a real::compat::regex (real/compat/std/regex.hpp) with real::compat::policy::fallback: it delegates that pattern to std::regex and forfeits the linear-time guarantee for it 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|. flags::icase folds Unicode in text mode, ASCII only under flags::ascii.

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: $ (no multiline) matches only at the very end, not before a final \n; . (no dotall) also excludes \r.
ascii	ASCII mode (re.A): \d \w \s \b and icase stay ASCII, even in text mode. ., explicit classes and UTF-8 literals stay code-point-aware.
dollar_endonly	$ (no multiline) matches only at the very end, never before a final \n (Rust \z). Unlike flags::ecma, . keeps the Python default.
allow_raw_byte	Permits \C (RE2's raw byte) outside flags::bytes, which always allows it. For byte-offset consumers (real::compat::re2): a \C span can end mid-code-point.
ungreedy	RE2 (?U): a bare quantifier is lazy and a ? suffix makes it greedy. Resolved at parse time; scoped like the inline flags ((?U:…), (?-U:…)).

match_semantics

enum class real::match_semantics : std::uint8_t

strong

Which match a search returns among those starting at the leftmost position (default first).

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

Function Documentation

dfa_faithful() [1/2]

dfa_fidelity real::dfa_faithful ( const regex &  pattern, std::size_t  state_budget = dfa_default_state_budget  )

inline

Decides whether pattern's match() is always its longest match – whether a dfa built from it reproduces pattern.match() on every input.

The answer is EXACT for the pattern, never a sample: faithful holds for every input, and divergent comes with an input that proves it. Only the search's size is bounded; past state_budget the answer is undecided, which a caller must treat as not faithful.

Parameters

[in]	pattern	The pattern to decide.
[in]	state_budget	Product states the search may explore.

Returns

The decision, with a witness when divergent.

Exceptions

real::dfa_error

for a pattern that is not DFA-able (see dfa_error).

dfa_faithful() [2/2]

dfa_fidelity real::dfa_faithful ( std::span< const regex >  patterns, std::size_t  state_budget = dfa_default_state_budget  )

inline

Decides real::dfa_faithful for each of patterns, in order, and answers for the first one not proven faithful (its index in dfa_fidelity::rule_index).

faithful means every pattern is, which is SUFFICIENT for a dfa over the set to reproduce the per-rule match() munch (longest wins, earliest on a tie, empty never wins): with every rule's match() equal to its longest match, both reach the same length and the same earliest rule. It is not NECESSARY – a divergent rule that a higher-priority rule always outlasts changes no answer, and this still refuses the set. That refusal is correct, only cautious; an acceptance is never wrong.

Parameters

[in]	patterns	The patterns, in priority order.
[in]	state_budget	Product states each pattern's search may explore.

Returns

The first non-faithful pattern's decision, or faithful.

Exceptions

real::dfa_error

for a pattern that is not DFA-able (see dfa_error).

flags_without()

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

constexpr

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

No operator~ on purpose: a complement sets every unassigned bit, naming flags that do not exist. The complement is taken in unsigned and narrowed after; a std::uint8_t intermediate would drop flags::ungreedy (512).

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.