> ## Documentation Index
> Fetch the complete documentation index at: https://cs-lua.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# regex

> Настоящие регулярные выражения: match, find, replace

# regex

Настоящие регулярные выражения: match, find, replace.

Lua-паттерны (`string.find`, `string.match`, `string.gsub`) годятся для
простых случаев, но не умеют альтернативу (`a|b`), нежадные квантификаторы
или группы с квантификатором. `regex` — обычные регулярки поверх
стандартной библиотеки C++ (`std::regex`, синтаксис ECMAScript — тот же,
что в JavaScript/PCRE): без нового вендоренного движка, без 32-битной
сборки под него.

```lua theme={null}
regex.match("2026-08-19", "(\\d+)-(\\d+)-(\\d+)")
-- "2026", "08", "19"
```

Скомпилированный паттерн кешируется по тексту (первый вызов с новым
паттерном платит за компиляцию, повторные — нет). Плохой паттерн — ошибка
Lua при первом использовании, а не тихий `nil`.

<h2 id="match">
  regex.match
</h2>

Ищет совпадение и возвращает захваченные группы (или само совпадение, если групп нет).

```lua theme={null}
regex.match(str, pattern[, init])
```

### Аргументы

| # | имя       | тип           |                                         |
| - | --------- | ------------- | --------------------------------------- |
| 1 | `str`     | string        | строка для поиска                       |
| 2 | `pattern` | string        | паттерн, синтаксис ECMAScript           |
| 3 | `init`    | number \| nil | с какого символа искать, 1 по умолчанию |

### Возвращает

| тип           |                                                                              |
| ------------- | ---------------------------------------------------------------------------- |
| `string, ...` | по одному значению на группу; `nil` для не сработавшей необязательной группы |
| `string`      | всё совпадение, если групп в паттерне нет                                    |
| `nil`         | совпадений не найдено                                                        |

### Пример

```lua theme={null}
local year, month, day = regex.match("2026-08-19", "(\\d+)-(\\d+)-(\\d+)")

if regex.match(name, "^[A-Za-z0-9_]+$") then
  -- имя годится: только буквы, цифры, подчёркивание
end
```

Та же форма, что у `string.match`: с группами — значения групп, без групп —
всё совпадение целиком.

<Warning>
  Синтаксис ECMAScript, не Lua-паттерны: `\d` вместо `%d`, `\w` вместо `%w` и
  т.д. В Lua-строке экранируй бэкслеш: `"\\d+"`, а не `"\d+"` — иначе
  получится управляющая последовательность строки, а не буквальный
  бэкслеш+d.
</Warning>

<h2 id="find">
  regex.find
</h2>

Ищет совпадение и возвращает его границы.

```lua theme={null}
regex.find(str, pattern[, init])
```

### Аргументы

| # | имя       | тип           |                                         |
| - | --------- | ------------- | --------------------------------------- |
| 1 | `str`     | string        | строка для поиска                       |
| 2 | `pattern` | string        | паттерн, синтаксис ECMAScript           |
| 3 | `init`    | number \| nil | с какого символа искать, 1 по умолчанию |

### Возвращает

| тип              |                                                                 |
| ---------------- | --------------------------------------------------------------- |
| `number, number` | начало и конец совпадения, 1-based, включительно                |
| `string, ...`    | дальше — по одному значению на группу, если они есть в паттерне |
| `nil`            | совпадений не найдено                                           |

### Пример

```lua theme={null}
local s, f = regex.find("hello123world", "\\d+")
-- s == 6, f == 8, str:sub(s, f) == "123"
```

Та же форма, что у `string.find` — `str:sub(start, finish)` всегда
восстанавливает совпадение.

<h2 id="replace">
  regex.replace
</h2>

Заменяет совпадения.

```lua theme={null}
regex.replace(str, pattern, repl[, limit])
```

### Аргументы

| # | имя       | тип           |                                                                 |
| - | --------- | ------------- | --------------------------------------------------------------- |
| 1 | `str`     | string        | исходная строка                                                 |
| 2 | `pattern` | string        | паттерн, синтаксис ECMAScript                                   |
| 3 | `repl`    | string        | замена; `$1`, `$2`, … — ссылки на группы, `$&` — всё совпадение |
| 4 | `limit`   | number \| nil | не больше стольких замен; без него — все                        |

### Возвращает

| тип      |                      |
| -------- | -------------------- |
| `string` | результат            |
| `number` | сколько раз заменили |

### Пример

```lua theme={null}
local out, n = regex.replace("2026-08-19", "-", "/")
-- out == "2026/08/19", n == 2

local swapped = regex.replace("John Smith", "(\\w+) (\\w+)", "$2 $1")
-- "Smith John"
```

Названо `replace`, не `gsub` — это не Lua-паттерн, и «gsub» уже значит
что-то конкретное для тех, кто знает Lua.