### 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}: \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; ```