---
slug: ./Regex
title: "ClikaRT::regex::Regex"
sidebar_label: "Regex"
description: "A compiled regular expression. Copyable is NOT provided (a compiled program is heavy); move it. Build one with Regex::compile. Matching methods interpret both the pattern and the subject as bytes."
---

<!-- Generated by tools/doxygen2mdx from Doxygen XML. Do not edit. -->

<span class="api-kind api-kind--class">class</span>

**Header:** `ClikaRT/regex/regex.h`

A compiled regular expression. Copyable is NOT provided (a compiled program is heavy); move it. Build one with [`Regex::compile`](./Regex.md#compile).

Matching methods interpret both the pattern and the subject as bytes. Feed UTF-8 text (the default encoding); a byte-oriented match over UTF-8 is the common case. [`full_match`](./Regex.md#full_match-2) requires the WHOLE subject to match; [`partial_match`](./Regex.md#partial_match-2) / `search` / [`find`](./Regex.md#find) look for a match anywhere within it.

## Nested types

| Name | Description |
| --- | --- |
| [`Options`](./Regex.Options.md) | Compile-time options (a subset of the engine's). |

## Types

### enum Encoding {#Encoding}

<div class="api-signature">

`enum class` **`Encoding`** `:` `std::uint8_t`

</div>

How the pattern and subject bytes are interpreted. The engine is byte-oriented; there is no wide/UTF-16 mode, and this only chooses how it reads 8-bit input.

| Enumerator | Description |
| --- | --- |
| `Utf8` | UTF-8 (the default). |
| `Latin1` | raw Latin-1 bytes |

<div class="api-declared">

Declared in `ClikaRT/regex/regex.h`, line 47

</div>

## Static member functions

### compile(string\_view, Options) {#compile}

<div class="api-signature">

`static` [`Regex`](./Regex.md) **`compile`**(`std::string_view` `pattern`, `const` [`Options`](./Regex.Options.md)`&` `options`)

</div>

Compile [`pattern`](./Regex.md#pattern) with the given options. A malformed pattern raises [`ClikaRT::Error`](../Error.md) (InvalidArgument) carrying the engine's diagnostic. [`pattern`](./Regex.md#pattern) is read during the call, not retained.

<div class="api-declared">

Declared in `ClikaRT/regex/regex.h`, line 66

</div>

### compile(string\_view) {#compile-2}

<div class="api-signature">

`static` [`Regex`](./Regex.md) **`compile`**(`std::string_view` `pattern`)

</div>

Compile [`pattern`](./Regex.md#pattern) with default options. (An overload rather than a defaulted [`Options`](./Regex.Options.md)`{}` argument: a nested aggregate's default-member initializers aren't complete in a same-class default-argument context.)

<div class="api-declared">

Declared in `ClikaRT/regex/regex.h`, line 72

</div>

### full\_match(string\_view, string\_view) {#full_match}

<div class="api-signature">

`static` `bool` **`full_match`**(`std::string_view` `text`, `std::string_view` `pattern`)

</div>

Compile [`pattern`](./Regex.md#pattern) and test it against `text` in one call. A malformed pattern raises [`ClikaRT::Error`](../Error.md). Prefer [`compile`](./Regex.md#compile) + a member matcher when matching the same pattern repeatedly.

<div class="api-declared">

Declared in `ClikaRT/regex/regex.h`, line 135

</div>

### partial\_match(string\_view, string\_view) {#partial_match}

<div class="api-signature">

`static` `bool` **`partial_match`**(`std::string_view` `text`, `std::string_view` `pattern`)

</div>

One-shot substring match of [`pattern`](./Regex.md#pattern) in `text`; compiles per call, and hoist a [`Regex`](./Regex.md) for a hot path.

<div class="api-declared">

Declared in `ClikaRT/regex/regex.h`, line 141

</div>

### quote\_meta() {#quote_meta}

<div class="api-signature">

`static` `std::string` **`quote_meta`**(`std::string_view` `literal`)

</div>

Escape the regex metacharacters in `literal` so the result matches `literal` verbatim.

<div class="api-declared">

Declared in `ClikaRT/regex/regex.h`, line 147

</div>

## Member functions

### Regex(Regex) {#Regex}

<div class="api-signature">

**`Regex`**(`Regex&&` `other`) `noexcept`

</div>

Move: transfers the compiled pattern.

<div class="api-declared">

Declared in `ClikaRT/regex/regex.h`, line 77

</div>

### operator=(Regex) {#operator-assign}

<div class="api-signature">

[`Regex`](./Regex.md)`&` **`operator=`**([`Regex`](./Regex.md)`&&` `other`) `noexcept`

</div>

Move-assign: transfers the compiled pattern.

<div class="api-declared">

Declared in `ClikaRT/regex/regex.h`, line 79

</div>

### Regex(Regex) {#Regex-2}

<div class="api-signature">

**`Regex`**(`const Regex&`) `=delete`

</div>

<div class="api-declared">

Declared in `ClikaRT/regex/regex.h`, line 80

</div>

### operator=(Regex) {#operator-assign-2}

<div class="api-signature">

[`Regex`](./Regex.md)`&` **`operator=`**(`const` [`Regex`](./Regex.md)`&`) `=delete`

</div>

<div class="api-declared">

Declared in `ClikaRT/regex/regex.h`, line 81

</div>

### \~Regex() {#Regex-3}

<div class="api-signature">

**`~Regex`**()

</div>

Releases the compiled pattern.

<div class="api-declared">

Declared in `ClikaRT/regex/regex.h`, line 83

</div>

### pattern() {#pattern}

<div class="api-signature">

`std::string` **`pattern`**() `const`

</div>

The source pattern this was compiled from.

<div class="api-declared">

Declared in `ClikaRT/regex/regex.h`, line 86

</div>

### num\_capturing\_groups() {#num_capturing_groups}

<div class="api-signature">

`int` **`num_capturing_groups`**() `const`

</div>

Number of capturing groups in the pattern (group 0, the whole match, is not counted).

<div class="api-declared">

Declared in `ClikaRT/regex/regex.h`, line 89

</div>

### named\_groups() {#named_groups}

<div class="api-signature">

`std::map<std::string, int>` **`named_groups`**() `const`

</div>

Named capture groups → their 1-based group index, for a pattern using `(?P<name>...)`. Empty when the pattern declares none. Read the capture at `groups[index - 1]` from a `*_groups` match.

<div class="api-declared">

Declared in `ClikaRT/regex/regex.h`, line 93

</div>

### full\_match(string\_view) {#full_match-2}

<div class="api-signature">

`bool` **`full_match`**(`std::string_view` `text`) `const`

</div>

True if the pattern matches the WHOLE `text`.

<div class="api-declared">

Declared in `ClikaRT/regex/regex.h`, line 99

</div>

### partial\_match(string\_view) {#partial_match-2}

<div class="api-signature">

`bool` **`partial_match`**(`std::string_view` `text`) `const`

</div>

True if the pattern matches ANY substring of `text`.

<div class="api-declared">

Declared in `ClikaRT/regex/regex.h`, line 101

</div>

### full\_match\_groups() {#full_match_groups}

<div class="api-signature">

`std::optional<std::vector<std::string>>` **`full_match_groups`**(`std::string_view` `text`) `const`

</div>

As [`full_match`](./Regex.md#full_match-2) / [`partial_match`](./Regex.md#partial_match-2), but on a match return capture groups 1..N (group 0, the whole match, is not included; an unmatched optional group yields ""). `std::nullopt` when there is no match.

<div class="api-declared">

Declared in `ClikaRT/regex/regex.h`, line 106

</div>

### partial\_match\_groups() {#partial_match_groups}

<div class="api-signature">

`std::optional<std::vector<std::string>>` **`partial_match_groups`**(`std::string_view` `text`) `const`

</div>

Substring twin of [`full_match_groups`](./Regex.md#full_match_groups); the pattern may match anywhere in `text`.

<div class="api-declared">

Declared in `ClikaRT/regex/regex.h`, line 109

</div>

### find() {#find}

<div class="api-signature">

`std::optional<std::pair<std::size_t, std::size_t>>` **`find`**(<br />
&nbsp;&nbsp;&nbsp;&nbsp;`std::string_view` `text`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;`std::size_t` `start` `=` `0`<br />
) `const`

</div>

Find the leftmost match at or after byte offset `start` (an unanchored search). Returns the match's `[begin, end)` byte offsets within `text`, or `std::nullopt` if there is none. Iterate by passing a previous match's `end` as the next `start`, the find-all form a tokenizer split needs.

<div class="api-declared">

Declared in `ClikaRT/regex/regex.h`, line 117

</div>

### replace() {#replace}

<div class="api-signature">

`std::string` **`replace`**(`std::string_view` `text`, `std::string_view` `rewrite`) `const`

</div>

Rewrite the FIRST match in `text` and return the result. If nothing matches, returns `text` unchanged.

<div class="api-declared">

Declared in `ClikaRT/regex/regex.h`, line 125

</div>

### replace\_all() {#replace_all}

<div class="api-signature">

`std::string` **`replace_all`**(`std::string_view` `text`, `std::string_view` `rewrite`) `const`

</div>

Rewrite EVERY match in `text` and return the result.

<div class="api-declared">

Declared in `ClikaRT/regex/regex.h`, line 127

</div>