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

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[].

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:

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

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#