Struct Captures 

pub struct Captures<'t> { /* private fields */ }

All capture groups from a single match.

Group 0 is the entire match. Groups 1..N correspond to (...) in the pattern.

A Captures borrows only the haystack, not the Regex that produced it, so it can be returned from a function that received the regex by reference. It keeps a shared handle to the compiled program for name lookups, so creating one costs an atomic increment and no allocation.

Examples

use ferroni::api::Regex;

fn year<'h>(re: &Regex, text: &'h str) -> Option<&'h str> {
    re.captures(text)?.name("year").map(|m| m.as_str())
}

let re = Regex::new(r"(?<year>\d{4})-\d{2}").unwrap();
assert_eq!(year(&re, "published 2026-10"), Some("2026"));

Implementations

impl<'t> Captures<'t>

pub fn get(&self, i: usize) -> Option<Match<'t>>

Get capture group i, or None if the group did not participate.

Group 0 is the entire match.

Like Oniguruma, the engine can leave a capture with its start after its end: a group that matched once, then started again and failed before closing, keeps the new start and the old end (for example group 1 of ((?=(a|ab))a?){2} against "a" is 1..0). Such a capture is not a range of the text and is reported as not participating (None), here and in Captures::iter and Captures::name. The raw values stay available through the low-level OnigRegion.

pub fn name(&self, name: &str) -> Option<Match<'t>>

Get the last capture group with the given name that participated, or None.

pub fn len(&self) -> usize

Number of capture groups (including group 0).

pub fn is_empty(&self) -> bool

Returns true if there are no capture groups (should never happen for a valid match).

pub fn iter(&self) -> CapturesIter<'_, 't>

Iterate over all capture groups.

impl Captures<'_>

pub fn expand(&self, replacement: &str, dst: &mut String)

Append replacement to dst, with each $ reference replaced by the text of the group it names.

The references are:

• $1 or ${1}: the group with that number. Group 0 is the whole match.
• $name or ${name}: the group with that name, resolved as Captures::name does, so a name shared by several groups yields the last one that participated.
• $$: a literal $.

An unbraced name is the longest run of [_0-9A-Za-z] after the $, so $1x refers to a group named 1x, not to group 1 followed by x. Write ${1}x to follow a group with letters. A braced reference runs to the first }, and what lies between the braces is looked up as a number or a name, so ${a-b} refers to a group named a-b.

A reference to a group that does not exist, or that did not participate in the match, expands to nothing. A $ that starts no reference, such as a $ at the end, a $ before a character that cannot start a name, or a ${ with no } after it, is copied literally.

Named groups hide plain groups

As in Oniguruma, a pattern with named groups does not capture its plain (...) groups, unless the pattern was built with RegexBuilder::capture_group(true). So $2 in (?<y>\d+)-(\d+) refers to no group and expands to nothing, while the named $y works:

use ferroni::prelude::*;

let re = Regex::new(r"(?<y>\d+)-(\d+)").unwrap();
let caps = re.captures("2026-10").unwrap();
let mut out = String::new();
caps.expand("$y/$2", &mut out);
assert_eq!(out, "2026/");

let re = Regex::builder(r"(?<y>\d+)-(\d+)").capture_group(true).build().unwrap();
let caps = re.captures("2026-10").unwrap();
let mut out = String::new();
caps.expand("$y/$2", &mut out);
assert_eq!(out, "2026/10");

Panics

Panics if a group that the template inserts is not valid UTF-8. That only happens for captures from the _bytes methods; use Captures::expand_bytes for those.

use ferroni::prelude::*;

let re = Regex::new(r"(?<word>\w+)-(?<num>\d+)").unwrap();
let caps = re.captures("item-42").unwrap();

let mut out = String::new();
caps.expand("$word:$2 $0 $$ $3 ${num}x $num-", &mut out);
assert_eq!(out, "item:42 item-42 $  42x 42-");

pub fn expand_bytes(&self, replacement: &[u8], dst: &mut Vec<u8>)

Append replacement to dst as bytes, with the same rules as Captures::expand. Use it for captures from the _bytes methods, whose groups need not be valid UTF-8.

use ferroni::prelude::*;

let re = Regex::new(r"(?<word>\w+)").unwrap();
let caps = re.captures_bytes(b"hello").unwrap();
let mut out = Vec::new();
caps.expand_bytes(b"[$word]", &mut out);
assert_eq!(out, b"[hello]");

Trait Implementations

impl Debug for Captures<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Captures<'_>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<'n> Index<&'n str> for Captures<'_>

Returns the text of the last participating group named name, as Captures::name does.

Panics

Panics if no group has that name, if no group with that name participated in the match, or if its bytes are not valid UTF-8 (captures from the _bytes methods). Captures::name reports these cases as None.

use ferroni::api::Regex;

let re = Regex::new(r"(?<year>\d{4})-(?<month>\d{2})").unwrap();
let caps = re.captures("2026-10").unwrap();
assert_eq!(&caps["year"], "2026");

type Output = str

The returned type after indexing.

fn index(&self, name: &'n str) -> &str

Performs the indexing (container[index]) operation.

impl Index<usize> for Captures<'_>

Returns the text of group i.

Panics

Panics if the pattern has no group i, if group i did not participate in the match, or if its bytes are not valid UTF-8 (captures from the _bytes methods). Captures::get reports the first two cases as None.

use ferroni::api::Regex;

let re = Regex::new(r"(?<year>\d{4})-(?<month>\d{2})").unwrap();
let caps = re.captures("2026-10").unwrap();
assert_eq!(&caps[1], "2026");
assert_eq!(&caps[2], "10");

type Output = str

The returned type after indexing.

fn index(&self, i: usize) -> &str

Performs the indexing (container[index]) operation.