The result of a match attempt: success, spans and captures. More...

#include <real.hpp>

Collaboration diagram for real::basic_match_result< SlotStorage, NameOwner >:

Public Member Functions
constexpr	basic_match_result ()=default
	Constructs an empty (non-matched) result.

constexpr	basic_match_result (std::string_view text, SlotStorage &&slots, bool matched, std::string_view pattern, std::span< const detail::named_group > names)
	Constructs a result from raw slots (used internally by the engine).

template<typename OtherOwner > requires (!std::is_same_v<OtherOwner, NameOwner>)
constexpr	basic_match_result (basic_match_result< SlotStorage, OtherOwner > other)
	Engine-internal: adopts the fields of the borrowing twin, to be detached next.

constexpr	basic_match_result (std::string_view text, std::string_view pattern, std::span< const detail::named_group > names)
	Engine-internal: an empty, unmatched result whose slot storage is built IN PLACE.

constexpr SlotStorage &	engine_slots () noexcept
	Engine-internal: the slot storage, for the engine to fill in place.

constexpr void	engine_set_matched (bool matched) noexcept
	Engine-internal: records whether the fill that just ran produced a match.

constexpr void	detach_from_regex ()
	Engine-internal: stop borrowing the regex's name tables, because it is about to die.

constexpr void	bind_context (std::string_view text, std::string_view pattern, std::span< const detail::named_group > names)
	Binds the subject, pattern and named groups once per walk, not per match.

template<bool Cascade, typename Vm >
constexpr bool	engine_refill_hot (Vm &vm, std::string_view text, std::size_t pos, detail::run_mode mode, std::size_t forbid, match_semantics sem=match_semantics::first)
	Per-match refill after bind_context — runs the VM and records only the outcome.

template<typename Vm >
constexpr void	engine_refill_span (Vm &vm, std::size_t s, std::size_t e)
	Refill from a span the engine already found in a batch, bypassing the VM entirely.

template<bool Cascade, typename Vm >
constexpr bool	engine_refill_trailing_la (Vm &vm, std::string_view text, std::size_t pos)
	Cold path for a trailing-lookaround walk.

constexpr bool	matched () const
	Returns `true` if the attempt matched.

constexpr	operator bool () const
	Returns `true` if the attempt matched (explicit bool conversion).

constexpr std::size_t	size () const
	Returns the number of groups, including group 0 (the whole match).

constexpr std::size_t	start (std::size_t group=0) const
	Start byte offset of a group.

constexpr std::size_t	end (std::size_t group=0) const
	End byte offset (exclusive) of a group.

constexpr std::string_view	operator[] (std::size_t group) const
	View of a group's matched text.

constexpr std::string_view	str (std::size_t group=0) const
	View of a group's matched text — `std::smatch`'s spelling for operator[].

constexpr std::size_t	group_index (std::string_view name) const
	Resolves a group name to its number.

constexpr std::size_t	start (std::string_view name) const
	Returns its start offset, or npos if unknown.

constexpr std::size_t	end (std::string_view name) const
	Returns its end offset, or npos if unknown.

constexpr std::string_view	operator[] (std::string_view name) const
	Returns its matched text, empty if unknown/unset.

constexpr std::span< const std::size_t >	spans () const noexcept
	The capture slots as one flat `[start0, end0, start1, end1, …]` view.

Private Attributes
std::string_view	text_
	The searched text.

SlotStorage	slots_
	Flattened capture slots.

bool	matched_ {}
	Whether a match occurred.

std::string_view	pattern_
	Pattern text (for named lookups).

std::span< const detail::named_group >	names_

NameOwner	owner_ {}

Friends
template<typename , typename >
class	basic_match_result
	The twin specialisation reads these fields to adopt them; nothing else does.

Detailed Description

template<typename SlotStorage, typename NameOwner = detail::borrowed_names>
class real::basic_match_result< SlotStorage, NameOwner >

The result of a match attempt: success, spans and captures.

Group views point into the searched text, which must outlive the result (the rvalue std::string overloads are deleted). Named lookups borrow the regex's pattern and name table; a result from a temporary regex is real::basic_regex::owning_result_type, which owns them, so names still resolve. find_iter and find_all are deleted on an rvalue regex.

Template Parameters

SlotStorage	The capture-slot container (vector- or static-backed), from the storage policy.
NameOwner	How name tables are held: borrowed from a live regex, or owned.

Constructor & Destructor Documentation

◆ basic_match_result() [1/3]

template<typename SlotStorage , typename NameOwner = detail::borrowed_names>

constexpr real::basic_match_result< SlotStorage, NameOwner >::basic_match_result	(	std::string_view	text,
		SlotStorage &&	slots,
		bool	matched,
		std::string_view	pattern,
		std::span< const detail::named_group >	names
	)

inlineconstexpr

Constructs a result from raw slots (used internally by the engine).

Parameters

[in]	text	The searched text (borrowed; must outlive the result).
[in]	slots	Flattened capture slots (byte offsets, npos for unset).
[in]	matched	Whether a match occurred.
[in]	pattern	The pattern text (for named-group resolution).
[in]	names	The regex's named-group table (borrowed).

◆ basic_match_result() [2/3]

template<typename SlotStorage , typename NameOwner = detail::borrowed_names>

template<typename OtherOwner >
requires (!std::is_same_v<OtherOwner, NameOwner>)

constexpr real::basic_match_result< SlotStorage, NameOwner >::basic_match_result ( basic_match_result< SlotStorage, OtherOwner > other )

inlineexplicitconstexpr

Engine-internal: adopts the fields of the borrowing twin, to be detached next.

Constrained to the owning specialisation, so the borrowing one every walk yields keeps its exact type. By value: the caller hands over a prvalue, and the slots move out of the parameter.

Template Parameters

OtherOwner The source's name owner, necessarily not this one's.

Parameters

[in] other The freshly run result to take over.

◆ basic_match_result() [3/3]

template<typename SlotStorage , typename NameOwner = detail::borrowed_names>

constexpr real::basic_match_result< SlotStorage, NameOwner >::basic_match_result	(	std::string_view	text,
		std::string_view	pattern,
		std::span< const detail::named_group >	names
	)

inlineconstexpr

Engine-internal: an empty, unmatched result whose slot storage is built IN PLACE.

With engine_slots and engine_set_matched, lets basic_regex::run hand the engine the final slot storage instead of moving a filled local in (a rep movs whose fixed startup dominates a groupless call). Keep run() to a single return statement: the result is NRVO-constructed in the caller's storage.

Parameters

[in]	text	The searched text (borrowed; must outlive the result).
[in]	pattern	The pattern text (for named-group resolution).
[in]	names	The regex's named-group table (borrowed).

Member Function Documentation

◆ bind_context()

template<typename SlotStorage , typename NameOwner = detail::borrowed_names>

constexpr void real::basic_match_result< SlotStorage, NameOwner >::bind_context	(	std::string_view	text,
		std::string_view	pattern,
		std::span< const detail::named_group >	names
	)

inlineconstexpr

Binds the subject, pattern and named groups once per walk, not per match.

Parameters

[in]	text	The subject the walk runs over.
[in]	pattern	The pattern text, for diagnostics and group naming.
[in]	names	The pattern's named groups.

◆ detach_from_regex()

template<typename SlotStorage , typename NameOwner = detail::borrowed_names>

constexpr void real::basic_match_result< SlotStorage, NameOwner >::detach_from_regex ( )

inlineconstexpr

Engine-internal: stop borrowing the regex's name tables, because it is about to die.

Copies the pattern and name table group_index reads into the result, which may outlive a temporary regex. The views are cleared either way, so owner_ is the source of truth and a copy deep-copies rather than inheriting views into the original. A no-op when the names are borrowed.

◆ end() [1/2]

template<typename SlotStorage , typename NameOwner = detail::borrowed_names>

constexpr std::size_t real::basic_match_result< SlotStorage, NameOwner >::end ( std::size_t group = 0 ) const

inlineconstexpr

End byte offset (exclusive) of a group.

Parameters

[in] group Group number (0 = whole match).

Returns: The offset, or real::npos if the group did not participate.

◆ end() [2/2]

template<typename SlotStorage , typename NameOwner = detail::borrowed_names>

constexpr std::size_t real::basic_match_result< SlotStorage, NameOwner >::end ( std::string_view name ) const

inlineconstexpr

Returns its end offset, or npos if unknown.

Parameters

[in] name Group name.

Returns: Its end offset, or npos if unknown.

◆ engine_refill_hot()

template<typename SlotStorage , typename NameOwner = detail::borrowed_names>

template<bool Cascade, typename Vm >

constexpr bool real::basic_match_result< SlotStorage, NameOwner >::engine_refill_hot	(	Vm &	vm,
		std::string_view	text,
		std::size_t	pos,
		detail::run_mode	mode,
		std::size_t	forbid,
		match_semantics	sem = `match_semantics::first`
	)

inlineconstexpr

Per-match refill after bind_context — runs the VM and records only the outcome.

Template Parameters

Cascade	Whether the VM may take its memchr-cascade tail.
Vm	The engine type, deduced.

Parameters

[in,out]	vm	The engine to run.
[in]	text	The subject.
[in]	pos	Byte offset to attempt at.
[in]	mode	Anchoring: full, prefix or search.
[in]	forbid	Offset at which a zero-length match is refused (the find_iter no-progress rule).
[in]	sem	Leftmost-first or leftmost-longest.

Returns: True on a match; the slots hold it.

◆ engine_refill_span()

template<typename SlotStorage , typename NameOwner = detail::borrowed_names>

template<typename Vm >

constexpr void real::basic_match_result< SlotStorage, NameOwner >::engine_refill_span	(	Vm &	vm,
		std::size_t	s,
		std::size_t	e
	)

inlineconstexpr

Refill from a span the engine already found in a batch, bypassing the VM entirely.

Template Parameters

Vm	The engine type, deduced.

Parameters

[in,out]	vm	The engine, used only to reconstruct the slot layout for this span.
[in]	s	Match start.
[in]	e	Match end.

◆ engine_refill_trailing_la()

template<typename SlotStorage , typename NameOwner = detail::borrowed_names>

template<bool Cascade, typename Vm >

constexpr bool real::basic_match_result< SlotStorage, NameOwner >::engine_refill_trailing_la	(	Vm &	vm,
		std::string_view	text,
		std::size_t	pos
	)

inlineconstexpr

Cold path for a trailing-lookaround walk.

Template Parameters

Cascade	Whether the VM may take its memchr-cascade tail.
Vm	The engine type, deduced.

Parameters

[in,out]	vm	The engine to run.
[in]	text	The subject.
[in]	pos	Byte offset to attempt at.

Returns: True on a match; the slots hold it.

◆ engine_set_matched()

template<typename SlotStorage , typename NameOwner = detail::borrowed_names>

constexpr void real::basic_match_result< SlotStorage, NameOwner >::engine_set_matched ( bool matched )

inlineconstexprnoexcept

Engine-internal: records whether the fill that just ran produced a match.

Parameters

[in] matched Whether a match occurred.

◆ engine_slots()

template<typename SlotStorage , typename NameOwner = detail::borrowed_names>

constexpr SlotStorage & real::basic_match_result< SlotStorage, NameOwner >::engine_slots ( )

inlineconstexprnoexcept

Engine-internal: the slot storage, for the engine to fill in place.

Returns: A mutable reference to the flattened capture slots.

◆ group_index()

template<typename SlotStorage , typename NameOwner = detail::borrowed_names>

constexpr std::size_t real::basic_match_result< SlotStorage, NameOwner >::group_index ( std::string_view name ) const

inlineconstexpr

Resolves a group name to its number.

Parameters

[in] name The group name.

Returns: The group number, or real::npos if unknown.

◆ matched()

template<typename SlotStorage , typename NameOwner = detail::borrowed_names>

constexpr bool real::basic_match_result< SlotStorage, NameOwner >::matched ( ) const

inlineconstexpr

Returns true if the attempt matched.

Returns: Whether the attempt matched.

◆ operator bool()

template<typename SlotStorage , typename NameOwner = detail::borrowed_names>

constexpr real::basic_match_result< SlotStorage, NameOwner >::operator bool ( ) const

inlineexplicitconstexpr

Returns true if the attempt matched (explicit bool conversion).

Returns: Whether the attempt matched.

◆ operator[]() [1/2]

template<typename SlotStorage , typename NameOwner = detail::borrowed_names>

constexpr std::string_view real::basic_match_result< SlotStorage, NameOwner >::operator[] ( std::size_t group ) const

inlineconstexpr

View of a group's matched text.

Parameters

[in] group Group number (0 = whole match).

Returns: A view into the searched text, empty if the group is unset.

◆ operator[]() [2/2]

template<typename SlotStorage , typename NameOwner = detail::borrowed_names>

constexpr std::string_view real::basic_match_result< SlotStorage, NameOwner >::operator[] ( std::string_view name ) const

inlineconstexpr

Returns its matched text, empty if unknown/unset.

Parameters

[in] name Group name.

Returns: Its matched text, empty if unknown/unset.

◆ size()

template<typename SlotStorage , typename NameOwner = detail::borrowed_names>

constexpr std::size_t real::basic_match_result< SlotStorage, NameOwner >::size ( ) const

inlineconstexpr

Returns the number of groups, including group 0 (the whole match).

Returns: The group count.

◆ spans()

template<typename SlotStorage , typename NameOwner = detail::borrowed_names>

constexpr std::span< const std::size_t > real::basic_match_result< SlotStorage, NameOwner >::spans ( ) const

inlineconstexprnoexcept

The capture slots as one flat [start0, end0, start1, end1, …] view.

For copying every group in one pass, pairwise (spans[2g], spans[2g+1]); the C ABI's spans buffer has this layout. Only meaningful on a matched result: an unmatched one carries whatever the last fill left. For a single group prefer start / end.

Returns: A view of 2 * size() slot values; empty when there are no slots.

◆ start() [1/2]

template<typename SlotStorage , typename NameOwner = detail::borrowed_names>

constexpr std::size_t real::basic_match_result< SlotStorage, NameOwner >::start ( std::size_t group = 0 ) const

inlineconstexpr

Start byte offset of a group.

Parameters

[in] group Group number (0 = whole match).

Returns: The offset, or real::npos if the group did not participate.

◆ start() [2/2]

template<typename SlotStorage , typename NameOwner = detail::borrowed_names>

constexpr std::size_t real::basic_match_result< SlotStorage, NameOwner >::start ( std::string_view name ) const

inlineconstexpr

Returns its start offset, or npos if unknown.

Parameters

[in] name Group name.

Returns: Its start offset, or npos if unknown.

◆ str()

template<typename SlotStorage , typename NameOwner = detail::borrowed_names>

constexpr std::string_view real::basic_match_result< SlotStorage, NameOwner >::str ( std::size_t group = 0 ) const

inlineconstexpr

View of a group's matched text — std::smatch's spelling for operator[].

Unlike std::smatch::str it returns a view: it never copies, and the subject must outlive the result. std::string s = m.str(1); does not compile (the conversion is explicit); write std::string s {m.str(1)}; for an owned copy.

Parameters

[in] group Group number (0 = whole match).

Returns: A view into the searched text, empty if the group is unset.

Member Data Documentation

◆ names_

template<typename SlotStorage , typename NameOwner = detail::borrowed_names>

std::span<const detail::named_group> real::basic_match_result< SlotStorage, NameOwner >::names_

private

Named-group table: borrowed, or owned via owner_.

◆ owner_

template<typename SlotStorage , typename NameOwner = detail::borrowed_names>

NameOwner real::basic_match_result< SlotStorage, NameOwner >::owner_ {}

private

Owns what pattern_ and names_ point at, once detach_from_regex has run; empty (and zero-sized) on the compile-time policy, null on every result that borrows.

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

include/real/real.hpp

Public Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ basic_match_result() [1/3]

◆ basic_match_result() [2/3]

◆ basic_match_result() [3/3]

Member Function Documentation

◆ bind_context()

◆ detach_from_regex()

◆ end() [1/2]

◆ end() [2/2]

◆ engine_refill_hot()

◆ engine_refill_span()

◆ engine_refill_trailing_la()

◆ engine_set_matched()

◆ engine_slots()

◆ group_index()

◆ matched()

◆ operator bool()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ size()

◆ spans()

◆ start() [1/2]

◆ start() [2/2]

◆ str()

Member Data Documentation

◆ names_

◆ owner_