Support types#

Synopsis#

The native engine’s public auxiliary types: flags (the compile options and their inline-letter equivalents), match_semantics (which match a search returns), fixed_string (the compile-time pattern literal behind static_regex), and regex_error with its machine-readable error_kind (the exception every rejection raises – never a silent divergence). Data types: no runtime cost of their own.

The everyday flags are icase, multiline, dotall, ascii and verbose – the same letters as (?imsxa) in the pattern. bytes, ecma, dollar_endonly, allow_raw_byte and ungreedy exist for drop-in parity with another surface; you rarely set them on real::regex directly.

Interface#

enum class real::flags : std::uint16_t#

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.

Values:

enumerator none#

No flags.

enumerator icase#

Case-insensitive (Unicode fold in text mode; ASCII under flags::ascii).

enumerator multiline#

^ and $ also match at line boundaries.

enumerator dotall#

. also matches \n.

enumerator bytes#

Binary mode: . and [^…] match raw bytes, not codepoints.

enumerator verbose#

Verbose mode (re.X): ignore unescaped whitespace and # comments outside classes.

enumerator ecma#

ECMAScript: $ (no multiline) matches only at the very end, not before a final \n; . (no dotall) also excludes \r.

enumerator 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.

enumerator dollar_endonly#

$ (no multiline) matches only at the very end, never before a final \n (Rust \z). Unlike flags::ecma, . keeps the Python default.

enumerator 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.

enumerator 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:…)).

enum class real::match_semantics : std::uint8_t#

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

Values:

enumerator first#

Leftmost-first (Perl / Python re): source-order priority decides. Default.

enumerator longest#

Leftmost-longest (POSIX / RE2 set_longest_match): the longest match wins.

template<std::size_t N>
struct fixed_string#

A fixed-size string usable as a non-type template parameter.

Enables static_regex<"\d+">: the literal is captured into data at compile time.

Template Parameters:

N – Size of the character array, including the terminating NUL.

Public Functions

inline constexpr fixed_string(const char (&literal)[N])#

Captures a string literal. Implicit, so a string literal can be the template argument.

Parameters:

literal – [in] The string literal to capture.

inline constexpr std::string_view view() const#

Returns a view of the string, excluding the trailing NUL.

Returns:

A view of the N-1 pattern characters.

Public Members

char data[N] = {}#

The captured characters, including the trailing NUL.

class regex_error : public std::exception#

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.

Public Functions

inline regex_error(const std::string &message, std::size_t position, error_kind kind = error_kind::syntax)#

Builds the error.

Parameters:

  • message – [in] Human-readable cause.

  • position – [in] Byte offset in the pattern where the error was found.

  • kind – [in] Whether the pattern is malformed or merely unsupported (default syntax).

inline error_kind kind() const noexcept#

Whether the pattern is malformed (syntax) or well-formed but unsupported by REAL.

Returns:

The classification.

inline const char *what() const noexcept override#

Returns the formatted error message (with position).

Returns:

The message, valid for this object’s lifetime.

inline std::size_t position() const noexcept#

Returns the byte offset in the pattern where the error was found.

Returns:

The offset into the pattern text.

inline const std::string &cause() const noexcept#

Returns the cause WITHOUT the regex_error at N: prefix that what adds.

For a consumer that reports the position itself (a Python error.pos, a rethrow adding context), so none re-parses the formatted message.

Returns:

The unprefixed message, valid for this object’s lifetime.

enum class real::error_kind : std::uint8_t#

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.

Values:

enumerator syntax#
enumerator unsupported#

Example#

Compiled and run by the example-check gate on every push:

  // flags combine bitwise at construction (the (?imsxa) inline letters work too).
  const real::regex ci {"real", real::flags::icase};
  std::cout << ci.search("the REAL engine").matched() << "\n";  // 1

  // Every rejection raises real::regex_error -- never a silent divergence.
  bool rejected = false;
  try {
    const real::regex bad {R"((a+)\1)"};  // backreference: rejected up front
  } catch (const real::regex_error&) {
    rejected = true;
  }
  std::cout << rejected << "\n";  // 1

See also#