zoptia0regex

https://github.com/zoptia/zoptia0regex
Admin
zoptia0regex is a regular-expression library for Zig, a faithful port of Go's regexp (RE2) engine...
Tokens:34,511
Snippets:192
Trust Score:3.5
License:Apache-2.0
Update:2 days ago
Show doc for...
Tokens:
Raw
### Scratch usage example

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Allocates a reusable Scratch for allocation-free matching in a hot loop; the scratch must not be shared across concurrent matches.

```zig
var scratch = regex.Scratch.init(gpa);
defer scratch.deinit();

for (lines) |line| {
    if (try re.matchScratch(&scratch, line)) hits += 1;
}
```

--------------------------------

### Import regex module

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Import the 'regex' module in your Zig source to use the package.

```zig
const regex = @import("regex");
```

--------------------------------

### matchScratch

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Performs a match reusing a caller-owned Scratch, avoiding heap allocation after warm-up.

```APIDOC
## matchScratch

### Description
`match` reusing a caller-owned `Scratch`. After warm-up each call does zero heap allocation.

### Function Signature
```zig
pub fn matchScratch(re: *const Regexp, scratch: *Scratch, s: []const u8) ExecError!bool
```

### Parameters
- `re` (*const Regexp) - Required - The compiled regexp.
- `scratch` (*Scratch) - Required - A reusable scratch buffer.
- `s` ([]const u8) - Required - The input string to match.

### Returns
- `ExecError!bool` - `true` if a match is found, `false` otherwise.
```

--------------------------------

### Install with zig fetch

Source: https://github.com/zoptia/zoptia0regex/blob/main/README.md

Adds the zoptia0regex dependency to your Zig project using the git URL. Requires Zig 0.16 or 0.17.0-dev nightlies.

```sh
zig fetch --save git+https://github.com/zoptia/zoptia0regex
```

--------------------------------

### Use replaceAllStringFunc with context struct

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Example of `replaceAllStringFunc` with a context struct passed through to the callback. `func` receives the matched text and returns a slice valid only for the duration of the call; `ctx` carries state. The returned slice must outlive only the call.

```zig
const Up = struct {
    fn f(_: @This(), s: []const u8) []const u8 {
        _ = s;
        return "X"; // returned slice must outlive only the call
    }
};
const out = try re.replaceAllStringFunc(gpa, src, Up{}, Up.f);
defer gpa.free(out);
```

--------------------------------

### Regexp.literalPrefix

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Returns a literal string that must begin any match, and whether it is the whole regexp.

```APIDOC
## Regexp.literalPrefix

### Description
Returns a literal string that must begin any match, and whether it is the whole regexp.

### Function Signature
```zig
pub fn Regexp.literalPrefix(re: *const Regexp) struct { prefix: []const u8, complete: bool }
```

### Parameters
- `re` (*const Regexp) - Required - The compiled regexp.

### Returns
- `struct { prefix: []const u8, complete: bool }` - The literal prefix and a flag indicating if it is the whole regexp.
```

--------------------------------

### findAllIndex

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Finds all matches and returns owned slices of offsets. Free with allocator.free.

```APIDOC
## findAllIndex

### Description
Finds all matches and returns owned slices of offsets. Free with allocator.free.

### Method
findAllIndex

### Parameters
- `allocator` (allocator) - Required - Allocator used for internal scratch and result.
- `input` (string) - Required - The input string to search.

### Returns
- `[][]usize` - Owned slice of offset pairs; free with allocator.free.
```

--------------------------------

### findIndexScratch

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Finds the index of the first match reusing a caller-owned Scratch.

```APIDOC
## findIndexScratch

### Description
`findIndex` reusing a caller-owned `Scratch`. After warm-up each call does zero heap allocation.

### Function Signature
```zig
pub fn findIndexScratch(re: *const Regexp, scratch: *Scratch, s: []const u8) ExecError!?struct { start: usize, end: usize }
```

### Parameters
- `re` (*const Regexp) - Required - The compiled regexp.
- `scratch` (*Scratch) - Required - A reusable scratch buffer.
- `s` ([]const u8) - Required - The input string to search.

### Returns
- `ExecError!?struct { start: usize, end: usize }` - The start and end indices of the first match, or `null` if no match.
```

--------------------------------

### matchesScratch

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Returns an iterator that reuses engine buffers and yields offsets from the Scratch, allocating nothing once warm.

```APIDOC
## matchesScratch

### Description
`matches` iterator borrowing engine buffers *and* the yielded offsets from the `Scratch`: repeated scans allocate nothing once warm. Valid until the next call that reuses the scratch; `deinit` frees nothing.

### Function Signature
```zig
pub fn matchesScratch(re: *const Regexp, scratch: *Scratch, s: []const u8) ExecError!MatchesIterator
```

### Parameters
- `re` (*const Regexp) - Required - The compiled regexp.
- `scratch` (*Scratch) - Required - A reusable scratch buffer.
- `s` ([]const u8) - Required - The input string to iterate over.

### Returns
- `ExecError!MatchesIterator` - An iterator over matches; `next()` returns `null` when no more matches.
```

--------------------------------

### expand

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Appends template to buf, expanding $name / ${name} / $1 references using m (submatch offsets into src).

```APIDOC
## expand

### Description
Appends template to buf, expanding $name / ${name} / $1 references using m (submatch offsets into src).

### Method
Function

### Signature
```zig
pub fn Regexp.expand(
    re: *const Regexp,
    allocator: std.mem.Allocator,
    buf: *std.ArrayList(u8),
    template: []const u8,
    src: []const u8,
    m: []i64,
) ExecError!void
```

### Parameters
- `re` (*const Regexp) - Required - The compiled regular expression.
- `allocator` (std.mem.Allocator) - Required - Memory allocator for any temporary allocations.
- `buf` (*std.ArrayList(u8)) - Required - The buffer to append the expanded text to; caller owns it.
- `template` ([]const u8) - Required - The template with $ references.
- `src` ([]const u8) - Required - The source text that the submatch offsets refer to.
- `m` ([]i64) - Required - Submatch offsets as returned by `findSubmatchIndex`.

### Response
Returns `ExecError!void`. The expanded text is appended to `buf`. `$$` emits a literal `$`; a malformed reference emits a literal `$`.
```

--------------------------------

### Matches.deinit

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Frees the iterator and its associated resources.

```APIDOC
## Matches.deinit

### Description
Frees the iterator and its associated resources.

### Method
Function

### Signature
```zig
pub fn Regexp.Matches.deinit(it: *Matches) void
```

### Parameters
- `it` (*Matches) - Required - The iterator to deinitialize.
```

--------------------------------

### findAllSubmatchIndex

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Finds all matches and submatches, returning a slice-of-slices where both levels are owned. Free with freeAllSubmatchIndex.

```APIDOC
## findAllSubmatchIndex

### Description
Finds all matches and submatches, returning a slice-of-slices where both levels are owned. Free with freeAllSubmatchIndex.

### Method
findAllSubmatchIndex

### Parameters
- `allocator` (allocator) - Required - Allocator used for internal scratch and result.
- `input` (string) - Required - The input string to search.

### Returns
- `[][][]usize` - Owned slice-of-slices of offsets; free with freeAllSubmatchIndex.
```

--------------------------------

### findAllIndex

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Returns the Match locations of all successive matches. Returns null when there are no matches.

```APIDOC
## findAllIndex

### Description
Returns the Match locations of all successive matches. Returns null when there are no matches.

### Method
Function

### Signature
```zig
pub fn Regexp.findAllIndex(re: *const Regexp, allocator, input: []const u8, n: i64) ExecError!?[]Match
```

### Parameters
- `re` (*const Regexp) - Required - The compiled regular expression.
- `allocator` - Required - Memory allocator for the returned slice.
- `input` ([]const u8) - Required - The input text to search.
- `n` (i64) - Required - Maximum number of matches; negative means all, zero yields none, positive caps the count.

### Response
Returns `?[]Match` - null if no matches, otherwise an array of Match locations. The caller owns the returned slice and must free it with `allocator.free`.
```

--------------------------------

### find

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Finds the first match of the pattern in the input. Returns a borrowed sub-slice of the input; do not free it.

```APIDOC
## find

### Description
Finds the first match of the pattern in the input. Returns a borrowed sub-slice of the input; do not free it.

### Method
find

### Parameters
- `allocator` (allocator) - Required - Allocator used for internal scratch.
- `input` (string) - Required - The input string to search.

### Returns
- `?[]const u8` - The matched sub-slice, or null if no match.
```

--------------------------------

### findAll

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Returns the texts of all successive matches as sub-slices of the input. Returns null when there are no matches.

```APIDOC
## findAll

### Description
Returns the texts of all successive matches as sub-slices of the input. Returns null when there are no matches.

### Method
Function

### Signature
```zig
pub fn Regexp.findAll(re: *const Regexp, allocator, input: []const u8, n: i64) ExecError!?[][]const u8
```

### Parameters
- `re` (*const Regexp) - Required - The compiled regular expression.
- `allocator` - Required - Memory allocator for the returned slice.
- `input` ([]const u8) - Required - The input text to search.
- `n` (i64) - Required - Maximum number of matches; negative means all, zero yields none, positive caps the count.

### Response
Returns `?[][]const u8` - null if no matches, otherwise an array of sub-slices of `input`. The caller owns the outer slice and must free it with `allocator.free`.
```

--------------------------------

### findSubmatchIndex

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Finds the first match and its submatches, returning owned slices of offsets. Free with allocator.free.

```APIDOC
## findSubmatchIndex

### Description
Finds the first match and its submatches, returning owned slices of offsets. Free with allocator.free.

### Method
findSubmatchIndex

### Parameters
- `allocator` (allocator) - Required - Allocator used for internal scratch and result.
- `input` (string) - Required - The input string to search.

### Returns
- `[][]usize` - Owned slice of offset pairs; free with allocator.free.
```

--------------------------------

### Regexp.numSubexp

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Returns the number of parenthesized subexpressions in the regexp.

```APIDOC
## Regexp.numSubexp

### Description
Returns the number of parenthesized subexpressions.

### Function Signature
```zig
pub fn Regexp.numSubexp(re: *const Regexp) usize
```

### Parameters
- `re` (*const Regexp) - Required - The compiled regexp.

### Returns
- `usize` - Number of parenthesized subexpressions.
```

--------------------------------

### Regexp.match

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Reports whether the input contains any match. Allocates nothing for the caller to free.

```APIDOC
## Regexp.match

### Description
Reports whether the input contains any match. Allocates nothing for the caller to free.

### Function Signature
```zig
pub fn Regexp.match(re: *const Regexp, allocator, input: []const u8) ExecError!bool
```

### Parameters
- `re` (*const Regexp) - Required - The compiled Regexp.
- `allocator` - Required - Allocator for scratch and results.
- `input` ([]const u8) - Required - The input string to search.

### Returns
- `ExecError!bool` - True if a match is found, false otherwise.
```

--------------------------------

### Matches.next

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Advances the iterator and returns the next match's submatch offsets, or null when there are no more matches.

```APIDOC
## Matches.next

### Description
Advances the iterator and returns the next match's submatch offsets, or null when there are no more matches.

### Method
Function

### Signature
```zig
pub fn Regexp.Matches.next(it: *Matches) ExecError!?[]const i64
```

### Parameters
- `it` (*Matches) - Required - The iterator to advance.

### Response
Returns `ExecError!?[]const i64` - null when no more matches, otherwise borrowed submatch offsets that are overwritten by the next call to `next()`.
```

--------------------------------

### Compile and use regex with findSubmatch in Zig

Source: https://github.com/zoptia/zoptia0regex/blob/main/README.md

Shows basic usage of the regex library: compile a pattern, find submatches, and free resources. The example matches an email-like string and outputs the full match and capture groups.

```zig
var re = try regex.compile(gpa, "(\\w+)@(\\w+)\\.(\\w+)");
defer re.deinit();

const subs = (try re.findSubmatch(gpa, "ping me@example.com")).?;
defer gpa.free(subs);
// subs => "me@example.com" / "me" / "example" / "com"
```

--------------------------------

### Wire regex module in build.zig

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Resolve the zoptia0regex dependency and add its 'regex' module to your executable module. Requires Zig 0.16 or 0.17.0-dev nightlies.

```zig
const std = @import("std");

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    const exe_mod = b.createModule(.{
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    });

    // Pull in zoptia0regex and expose its "regex" module to your code.
    const regex_dep = b.dependency("zoptia0regex", .{
        .target = target,
        .optimize = optimize,
    });
    exe_mod.addImport("regex", regex_dep.module("regex"));

    const exe = b.addExecutable(.{ .name = "myapp", .root_module = exe_mod });
    b.installArtifact(exe);
}
```

--------------------------------

### expand

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Expands a template string, appending the result to a buffer you own. The buffer is caller-owned and must be freed by the caller.

```APIDOC
## expand

### Description
Expands a template string, appending the result to a buffer you own. The buffer is caller-owned and must be freed by the caller.

### Method
expand

### Parameters
- `allocator` (allocator) - Required - Allocator used for internal scratch.
- `buf` ([]u8) - Required - Buffer to append the expanded result to.
- `template` (string) - Required - The template string to expand.

### Returns
- `void` - Appends to the provided buffer.
```

--------------------------------

### freeAllSubmatchIndex

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Frees the result of findAllSubmatchIndex, including each inner slice and the outer slice.

```APIDOC
## freeAllSubmatchIndex

### Description
Frees the result of findAllSubmatchIndex, including each inner slice and the outer slice.

### Method
Function

### Signature
```zig
pub fn Regexp.freeAllSubmatchIndex(allocator: std.mem.Allocator, x: [][]i64) void
```

### Parameters
- `allocator` (std.mem.Allocator) - Required - The allocator used to allocate the slices.
- `x` ([][]i64) - Required - The result from `findAllSubmatchIndex` to free.
```

--------------------------------

### replaceAllString

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Replaces every match with repl, expanding $1 / ${name} references. Returns a newly allocated string.

```APIDOC
## replaceAllString

### Description
Replaces every match with repl, expanding $1 / ${name} references. Returns a newly allocated string.

### Method
Function

### Signature
```zig
pub fn Regexp.replaceAllString(re: *const Regexp, allocator, src: []const u8, repl: []const u8) ExecError![]u8
```

### Parameters
- `re` (*const Regexp) - Required - The compiled regular expression.
- `allocator` - Required - Memory allocator for the returned string.
- `src` ([]const u8) - Required - The source text to replace in.
- `repl` ([]const u8) - Required - The replacement template with $ expansion.

### Response
Returns `ExecError![]u8` - a newly allocated string that the caller owns and must free with `allocator.free`.
```

--------------------------------

### Regexp.subexpNames

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Returns the names of the capturing groups; the first element is always an empty string.

```APIDOC
## Regexp.subexpNames

### Description
Returns the names of the capturing groups; `subexpNames()[0]` is always `""`.

### Function Signature
```zig
pub fn Regexp.subexpNames(re: *const Regexp) []const []const u8
```

### Parameters
- `re` (*const Regexp) - Required - The compiled regexp.

### Returns
- `[]const []const u8` - Names of capturing groups; borrowed from the Regexp.
```

--------------------------------

### Regexp.string

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Returns the source text the regexp was compiled from. The returned slice is borrowed from the Regexp and valid until deinit.

```APIDOC
## Regexp.string

### Description
Returns the source text the regexp was compiled from.

### Function Signature
```zig
pub fn Regexp.string(re: *const Regexp) []const u8
```

### Parameters
- `re` (*const Regexp) - Required - The compiled regexp.

### Returns
- `[]const u8` - The source text; borrowed from the Regexp, valid until `deinit`.
```

--------------------------------

### Regexp.subexpIndex

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Returns the index of the first subexpression with the given name, or null if not found.

```APIDOC
## Regexp.subexpIndex

### Description
Returns the index of the first subexpression with the given name, or `null`.

### Function Signature
```zig
pub fn Regexp.subexpIndex(re: *const Regexp, name: []const u8) ?usize
```

### Parameters
- `re` (*const Regexp) - Required - The compiled regexp.
- `name` ([]const u8) - Required - The name to search for.

### Returns
- `?usize` - Index of the first subexpression with the given name, or `null` if not found.
```

--------------------------------

### findIndex

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Finds the first match and returns a Match value with offsets. No result allocation to free.

```APIDOC
## findIndex

### Description
Finds the first match and returns a Match value with offsets. No result allocation to free.

### Method
findIndex

### Parameters
- `allocator` (allocator) - Required - Allocator used for internal scratch.
- `input` (string) - Required - The input string to search.

### Returns
- `Match` - The match result with offsets.
```

--------------------------------

### Compile and defer deinit with regex.compile

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Compiles a pattern with the given allocator and frees the entire arena in one shot via defer re.deinit(). The compiled program, subexpression names, source text, and prefix all live inside the arena.

```zig
var re = try regex.compile(gpa, pattern);
defer re.deinit();
```

--------------------------------

### Scratch variants

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

The *Scratch variants borrow all working memory from the Scratch you pass; scratch.deinit() frees it all. Nothing they return is yours to free.

```APIDOC
## Scratch variants

### Description
The *Scratch variants borrow all working memory from the Scratch you pass; scratch.deinit() frees it all. Nothing they return is yours to free.

### Methods
- `findSubmatchIndexScratch` - Uses Scratch for working memory and result slice.

### Parameters
- `scratch` (Scratch) - Required - Scratch buffer to borrow memory from.

### Returns
- Various - Results are borrowed from the Scratch; do not free.
```

--------------------------------

### replaceAllLiteralString

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Replaces every match with repl literally, without $ expansion. Returns a newly allocated string.

```APIDOC
## replaceAllLiteralString

### Description
Replaces every match with repl literally, without $ expansion. Returns a newly allocated string.

### Method
Function

### Signature
```zig
pub fn Regexp.replaceAllLiteralString(re: *const Regexp, allocator, src: []const u8, repl: []const u8) ExecError![]u8
```

### Parameters
- `re` (*const Regexp) - Required - The compiled regular expression.
- `allocator` - Required - Memory allocator for the returned string.
- `src` ([]const u8) - Required - The source text to replace in.
- `repl` ([]const u8) - Required - The literal replacement string.

### Response
Returns `ExecError![]u8` - a newly allocated string that the caller owns and must free with `allocator.free`.
```

--------------------------------

### split

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Splits src around matches (Go's Split). Returns null when n == 0.

```APIDOC
## split

### Description
Splits src around matches (Go's Split). Returns null when n == 0.

### Method
Function

### Signature
```zig
pub fn Regexp.split(re: *const Regexp, allocator, src: []const u8, n: i64) ExecError!?[][]const u8
```

### Parameters
- `re` (*const Regexp) - Required - The compiled regular expression.
- `allocator` - Required - Memory allocator for the returned slice.
- `src` ([]const u8) - Required - The source text to split.
- `n` (i64) - Required - Maximum number of pieces; negative means all, zero returns null, positive caps the count.

### Response
Returns `?[][]const u8` - null if n == 0, otherwise an array of sub-slices of `src`. The caller owns the outer slice and must free it with `allocator.free`.
```

--------------------------------

### deinit

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Frees all memory allocated by the Regexp's arena. Call once after compilation to release everything.

```APIDOC
## deinit

### Description
Frees all memory allocated by the Regexp's arena. Call once after compilation to release everything.

### Method
deinit

### Parameters
- `re` (Regexp) - Required - The compiled regex to deinitialize.

### Example
```zig
defer re.deinit();
```
```

--------------------------------

### matches

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Returns an iterator over successive matches (Go 1.27's matches / All*). next() yields borrowed submatch offsets, deinit() frees it.

```APIDOC
## matches

### Description
Returns an iterator over successive matches (Go 1.27's matches / All*). next() yields borrowed submatch offsets, deinit() frees it.

### Method
Function

### Signature
```zig
pub fn Regexp.matches(re: *const Regexp, allocator, input: []const u8, n: i64) ExecError!Regexp.Matches
```

### Parameters
- `re` (*const Regexp) - Required - The compiled regular expression.
- `allocator` - Required - Memory allocator for the iterator.
- `input` ([]const u8) - Required - The input text to search.
- `n` (i64) - Required - Maximum number of matches; negative means all, zero yields none, positive caps the count.

### Response
Returns `ExecError!Regexp.Matches` - an iterator that must be deinitialized with `deinit`.

### Example
```zig
var it = try re.matches(gpa, input, -1);
defer it.deinit();
while (try it.next()) |m| {
    // m[0..2] is the whole match, m[2*k..2*k+2] group k (-1 = unset).
    // m is borrowed: it is overwritten by the next call to next().
    std.debug.print("{s}\n", .{input[@intCast(m[0])..@intCast(m[1])]});
}
```
```

--------------------------------

### Introspection method signatures

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Read-only methods on Regexp that return borrowed slices valid until deinit; none allocate.

```zig
pub fn Regexp.string(re: *const Regexp) []const u8
pub fn Regexp.numSubexp(re: *const Regexp) usize
pub fn Regexp.subexpNames(re: *const Regexp) []const []const u8
pub fn Regexp.subexpIndex(re: *const Regexp, name: []const u8) ?usize
pub fn Regexp.literalPrefix(re: *const Regexp) struct { prefix: []const u8, complete: bool }
```

--------------------------------

### Boolean match method signatures

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Signatures for Regexp.match and Regexp.matchString. Both report whether input contains any match and allocate nothing for the caller to free.

```zig
pub fn Regexp.match(re: *const Regexp, allocator, input: []const u8) ExecError!bool
pub fn Regexp.matchString(re: *const Regexp, allocator, s: []const u8) ExecError!bool
```

--------------------------------

### compile

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Compiles a regular expression pattern, allocating an arena from the provided allocator. The compiled program, subexpression names, source text, and prefix live inside the arena; call deinit() to free everything.

```APIDOC
## compile

### Description
Compiles a regular expression pattern, allocating an arena from the provided allocator. The compiled program, subexpression names, source text, and prefix live inside the arena; call deinit() to free everything.

### Method
compile

### Parameters
- `gpa` (allocator) - Required - Allocator used to allocate the arena.
- `pattern` (string) - Required - The regular expression pattern to compile.

### Returns
- `Regexp` - The compiled regular expression.

### Example
```zig
var re = try regex.compile(gpa, pattern);
defer re.deinit();
```
```

--------------------------------

### quoteMeta

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Quotes all regular expression metacharacters in a string. Returns an owned []u8; free with allocator.free.

```APIDOC
## quoteMeta

### Description
Quotes all regular expression metacharacters in a string. Returns an owned []u8; free with allocator.free.

### Method
quoteMeta

### Parameters
- `allocator` (allocator) - Required - Allocator used for internal scratch and result.
- `input` (string) - Required - The string to quote.

### Returns
- `[]u8` - Owned quoted string; free with allocator.free.
```

--------------------------------

### match

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Checks if the pattern matches the input. Uses the provided allocator for internal scratch and returns a boolean result.

```APIDOC
## match

### Description
Checks if the pattern matches the input. Uses the provided allocator for internal scratch and returns a boolean result.

### Method
match

### Parameters
- `allocator` (allocator) - Required - Allocator used for internal scratch.
- `input` (string) - Required - The input string to search.

### Returns
- `bool` - True if a match is found, false otherwise.
```

--------------------------------

### findAllSubmatchIndex

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Returns submatch offsets for every match; each inner slice has length 2*(numSubexp+1). Returns null when there are no matches.

```APIDOC
## findAllSubmatchIndex

### Description
Returns submatch offsets for every match; each inner slice has length 2*(numSubexp+1). Returns null when there are no matches.

### Method
Function

### Signature
```zig
pub fn Regexp.findAllSubmatchIndex(re: *const Regexp, allocator, input: []const u8, n: i64) ExecError!?[][]i64
```

### Parameters
- `re` (*const Regexp) - Required - The compiled regular expression.
- `allocator` - Required - Memory allocator for the returned slices.
- `input` ([]const u8) - Required - The input text to search.
- `n` (i64) - Required - Maximum number of matches; negative means all, zero yields none, positive caps the count.

### Response
Returns `?[][]i64` - null if no matches, otherwise an array of submatch offset slices. The caller owns both the outer and every inner slice and must free them with `freeAllSubmatchIndex`.

### Example
```zig
if (try re.findAllSubmatchIndex(gpa, input, -1)) |all| {
    defer regex.Regexp.freeAllSubmatchIndex(gpa, all);
    // use all[i] ...
}
```
```

--------------------------------

### replaceAllStringFunc

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Replaces every match with the result of a function applied to the matched text. Returns a newly allocated string.

```APIDOC
## replaceAllStringFunc

### Description
Replaces every match with the result of a function applied to the matched text. Returns a newly allocated string.

### Method
Function

### Signature
```zig
pub fn Regexp.replaceAllStringFunc(
    re: *const Regexp,
    allocator: std.mem.Allocator,
    src: []const u8,
    ctx: anytype,
    comptime func: fn (@TypeOf(ctx), []const u8) []const u8,
) ExecError![]u8
```

### Parameters
- `re` (*const Regexp) - Required - The compiled regular expression.
- `allocator` (std.mem.Allocator) - Required - Memory allocator for the returned string.
- `src` ([]const u8) - Required - The source text to replace in.
- `ctx` (anytype) - Required - Context passed through to `func`.
- `func` (comptime fn) - Required - Function that receives the matched text and returns a replacement slice valid for the duration of the call.

### Response
Returns `ExecError![]u8` - a newly allocated string that the caller owns and must free with `allocator.free`.

### Example
```zig
const Up = struct {
    fn f(_: @This(), s: []const u8) []const u8 {
        _ = s;
        return "X"; // returned slice must outlive only the call
    }
};
const out = try re.replaceAllStringFunc(gpa, src, Up{}, Up.f);
defer gpa.free(out);
```
```

--------------------------------

### Free findAllSubmatchIndex result with freeAllSubmatchIndex

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Frees the result of `findAllSubmatchIndex`, including each inner slice and the outer slice. Use `defer` to ensure cleanup.

```zig
if (try re.findAllSubmatchIndex(gpa, input, -1)) |all| {
    defer regex.Regexp.freeAllSubmatchIndex(gpa, all);
    // use all[i] ...
}
```

--------------------------------

### Regexp findAll, findAllIndex, findAllSubmatchIndex, freeAllSubmatchIndex, matches signatures

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Declarations for the match-finding methods. `n` caps matches: `n < 0` means all, `n == 0` yields none, `n > 0` returns at most `n`. `findAllSubmatchIndex` returns submatch offsets with each inner slice length `2*(numSubexp+1)`; free it with `freeAllSubmatchIndex`. `matches` is the underlying iterator port of Go 1.27's `matches`.

```zig
pub fn Regexp.findAll(re: *const Regexp, allocator, input: []const u8, n: i64) ExecError!?[][]const u8
pub fn Regexp.findAllIndex(re: *const Regexp, allocator, input: []const u8, n: i64) ExecError!?[]Match
pub fn Regexp.findAllSubmatchIndex(re: *const Regexp, allocator, input: []const u8, n: i64) ExecError!?[][]i64
pub fn Regexp.freeAllSubmatchIndex(allocator: std.mem.Allocator, x: [][]i64) void
pub fn Regexp.matches(re: *const Regexp, allocator, input: []const u8, n: i64) ExecError!Regexp.Matches
pub fn Regexp.Matches.next(it: *Matches) ExecError!?[]const i64
pub fn Regexp.Matches.deinit(it: *Matches) void
```

--------------------------------

### findAll

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Finds all non-overlapping matches. Returns a slice whose elements are sub-slices of the input; free only the outer slice.

```APIDOC
## findAll

### Description
Finds all non-overlapping matches. Returns a slice whose elements are sub-slices of the input; free only the outer slice.

### Method
findAll

### Parameters
- `allocator` (allocator) - Required - Allocator used for internal scratch and result.
- `input` (string) - Required - The input string to search.

### Returns
- `[][]const u8` - Slice of matched sub-slices; free with allocator.free.
```

--------------------------------

### Regexp.setLongest

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Switches an existing Regexp to leftmost-longest matching for future searches. This method modifies the Regexp in place.

```APIDOC
## Regexp.setLongest

### Description
Switches an existing Regexp to leftmost-longest matching for future searches. This method modifies the Regexp in place.

### Function Signature
```zig
pub fn Regexp.setLongest(re: *Regexp) void
```

### Parameters
- `re` (*Regexp) - Required - Pointer to the Regexp to modify.
```

--------------------------------

### split

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Splits the input by matches. Returns a slice whose elements are sub-slices of the input; free only the outer slice.

```APIDOC
## split

### Description
Splits the input by matches. Returns a slice whose elements are sub-slices of the input; free only the outer slice.

### Method
split

### Parameters
- `allocator` (allocator) - Required - Allocator used for internal scratch and result.
- `input` (string) - Required - The input string to split.

### Returns
- `[][]const u8` - Slice of sub-slices; free with allocator.free.
```

--------------------------------

### Compile and find submatches in Zig

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Compiles a pattern with three capturing groups and extracts submatches from an input string. The Regexp owns a heap arena freed by deinit(); findSubmatch returns null on no match and the outer slice is caller-owned and must be freed. Each submatch element is a sub-slice of the original input or null for non-participating groups.

```zig
const std = @import("std");
const regex = @import("regex");

pub fn main() !void {
    var gpa_state: std.heap.DebugAllocator(.{}) = .{};
    defer _ = gpa_state.deinit();
    const gpa = gpa_state.allocator();

    // Compile once; the Regexp owns a heap arena freed by deinit().
    var re = try regex.compile(gpa, "(\\w+)@(\\w+)\\.(\\w+)");
    defer re.deinit();

    // findSubmatch returns null on no match; the outer slice is caller-owned.
    if (try re.findSubmatch(gpa, "ping me@example.com")) |subs| {
        defer gpa.free(subs);
        // subs[0] is the whole match; subs[1..] are the groups.
        // subs[1] = "me", subs[2] = "example", subs[3] = "com"
        for (subs, 0..) |s, i| {
            if (s) |text| {
                std.debug.print("group {d}: {s}\n", .{ i, text });
            } else {
                std.debug.print("group {d}: <none>\n", .{i});
            }
        }
    } else {
        std.debug.print("no match\n", .{});
    }
}
```

--------------------------------

### compilePOSIX

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Compiles a regular expression pattern with POSIX ERE syntax and leftmost-longest semantics. Returns a Regexp value that owns an internal arena until deinit is called.

```APIDOC
## compilePOSIX

### Description
Compiles a regular expression pattern with POSIX ERE syntax and leftmost-longest semantics. Returns a Regexp value that owns an internal arena until deinit is called.

### Function Signature
```zig
pub fn compilePOSIX(gpa: std.mem.Allocator, expr: []const u8) ParseError!Regexp
```

### Parameters
- `gpa` (std.mem.Allocator) - Required - Allocator that backs the Regexp's internal arena.
- `expr` ([]const u8) - Required - The regular expression pattern to compile.

### Returns
- `ParseError!Regexp` - The compiled Regexp or a ParseError if the pattern is malformed.
```

--------------------------------

### Regexp.findSubmatchIndex

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Returns submatch byte offsets as an array of i64, with -1 for groups that did not participate. The result is heap-allocated and must be freed by the caller.

```APIDOC
## Regexp.findSubmatchIndex

### Description
Returns submatch byte offsets as an array of i64, with -1 for groups that did not participate. The result is heap-allocated and must be freed by the caller.

### Function Signature
```zig
pub fn Regexp.findSubmatchIndex(re: *const Regexp, allocator, input: []const u8) ExecError!?[]i64
```

### Parameters
- `re` (*const Regexp) - Required - The compiled Regexp.
- `allocator` - Required - Allocator for scratch and results.
- `input` ([]const u8) - Required - The input string to search.

### Returns
- `ExecError!?[]i64` - An array of byte offsets of length 2*(numSubexp+1), or null if no match. -1 indicates a group that did not participate.
```

--------------------------------

### findSubmatch

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Finds the first match and its submatches. Returns a slice whose elements are sub-slices of the input; free only the outer slice.

```APIDOC
## findSubmatch

### Description
Finds the first match and its submatches. Returns a slice whose elements are sub-slices of the input; free only the outer slice.

### Method
findSubmatch

### Parameters
- `allocator` (allocator) - Required - Allocator used for internal scratch and result.
- `input` (string) - Required - The input string to search.

### Returns
- `[][]const u8` - Slice of matched sub-slices; free with allocator.free.
```

--------------------------------

### Regexp.find

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Returns the text of the leftmost match as a sub-slice of the input. Returns null if there is no match. The returned slice is not owned by the caller.

```APIDOC
## Regexp.find

### Description
Returns the text of the leftmost match as a sub-slice of the input. Returns null if there is no match. The returned slice is not owned by the caller.

### Function Signature
```zig
pub fn Regexp.find(re: *const Regexp, allocator, input: []const u8) ExecError!?[]const u8
```

### Parameters
- `re` (*const Regexp) - Required - The compiled Regexp.
- `allocator` - Required - Allocator for scratch and results.
- `input` ([]const u8) - Required - The input string to search.

### Returns
- `ExecError!?[]const u8` - The matched text as a sub-slice of input, or null if no match.
```

--------------------------------

### Regexp.matchString

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Alias of match; both take []const u8. Reports whether the input contains any match. Allocates nothing for the caller to free.

```APIDOC
## Regexp.matchString

### Description
Alias of match; both take []const u8. Reports whether the input contains any match. Allocates nothing for the caller to free.

### Function Signature
```zig
pub fn Regexp.matchString(re: *const Regexp, allocator, s: []const u8) ExecError!bool
```

### Parameters
- `re` (*const Regexp) - Required - The compiled Regexp.
- `allocator` - Required - Allocator for scratch and results.
- `s` ([]const u8) - Required - The input string to search.

### Returns
- `ExecError!bool` - True if a match is found, false otherwise.
```

--------------------------------

### compile

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Compiles a regular expression pattern with Perl (leftmost-first) semantics. Returns a Regexp value that owns an internal arena until deinit is called.

```APIDOC
## compile

### Description
Compiles a regular expression pattern with Perl (leftmost-first) semantics. Returns a Regexp value that owns an internal arena until deinit is called.

### Function Signature
```zig
pub fn compile(gpa: std.mem.Allocator, expr: []const u8) ParseError!Regexp
```

### Parameters
- `gpa` (std.mem.Allocator) - Required - Allocator that backs the Regexp's internal arena.
- `expr` ([]const u8) - Required - The regular expression pattern to compile.

### Returns
- `ParseError!Regexp` - The compiled Regexp or a ParseError if the pattern is malformed.
```

--------------------------------

### Regexp.split signature

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Declaration for `split`, which splits `src` around matches (Go's `Split`). `n < 0` returns all pieces; `n == 0` returns `null`; `n > 0` returns at most `n` pieces (the final piece holds the unsplit remainder). Pieces are sub-slices of `src`; free the outer slice with `allocator.free`.

```zig
pub fn Regexp.split(re: *const Regexp, allocator, src: []const u8, n: i64) ExecError!?[][]const u8
```

--------------------------------

### Regexp.findIndex

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Returns the byte offsets of the leftmost match as a Match struct. Returns null if there is no match. The result is not owned by the caller.

```APIDOC
## Regexp.findIndex

### Description
Returns the byte offsets of the leftmost match as a Match struct. Returns null if there is no match. The result is not owned by the caller.

### Function Signature
```zig
pub fn Regexp.findIndex(re: *const Regexp, allocator, input: []const u8) ExecError!?Match
```

### Parameters
- `re` (*const Regexp) - Required - The compiled Regexp.
- `allocator` - Required - Allocator for scratch and results.
- `input` ([]const u8) - Required - The input string to search.

### Returns
- `ExecError!?Match` - A Match struct with start and end offsets, or null if no match.
```

--------------------------------

### replaceAllString, replaceAllLiteralString, replaceAllStringFunc signatures

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Declarations for replacement methods. `replaceAllString` expands `$1`/`${name}` references; `replaceAllLiteralString` replaces literally; `replaceAllStringFunc` applies a function to matched text. All return a freshly allocated `[]u8` the caller owns (free with `allocator.free`).

```zig
pub fn Regexp.replaceAllString(re: *const Regexp, allocator, src: []const u8, repl: []const u8) ExecError![]u8
pub fn Regexp.replaceAllLiteralString(re: *const Regexp, allocator, src: []const u8, repl: []const u8) ExecError![]u8
pub fn Regexp.replaceAllStringFunc(
    re: *const Regexp,
    allocator: std.mem.Allocator,
    src: []const u8,
    ctx: anytype,
    comptime func: fn (@TypeOf(ctx), []const u8) []const u8,
) ExecError![]u8
```

--------------------------------

### Find leftmost match method signatures

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Signatures for Regexp.find and Regexp.findIndex. find returns the text of the leftmost match as a sub-slice of input; findIndex returns byte offsets as a Match. Both return null on no match and do not allocate owned memory.

```zig
pub fn Regexp.find(re: *const Regexp, allocator, input: []const u8) ExecError!?[]const u8
pub fn Regexp.findIndex(re: *const Regexp, allocator, input: []const u8) ExecError!?Match
```

--------------------------------

### Match and ExecError type definitions

Source: https://github.com/zoptia/zoptia0regex/blob/main/docs/usage.md

Defines the Match struct and ExecError type used in API signatures. ExecError is an alias for std.mem.Allocator.Error, indicating allocation failure is the only runtime error.

```zig
pub const Match = struct { start: usize, end: usize };
pub const ExecError = std.mem.Allocator.Error;
```
Tokens:
Raw