REAL
Regular Expression Algorithmic Library — constexpr C++20 regex
Loading...
Searching...
No Matches
real::compat::basic_regex< CharT, Traits > Class Template Reference

A std::basic_regex-compatible pattern, backed by REAL where it can serve the pattern, else by std. More...

#include <regex_core.hpp>

Collaboration diagram for real::compat::basic_regex< CharT, Traits >:
[legend]

Public Types

using value_type = CharT
 Character type.
 
using traits_type = Traits
 Regex traits (std parity).
 
using string_type = std::basic_string< CharT >
 Pattern string type.
 
using flag_type = regex_constants::syntax_option_type
 Option type.
 
using locale_type = typename Traits::locale_type
 The traits' locale type (std parity).
 

Public Member Functions

 basic_regex ()=default
 An empty pattern on the std backend — the variant's first alternative default-constructs.
 
 basic_regex (const CharT *pattern, flag_type f=regex_constants::ECMAScript, policy pol=policy::strict)
 Compiles pattern from a C string.
 
 basic_regex (const string_type &pattern, flag_type f=regex_constants::ECMAScript, policy pol=policy::strict)
 Compiles pattern from an owned string.
 
 basic_regex (const CharT *pattern, std::size_t len, flag_type f=regex_constants::ECMAScript, policy pol=policy::strict)
 Compiles the first len characters of pattern, which need not be NUL-terminated.
 
template<typename It >
 basic_regex (It begin, It end, flag_type f=regex_constants::ECMAScript, policy pol=policy::strict)
 Compiles the pattern in [begin, end).
 
 basic_regex (std::initializer_list< CharT > pattern, flag_type f=regex_constants::ECMAScript, policy pol=policy::strict)
 Compiles the characters of pattern.
 
basic_regex & operator= (const CharT *pattern)
 Replaces the pattern with pattern, as assign(pattern).
 
basic_regex & operator= (std::initializer_list< CharT > pattern)
 Replaces the pattern with pattern, as assign(pattern).
 
template<typename ST , typename SA >
basic_regex & operator= (const std::basic_string< CharT, ST, SA > &pattern)
 Replaces the pattern with pattern, as assign(pattern).
 
basic_regex & assign (const basic_regex &other)
 Becomes a copy of other.
 
basic_regex & assign (basic_regex &&other) noexcept
 Takes other's pattern.
 
basic_regex & assign (const CharT *pattern, flag_type f=regex_constants::ECMAScript)
 Compiles pattern in place of the current one, under this regex's policy. Every overload gives the strong guarantee std's does: on a throw *this is unchanged.
 
basic_regex & assign (const CharT *pattern, std::size_t len, flag_type f=regex_constants::ECMAScript)
 Compiles the first len characters of pattern in place of the current pattern.
 
template<typename ST , typename SA >
basic_regex & assign (const std::basic_string< CharT, ST, SA > &pattern, flag_type f=regex_constants::ECMAScript)
 Compiles pattern in place of the current pattern.
 
template<typename InputIt >
basic_regex & assign (InputIt first, InputIt last, flag_type f=regex_constants::ECMAScript)
 Compiles the pattern in [first, last) in place of the current pattern.
 
basic_regex & assign (std::initializer_list< CharT > pattern, flag_type f=regex_constants::ECMAScript)
 Compiles the characters of pattern in place of the current pattern.
 
std::size_t mark_count () const noexcept
 Number of marked sub-expressions (excluding group 0), as std::basic_regex.
 
flag_type flags () const noexcept
 The flags this regex was built with.
 
void swap (basic_regex &other) noexcept
 Exchanges engines, flags, policy and cached state with other.
 
bool uses_real () const noexcept
 True if this regex is backed by the real engine (vs the std fallback).
 
bool uses_fallback () const noexcept
 True if std::regex holds this pattern, which then has no linear-time guarantee: a pattern REAL cannot serve under policy::fallback, any non-char instantiation, a default-constructed regex.
 
compat::policy policy () const noexcept
 The drop-in policy this regex was constructed with.
 
const std::variant< std::basic_regex< CharT, Traits >, real::regex > & engine () const noexcept
 Access the active backend (engine-facing; used by the free functions).
 
bool nullable () const noexcept
 Whether the pattern can match the empty string; under a POSIX grammar a nullable pattern's replace and iteration run on std (uses_real_traversal).
 
bool posix_longest () const noexcept
 Whether a POSIX grammar was translated onto REAL (detail::translate_posix): a search then takes leftmost-longest overall bounds, while captures stay the winning thread's rather than following POSIX subexpression rules. False on the std backend, which applies POSIX itself.
 
bool uses_real_traversal () const noexcept
 Whether replace and iteration run on REAL: real-backed, not a nullable POSIX pattern (std's leftmost-longest empty-match traversal is not modelled), and no capturing group nullable under a quantifier ((ab|)+a): REAL captures its last consuming iteration, libstdc++ and libc++ an extra empty one. Search and match keep that one capture divergence, by design (docs/COMPATIBILITY.md).
 
const std::basic_regex< CharT, Traits > & std_engine () const
 The std::regex for the std path, built once on demand for a real-backed pattern (a call REAL cannot honor, a traversal it does not model, a $0 format).
 
const real::regex * end_engine (bool not_eol, bool not_eow) const
 The REAL engine a search under match_not_eol / match_not_eow runs: this pattern's own when it has nothing those flags change, else its rewrite (see detail::rewrite_end_context), built once on demand and thread-safely as std_engine is.
 

Static Public Attributes

static constexpr flag_type icase {regex_constants::icase}
 As std::basic_regex::icase.
 
static constexpr flag_type nosubs {regex_constants::nosubs}
 As std::basic_regex::nosubs.
 
static constexpr flag_type optimize {regex_constants::optimize}
 As std::basic_regex::optimize.
 
static constexpr flag_type collate {regex_constants::collate}
 As std::basic_regex::collate.
 
static constexpr flag_type ECMAScript {regex_constants::ECMAScript}
 As std::basic_regex::ECMAScript.
 
static constexpr flag_type basic {regex_constants::basic}
 As std::basic_regex::basic.
 
static constexpr flag_type extended {regex_constants::extended}
 As std::basic_regex::extended.
 
static constexpr flag_type awk {regex_constants::awk}
 As std::basic_regex::awk.
 
static constexpr flag_type grep {regex_constants::grep}
 As std::basic_regex::grep.
 
static constexpr flag_type egrep {regex_constants::egrep}
 As std::basic_regex::egrep.
 
static constexpr flag_type multiline {regex_constants::multiline}
 As std::basic_regex::multiline.
 

Private Member Functions

detail::end_variants build_end_variants () const
 Builds the three not_eol / not_eow variants of this real-backed ECMAScript pattern.
 
detail::end_variant build_end_variant (bool not_eol, bool not_eow) const
 Builds one not_eol / not_eow variant of this real-backed ECMAScript pattern.
 
basic_regex & recompile (std::basic_string_view< CharT > pattern, flag_type f)
 Compiles pattern into a fresh regex under this one's policy, then takes it: a throw leaves *this as it was.
 
void compile (std::basic_string_view< CharT > pattern, flag_type f)
 Compiles pattern into this object, replacing whatever it held.
 
void reject_or_fallback (std::string_view sv, flag_type f, const std::string &reason)
 The policy branch for a pattern REAL cannot serve: strict throws (see regex_error), fallback compiles it on std::regex.
 
void emplace_std (std::string_view sv, flag_type f)
 Compiles sv on the standard-library backend and stores it.
 

Private Attributes

std::variant< std::basic_regex< CharT, Traits >, real::regex > engine_
 Whichever backend compiled this pattern; see uses_real and uses_fallback.
 
string_type pattern_
 The pattern text, for the lazy builds.
 
flag_type flags_ {regex_constants::ECMAScript}
 Syntax options it was compiled with (flags).
 
std::size_t mark_count_ {}
 Capturing groups excluding the whole match (mark_count).
 
bool nullable_ {}
 empty_match_possible (real-backed).
 
bool nullable_captured_repeat_ {}
 A capturing group nullable under a quantifier (real-backed); see uses_real_traversal.
 
bool posix_longest_ {}
 A POSIX grammar translated onto REAL: search uses leftmost-longest bounds.
 
detail::lazy_std_engine< std::basic_regex< CharT, Traits > > lazy_std_
 The std engine, built on demand (std_engine).
 
detail::lazy_std_engine< detail::end_variants > end_variants_
 Lazy REAL variants for match_not_eol / match_not_eow.
 
compat::policy policy_ {policy::strict}
 strict rejects ineligible, fallback delegates to std.
 

Detailed Description

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
class real::compat::basic_regex< CharT, Traits >

A std::basic_regex-compatible pattern, backed by REAL where it can serve the pattern, else by std.

Template Parameters
CharTCharacter type (char; other types route straight to std).
TraitsRegex traits (std parity).

Constructor & Destructor Documentation

◆ basic_regex() [1/5]

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
real::compat::basic_regex< CharT, Traits >::basic_regex ( const CharT *  pattern,
flag_type  f = regex_constants::ECMAScript,
policy  pol = policy::strict 
)
inlineexplicit

Compiles pattern from a C string.

Parameters
[in]patternNUL-terminated pattern text.
[in]fSyntax options; the grammar they select may route the pattern to std.
[in]polStrict rejects a pattern REAL cannot represent linearly; fallback routes it to std.
Exceptions
real::compat::regex_erroron an invalid pattern, or on a strict-policy rejection.

◆ basic_regex() [2/5]

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
real::compat::basic_regex< CharT, Traits >::basic_regex ( const string_type &  pattern,
flag_type  f = regex_constants::ECMAScript,
policy  pol = policy::strict 
)
inlineexplicit

Compiles pattern from an owned string.

Parameters
[in]patternThe pattern text.
[in]fSyntax options.
[in]polRejection policy; see the C-string overload.
Exceptions
real::compat::regex_erroron an invalid pattern, or on a strict-policy rejection.

◆ basic_regex() [3/5]

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
real::compat::basic_regex< CharT, Traits >::basic_regex ( const CharT *  pattern,
std::size_t  len,
flag_type  f = regex_constants::ECMAScript,
policy  pol = policy::strict 
)
inline

Compiles the first len characters of pattern, which need not be NUL-terminated.

Parameters
[in]patternPattern text.
[in]lenIts length in characters.
[in]fSyntax options.
[in]polRejection policy.
Exceptions
real::compat::regex_erroron an invalid pattern, or on a strict-policy rejection.

◆ basic_regex() [4/5]

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
template<typename It >
real::compat::basic_regex< CharT, Traits >::basic_regex ( It  begin,
It  end,
flag_type  f = regex_constants::ECMAScript,
policy  pol = policy::strict 
)
inline

Compiles the pattern in [begin, end).

Parameters
[in]beginStart of the pattern text.
[in]endOne past its end.
[in]fSyntax options.
[in]polRejection policy.
Exceptions
real::compat::regex_erroron an invalid pattern, or on a strict-policy rejection.

◆ basic_regex() [5/5]

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
real::compat::basic_regex< CharT, Traits >::basic_regex ( std::initializer_list< CharT >  pattern,
flag_type  f = regex_constants::ECMAScript,
policy  pol = policy::strict 
)
inline

Compiles the characters of pattern.

Parameters
[in]patternThe pattern text.
[in]fSyntax options.
[in]polRejection policy.
Exceptions
real::compat::regex_erroron an invalid pattern, or on a strict-policy rejection.

Member Function Documentation

◆ assign() [1/7]

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
basic_regex & real::compat::basic_regex< CharT, Traits >::assign ( basic_regex< CharT, Traits > &&  other)
inlinenoexcept

Takes other's pattern.

Parameters
[in,out]otherThe regex to move from.
Returns
*this.

◆ assign() [2/7]

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
basic_regex & real::compat::basic_regex< CharT, Traits >::assign ( const basic_regex< CharT, Traits > &  other)
inline

Becomes a copy of other.

Parameters
[in]otherThe regex to copy.
Returns
*this.

◆ assign() [3/7]

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
basic_regex & real::compat::basic_regex< CharT, Traits >::assign ( const CharT *  pattern,
flag_type  f = regex_constants::ECMAScript 
)
inline

Compiles pattern in place of the current one, under this regex's policy. Every overload gives the strong guarantee std's does: on a throw *this is unchanged.

Parameters
[in]patternNUL-terminated pattern text.
[in]fSyntax options.
Returns
*this.
Exceptions
real::compat::regex_erroron an invalid pattern, or on a strict-policy rejection.

◆ assign() [4/7]

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
basic_regex & real::compat::basic_regex< CharT, Traits >::assign ( const CharT *  pattern,
std::size_t  len,
flag_type  f = regex_constants::ECMAScript 
)
inline

Compiles the first len characters of pattern in place of the current pattern.

Parameters
[in]patternPattern text.
[in]lenIts length in characters.
[in]fSyntax options.
Returns
*this.
Exceptions
real::compat::regex_erroras the C-string overload does; *this is then unchanged.

◆ assign() [5/7]

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
template<typename ST , typename SA >
basic_regex & real::compat::basic_regex< CharT, Traits >::assign ( const std::basic_string< CharT, ST, SA > &  pattern,
flag_type  f = regex_constants::ECMAScript 
)
inline

Compiles pattern in place of the current pattern.

Template Parameters
STThe string's traits.
SAThe string's allocator.
Parameters
[in]patternThe pattern text.
[in]fSyntax options.
Returns
*this.
Exceptions
real::compat::regex_erroras the C-string overload does; *this is then unchanged.

◆ assign() [6/7]

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
template<typename InputIt >
basic_regex & real::compat::basic_regex< CharT, Traits >::assign ( InputIt  first,
InputIt  last,
flag_type  f = regex_constants::ECMAScript 
)
inline

Compiles the pattern in [first, last) in place of the current pattern.

Template Parameters
InputItAn input iterator over characters.
Parameters
[in]firstStart of the pattern text.
[in]lastOne past its end.
[in]fSyntax options.
Returns
*this.
Exceptions
real::compat::regex_erroras the C-string overload does; *this is then unchanged.

◆ assign() [7/7]

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
basic_regex & real::compat::basic_regex< CharT, Traits >::assign ( std::initializer_list< CharT >  pattern,
flag_type  f = regex_constants::ECMAScript 
)
inline

Compiles the characters of pattern in place of the current pattern.

Parameters
[in]patternThe pattern text.
[in]fSyntax options.
Returns
*this.
Exceptions
real::compat::regex_erroras the C-string overload does; *this is then unchanged.

◆ build_end_variant()

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
detail::end_variant real::compat::basic_regex< CharT, Traits >::build_end_variant ( bool  not_eol,
bool  not_eow 
) const
inlineprivate

Builds one not_eol / not_eow variant of this real-backed ECMAScript pattern.

Parameters
[in]not_eolmatch_not_eol is set.
[in]not_eowmatch_not_eow is set.
Returns
The variant.

◆ build_end_variants()

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
detail::end_variants real::compat::basic_regex< CharT, Traits >::build_end_variants ( ) const
inlineprivate

Builds the three not_eol / not_eow variants of this real-backed ECMAScript pattern.

Returns
The variants.

◆ compile()

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
void real::compat::basic_regex< CharT, Traits >::compile ( std::basic_string_view< CharT >  pattern,
flag_type  f 
)
inlineprivate

Compiles pattern into this object, replacing whatever it held.

Parameters
[in]patternThe pattern text.
[in]fSyntax options.
Exceptions
real::compat::regex_erroron an invalid pattern, or on a strict-policy rejection.

◆ emplace_std()

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
void real::compat::basic_regex< CharT, Traits >::emplace_std ( std::string_view  sv,
flag_type  f 
)
inlineprivate

Compiles sv on the standard-library backend and stores it.

Parameters
[in]svThe pattern text.
[in]fSyntax options, translated by detail::to_std.

◆ end_engine()

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
const real::regex * real::compat::basic_regex< CharT, Traits >::end_engine ( bool  not_eol,
bool  not_eow 
) const
inline

The REAL engine a search under match_not_eol / match_not_eow runs: this pattern's own when it has nothing those flags change, else its rewrite (see detail::rewrite_end_context), built once on demand and thread-safely as std_engine is.

Parameters
[in]not_eolmatch_not_eol is set.
[in]not_eowmatch_not_eow is set.
Returns
The engine, or null when the call must go to std (a POSIX grammar, a rewrite REAL does not compile).

◆ engine()

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
const std::variant< std::basic_regex< CharT, Traits >, real::regex > & real::compat::basic_regex< CharT, Traits >::engine ( ) const
inlinenoexcept

Access the active backend (engine-facing; used by the free functions).

Returns
The variant holding whichever backend compiled this pattern.

◆ flags()

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
flag_type real::compat::basic_regex< CharT, Traits >::flags ( ) const
inlinenoexcept

The flags this regex was built with.

Returns
Those flags.

◆ mark_count()

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
std::size_t real::compat::basic_regex< CharT, Traits >::mark_count ( ) const
inlinenoexcept

Number of marked sub-expressions (excluding group 0), as std::basic_regex.

Returns
The group count.

◆ nullable()

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
bool real::compat::basic_regex< CharT, Traits >::nullable ( ) const
inlinenoexcept

Whether the pattern can match the empty string; under a POSIX grammar a nullable pattern's replace and iteration run on std (uses_real_traversal).

Returns
true if it is nullable.

◆ operator=() [1/3]

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
basic_regex & real::compat::basic_regex< CharT, Traits >::operator= ( const CharT *  pattern)
inline

Replaces the pattern with pattern, as assign(pattern).

Parameters
[in]patternNUL-terminated pattern text.
Returns
*this.
Exceptions
real::compat::regex_erroras assign does; *this is then unchanged.

◆ operator=() [2/3]

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
template<typename ST , typename SA >
basic_regex & real::compat::basic_regex< CharT, Traits >::operator= ( const std::basic_string< CharT, ST, SA > &  pattern)
inline

Replaces the pattern with pattern, as assign(pattern).

Template Parameters
STThe string's traits.
SAThe string's allocator.
Parameters
[in]patternThe pattern text.
Returns
*this.
Exceptions
real::compat::regex_erroras assign does; *this is then unchanged.

◆ operator=() [3/3]

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
basic_regex & real::compat::basic_regex< CharT, Traits >::operator= ( std::initializer_list< CharT >  pattern)
inline

Replaces the pattern with pattern, as assign(pattern).

Parameters
[in]patternThe pattern text.
Returns
*this.
Exceptions
real::compat::regex_erroras assign does; *this is then unchanged.

◆ policy()

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
compat::policy real::compat::basic_regex< CharT, Traits >::policy ( ) const
inlinenoexcept

The drop-in policy this regex was constructed with.

Returns
Strict or fallback.

◆ posix_longest()

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
bool real::compat::basic_regex< CharT, Traits >::posix_longest ( ) const
inlinenoexcept

Whether a POSIX grammar was translated onto REAL (detail::translate_posix): a search then takes leftmost-longest overall bounds, while captures stay the winning thread's rather than following POSIX subexpression rules. False on the std backend, which applies POSIX itself.

Returns
true under a POSIX grammar that REAL is running.

◆ recompile()

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
basic_regex & real::compat::basic_regex< CharT, Traits >::recompile ( std::basic_string_view< CharT >  pattern,
flag_type  f 
)
inlineprivate

Compiles pattern into a fresh regex under this one's policy, then takes it: a throw leaves *this as it was.

Parameters
[in]patternThe pattern text.
[in]fSyntax options.
Returns
*this.
Exceptions
real::compat::regex_erroron an invalid pattern, or on a strict-policy rejection.

◆ reject_or_fallback()

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
void real::compat::basic_regex< CharT, Traits >::reject_or_fallback ( std::string_view  sv,
flag_type  f,
const std::string &  reason 
)
inlineprivate

The policy branch for a pattern REAL cannot serve: strict throws (see regex_error), fallback compiles it on std::regex.

Parameters
[in]svThe pattern text.
[in]fSyntax options.
[in]reasonMessage carried by the thrown regex_error under strict policy.
Exceptions
real::compat::regex_errorunder policy::strict; compiles on std under policy::fallback.

◆ std_engine()

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
const std::basic_regex< CharT, Traits > & real::compat::basic_regex< CharT, Traits >::std_engine ( ) const
inline

The std::regex for the std path, built once on demand for a real-backed pattern (a call REAL cannot honor, a traversal it does not model, a $0 format).

Thread-safe: a static mutex per instantiation serialises the build only; once published (detail::lazy_std_engine) every call reads it lock-free. Not a std::once_flag, which is not copyable, as basic_regex must be.

Returns
The wrapped std::basic_regex; compiling one on demand if this pattern is real-backed.

◆ swap()

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
void real::compat::basic_regex< CharT, Traits >::swap ( basic_regex< CharT, Traits > &  other)
inlinenoexcept

Exchanges engines, flags, policy and cached state with other.

Parameters
[in,out]otherThe regex to swap with.

◆ uses_fallback()

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
bool real::compat::basic_regex< CharT, Traits >::uses_fallback ( ) const
inlinenoexcept

True if std::regex holds this pattern, which then has no linear-time guarantee: a pattern REAL cannot serve under policy::fallback, any non-char instantiation, a default-constructed regex.

Returns
true if std::basic_regex holds it.

◆ uses_real()

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
bool real::compat::basic_regex< CharT, Traits >::uses_real ( ) const
inlinenoexcept

True if this regex is backed by the real engine (vs the std fallback).

Returns
true if REAL's linear engine holds it.

◆ uses_real_traversal()

template<typename CharT = char, typename Traits = std::regex_traits<CharT>>
bool real::compat::basic_regex< CharT, Traits >::uses_real_traversal ( ) const
inlinenoexcept

Whether replace and iteration run on REAL: real-backed, not a nullable POSIX pattern (std's leftmost-longest empty-match traversal is not modelled), and no capturing group nullable under a quantifier ((ab|)+a): REAL captures its last consuming iteration, libstdc++ and libc++ an extra empty one. Search and match keep that one capture divergence, by design (docs/COMPATIBILITY.md).

Returns
true for a real-backed pattern whose traversal real models.

The documentation for this class was generated from the following file: