basic_match_result#

Synopsis#

What every match / fullmatch / search call returns: a testable result carrying the spans and texts of the whole match and its capture groups, addressable by index or by group name. real::match_result is the usual alias. A non-match is simply falsy – test the result, then read it. m.str(1) is accepted as a synonym of m[1], for callers whose fingers come from std::smatch. Both return a view, not an owned string, so an owned copy is std::string s {m.str(1)}; — with braces, since std::string_view converts to std::string explicitly.

Interface#

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

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 on the regex are deleted so the common dangling mistake is a compile error.

Named-group lookups need the regex’s pattern text and name table. A result from a live regex borrows both. A result from a temporary regex is real::basic_regex::owning_result_type — the same class, owning those tables — so names still resolve after the regex dies. find_iter and find_all have no such twin: they are deleted on an rvalue regex.

Template Parameters:

  • SlotStorage – The capture-slot container (vector- or static-backed), supplied by the storage policy.

  • NameOwner – How name tables are held: borrowed from a live regex, or owned after a temporary regex dies.

Public Functions

constexpr basic_match_result() = default#

Constructs an empty (non-matched) result.

inline constexpr bool matched() const#

Returns true if the attempt matched.

Returns:

Whether the attempt matched.

inline explicit constexpr operator bool() const#

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

Returns:

Whether the attempt matched.

inline constexpr std::size_t size() const#

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

Returns:

The group count.

inline constexpr std::size_t start(std::size_t group = 0) const#

Start byte offset of a group.

Parameters:

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

Returns:

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

inline constexpr std::size_t end(std::size_t group = 0) const#

End byte offset (exclusive) of a group.

Parameters:

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

Returns:

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

inline constexpr std::string_view operator[](std::size_t group) const#

View of a group’s matched text.

Parameters:

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

Returns:

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

inline constexpr std::string_view str(std::size_t group = 0) const#

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

Exactly operator[], under the name a caller arriving from std::regex writes first. Without it m.str(1) is a compile error that names an internal storage type and suggests nothing. Unlike std::smatch::str it returns a view rather than an owned string, so it never copies and the subject must outlive the result.

That difference bites on the NEXT line the same caller writes: std::string s = m.str(1); does not compile, because std::string_view converts to std::string explicitly. Spell it std::string s {m.str(1)}; when an owned copy is what you want.

Parameters:

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

Returns:

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

inline constexpr std::size_t group_index(std::string_view name) const#

Resolves a group name to its number.

Parameters:

name – [in] The group name.

Returns:

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

inline constexpr std::size_t start(std::string_view name) const#

Returns its start offset, or npos if unknown.

Parameters:

name – [in] Group name.

Returns:

Its start offset, or npos if unknown.

inline constexpr std::size_t end(std::string_view name) const#

Returns its end offset, or npos if unknown.

Parameters:

name – [in] Group name.

Returns:

Its end offset, or npos if unknown.

inline constexpr std::string_view operator[](std::string_view name) const#

Returns its matched text, empty if unknown/unset.

Parameters:

name – [in] Group name.

Returns:

Its matched text, empty if unknown/unset.

inline constexpr std::span<const std::size_t> spans() const noexcept#

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

For a caller that copies every group in one pass (the C ABI’s spans buffer is this layout). Only meaningful on a matched result — an unmatched one carries whatever the last fill left. Prefer start / end when reading a single group; those return real::npos if it did not participate. Copy pairwise (spans[2g], spans[2g+1]).

Returns:

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

Friends

friend class basic_match_result

Complexity#

Every accessor is O(1) – the spans are computed by the match itself, the result only reads them. group_index resolves a name against the pattern’s named-group table. Group views (m[0], m["year"]) borrow the subject, which must outlive the result.

Example#

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

  // A match result is testable, sized, and addressable by index or by group name.
  const real::regex date {R"((?P<year>\d{4})-(?P<month>\d{2}))"};
  const auto m = date.search("released 2026-07-20");
  if (m) {
    std::cout << m.size() << "\n";          // 3 -- group 0 plus the two named groups
    std::cout << m[0] << "\n";              // 2026-07 -- the whole match
    std::cout << m["year"] << "\n";         // 2026 -- by name...
    std::cout << m[2] << "\n";              // 07   -- ...or by index
    std::cout << m.str(2) << "\n";          // 07   -- std::smatch's spelling of the same thing
    std::cout << m.start("month") << "\n";  // 14   -- byte offsets, by name too
  }

See also#