.. index::
    single: MatchBase
    single: Match
    single: MatchView
    single: CaptureRange
    single: CaptureGroup

*******************
The Match Interface
*******************

A successful regular expression match is represented by a *match object*.

To make match handling explicit and safe, the library intentionally splits match
results into two dedicated interfaces:

*   :cpp:class:`Match <erbsland::re::Match>`
    An **owning** match. All captured text is owned by the match object and
    remains valid for its entire lifetime.

*   :cpp:class:`MatchView <erbsland::re::MatchView>`
    A **view-based** match. All captured text is only *referenced* and depends on
    the lifetime of the original input string.

Both interfaces share the same positional and group-based API via the common base
interface :cpp:class:`MatchBase <erbsland::re::MatchBase>`, but they differ
intentionally in how match content can be accessed.

*   :cpp:class:`Match <erbsland::re::Match>` provides
    :cpp:any:`content <erbsland::re::Match::content>` methods.
*   :cpp:class:`MatchView <erbsland::re::MatchView>` provides
    :cpp:any:`contentView <erbsland::re::MatchView::contentView>` methods.

This design prevents a common and subtle pitfall: switching matching code from
an owning API to a view-based API without noticing the lifetime implications.

For example, if code is changed from
:cpp:any:`match <erbsland::re::RegEx::match>` to
:cpp:any:`matchView <erbsland::re::RegEx::matchView>` and both returned the same
interface, the code would still compile — but might suddenly introduce undefined
behavior if the input string does not outlive the match result.

By requiring two distinct interfaces, switching between owning and view-based
matches becomes a conscious and visible decision.

Obtaining a Match
=================

You typically obtain match objects from :cpp:class:`RegEx <erbsland::re::RegEx>`:

*   :cpp:any:`match <erbsland::re::RegEx::match>`,
    :cpp:any:`fullMatch <erbsland::re::RegEx::fullMatch>`,
    :cpp:any:`findFirst <erbsland::re::RegEx::findFirst>`,
    :cpp:any:`findAll <erbsland::re::RegEx::findAll>`,
    :cpp:any:`collectAll <erbsland::re::RegEx::collectAll>`
    return :cpp:class:`Match <erbsland::re::Match>`.

*   :cpp:any:`matchView <erbsland::re::RegEx::matchView>`,
    :cpp:any:`fullMatchView <erbsland::re::RegEx::fullMatchView>`,
    :cpp:any:`findFirstView <erbsland::re::RegEx::findFirstView>`,
    :cpp:any:`findAllView <erbsland::re::RegEx::findAllView>`,
    :cpp:any:`collectAllView <erbsland::re::RegEx::collectAllView>`
    return :cpp:class:`MatchView <erbsland::re::MatchView>`.

*   :cpp:any:`replaceAll <erbsland::re::RegEx::replaceAll>` uses
    :cpp:class:`MatchView <erbsland::re::MatchView>` when invoking the replacement
    callback.

Match Lifetime and Ownership
============================

All matching functions return shared pointers to match objects. This allows match
results to be copied and passed around cheaply while clearly expressing shared
ownership.

The lifetime rules depend on how the match was created:

*   :cpp:class:`Match <erbsland::re::Match>` objects own their matched text
    internally. They are fully self-contained and safe to use independently.

*   :cpp:class:`MatchView <erbsland::re::MatchView>` objects only reference the
    original input text. You must ensure that this text remains alive for as long
    as the match object is used.

Violating these lifetime rules results in undefined behavior. If you are unsure
which variant to use, prefer the owning APIs.

Accessing the Match Data
========================

The shared base interface :cpp:class:`MatchBase <erbsland::re::MatchBase>`
provides access to positional and structural information:

*   :cpp:any:`begin <erbsland::re::MatchBase::begin>`,
    :cpp:any:`end <erbsland::re::MatchBase::end>`,
    :cpp:any:`range <erbsland::re::MatchBase::range>`

*   :cpp:any:`group <erbsland::re::MatchBase::group>`,
    :cpp:any:`groupCount <erbsland::re::MatchBase::groupCount>`,
    :cpp:any:`hasGroupIndex <erbsland::re::MatchBase::hasGroupIndex>`,
    :cpp:any:`hasGroupName <erbsland::re::MatchBase::hasGroupName>`

Access to the matched *content* depends on the concrete type:

*   :cpp:class:`Match <erbsland::re::Match>` provides
    :cpp:any:`content <erbsland::re::Match::content>`.

*   :cpp:class:`MatchView <erbsland::re::MatchView>` provides
    :cpp:any:`contentView <erbsland::re::MatchView::contentView>`.

Parameters
----------

Most access methods are available in three variants:

*   **No parameter**
    Addresses the *entire* match. This is equivalent to accessing capture group
    zero.

*   **Group Index**
    Accesses a capture group by its numeric index. Group zero refers to the whole
    match; group indices starting from one refer to individual capture groups.

*   **Group Name**
    If the pattern defines named capture groups, they can be accessed using
    their names.

Begin, End and Range
--------------------

The :cpp:any:`begin <erbsland::re::MatchBase::begin>`,
:cpp:any:`end <erbsland::re::MatchBase::end>` and
:cpp:any:`range <erbsland::re::MatchBase::range>` methods return positions into
the input text.

The unit used for these positions depends on the type of the matched string.
For UTF-8 encoded strings, positions are expressed in **bytes**. This allows
you to use them directly with standard library facilities such as ``substr`` or
file ``seek`` operations.

The :cpp:any:`end <erbsland::re::MatchBase::end>` position always points to the
first byte *after* the captured range.

If a capture group did not participate in the match,
:cpp:any:`begin <erbsland::re::MatchBase::begin>` and
:cpp:any:`end <erbsland::re::MatchBase::end>` return zero.

For UTF-16 and UTF-32 strings, see the section at the end of this page.

Accessing the Content
---------------------

Use :cpp:any:`content <erbsland::re::Match::content>` (owning) or
:cpp:any:`contentView <erbsland::re::MatchView::contentView>` (view-based) to
access the captured text.

If a capture group was not matched, an empty string or empty view is returned.

Thread Safety
=============

Match objects are immutable after creation. As a result, it is safe to read from
a match concurrently from multiple threads, provided the documented lifetime
rules are respected.

UTF-16 and UTF-32 Strings
=========================

When matching UTF-16 or UTF-32 strings, the corresponding overloads in
:cpp:class:`RegEx <erbsland::re::RegEx>` return
:cpp:class:`Match16 <erbsland::re::Match16>`,
:cpp:class:`Match16View <erbsland::re::Match16View>`,
:cpp:class:`Match32 <erbsland::re::Match32>` and
:cpp:class:`Match32View <erbsland::re::Match32View>` objects.

These types behave exactly like their UTF-8 counterparts, with the key
difference that all returned positions are expressed as indices into
``char16_t`` or ``char32_t`` sequences.

For UTF-16 strings containing surrogate pairs, the index refers to the first
``char16_t`` code unit of the character. This mirrors the behaviour of the
UTF-8 variants, where positions always point to the first byte of a
multi-byte character.


.. button-ref:: settings
    :ref-type: doc
    :color: success
    :align: center
    :expand:
    :class: sd-fs-5 sd-font-weight-bold sd-p-2 sd-my-4

    Settings →

Interfaces and Types
====================

.. doxygenclass:: erbsland::re::MatchBase
    :members:

.. doxygenclass:: erbsland::re::Match
    :members:

.. doxygenclass:: erbsland::re::MatchView
    :members:

.. doxygenclass:: erbsland::re::Match16
    :members:

.. doxygenclass:: erbsland::re::Match16View
    :members:

.. doxygenclass:: erbsland::re::Match32
    :members:

.. doxygenclass:: erbsland::re::Match32View
    :members:

.. doxygenclass:: erbsland::re::CaptureRange
    :members:

.. doxygenclass:: erbsland::re::CaptureGroup
    :members:

.. doxygentypedef:: erbsland::re::MatchPtr

.. doxygentypedef:: erbsland::re::MatchViewPtr

.. doxygentypedef:: erbsland::re::Match16Ptr

.. doxygentypedef:: erbsland::re::Match16ViewPtr

.. doxygentypedef:: erbsland::re::Match32Ptr

.. doxygentypedef:: erbsland::re::Match32ViewPtr