impl<'h> Captures<'h>

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

Returns the Match associated with the capture group at index i. If i does not correspond to a capture group, or if the capture group did not participate in the match, then None is returned.

When i == 0, this is guaranteed to return a non-None value.

Examples

Get the substring that matched with a default of an empty string if the group didn't participate in the match:

use regex::Regex;

let re = Regex::new(r"[a-z]+(?:([0-9]+)|([A-Z]+))").unwrap();
let caps = re.captures("abc123").unwrap();

let substr1 = caps.get(1).map_or("", |m| m.as_str());
let substr2 = caps.get(2).map_or("", |m| m.as_str());
assert_eq!(substr1, "123");
assert_eq!(substr2, "");

fn get_match(&self) -> Match<'h>

Return the overall match for the capture.

This returns the match for index 0. That is it is equivalent to m.get(0).unwrap()

Example

use regex::Regex;

let re = Regex::new(r"[a-z]+([0-9]+)").unwrap();
let caps = re.captures("   abc123-def").unwrap();

assert_eq!(caps.get_match().as_str(), "abc123");

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

Returns the Match associated with the capture group named name. If name isn't a valid capture group or it refers to a group that didn't match, then None is returned.

Note that unlike caps["name"], this returns a Match whose lifetime matches the lifetime of the haystack in this Captures value. Conversely, the substring returned by caps["name"] has a lifetime of the Captures value, which is likely shorter than the lifetime of the haystack. In some cases, it may be necessary to use this method to access the matching substring instead of the caps["name"] notation.

Examples

Get the substring that matched with a default of an empty string if the group didn't participate in the match:

use regex::Regex;

let re = Regex::new(
    r"[a-z]+(?:(?<numbers>[0-9]+)|(?<letters>[A-Z]+))",
).unwrap();
let caps = re.captures("abc123").unwrap();

let numbers = caps.name("numbers").map_or("", |m| m.as_str());
let letters = caps.name("letters").map_or("", |m| m.as_str());
assert_eq!(numbers, "123");
assert_eq!(letters, "");

fn extract<const N: usize>(&self) -> (&'h str, [&'h str; N])

This is a convenience routine for extracting the substrings corresponding to matching capture groups.

This returns a tuple where the first element corresponds to the full substring of the haystack that matched the regex. The second element is an array of substrings, with each corresponding to the substring that matched for a particular capture group.

Panics

This panics if the number of possible matching groups in this Captures value is not fixed to N in all circumstances. More precisely, this routine only works when N is equivalent to Regex::static_captures_len.

Stated more plainly, if the number of matching capture groups in a regex can vary from match to match, then this function always panics.

For example, (a)(b)|(c) could produce two matching capture groups or one matching capture group for any given match. Therefore, one cannot use extract with such a pattern.

But a pattern like (a)(b)|(c)(d) can be used with extract because the number of capture groups in every match is always equivalent, even if the capture indices in each match are not.

Example

use regex::Regex;

let re = Regex::new(r"([0-9]{4})-([0-9]{2})-([0-9]{2})").unwrap();
let hay = "On 2010-03-14, I became a Tennessee lamb.";
let Some((full, [year, month, day])) =
    re.captures(hay).map(|caps| caps.extract()) else { return };
assert_eq!("2010-03-14", full);
assert_eq!("2010", year);
assert_eq!("03", month);
assert_eq!("14", day);

Example: iteration

This example shows how to use this method when iterating over all Captures matches in a haystack.

use regex::Regex;

let re = Regex::new(r"([0-9]{4})-([0-9]{2})-([0-9]{2})").unwrap();
let hay = "1973-01-05, 1975-08-25 and 1980-10-18";

let mut dates: Vec<(&str, &str, &str)> = vec![];
for (_, [y, m, d]) in re.captures_iter(hay).map(|c| c.extract()) {
    dates.push((y, m, d));
}
assert_eq!(dates, vec![
    ("1973", "01", "05"),
    ("1975", "08", "25"),
    ("1980", "10", "18"),
]);

Example: parsing different formats

This API is particularly useful when you need to extract a particular value that might occur in a different format. Consider, for example, an identifier that might be in double quotes or single quotes:

use regex::Regex;

let re = Regex::new(r#"id:(?:"([^"]+)"|'([^']+)')"#).unwrap();
let hay = r#"The first is id:"foo" and the second is id:'bar'."#;
let mut ids = vec![];
for (_, [id]) in re.captures_iter(hay).map(|c| c.extract()) {
    ids.push(id);
}
assert_eq!(ids, vec!["foo", "bar"]);

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

Expands all instances of $ref in replacement to the corresponding capture group, and writes them to the dst buffer given. A ref can be a capture group index or a name. If ref doesn't refer to a capture group that participated in the match, then it is replaced with the empty string.

Format

The format of the replacement string supports two different kinds of capture references: unbraced and braced.

For the unbraced format, the format supported is $ref where name can be any character in the class [0-9A-Za-z_]. ref is always the longest possible parse. So for example, $1a corresponds to the capture group named 1a and not the capture group at index 1. If ref matches ^[0-9]+$, then it is treated as a capture group index itself and not a name.

For the braced format, the format supported is ${ref} where ref can be any sequence of bytes except for }. If no closing brace occurs, then it is not considered a capture reference. As with the unbraced format, if ref matches ^[0-9]+$, then it is treated as a capture group index and not a name.

The braced format is useful for exerting precise control over the name of the capture reference. For example, ${1}a corresponds to the capture group reference 1 followed by the letter a, where as $1a (as mentioned above) corresponds to the capture group reference 1a. The braced format is also useful for expressing capture group names that use characters not supported by the unbraced format. For example, ${foo[bar].baz} refers to the capture group named foo[bar].baz.

If a capture group reference is found and it does not refer to a valid capture group, then it will be replaced with the empty string.

To write a literal $, use $$.

Example

use regex::Regex;

let re = Regex::new(
    r"(?<day>[0-9]{2})-(?<month>[0-9]{2})-(?<year>[0-9]{4})",
).unwrap();
let hay = "On 14-03-2010, I became a Tennessee lamb.";
let caps = re.captures(hay).unwrap();

let mut dst = String::new();
caps.expand("year=$year, month=$month, day=$day", &mut dst);
assert_eq!(dst, "year=2010, month=03, day=14");

fn iter<'c>(&'c self) -> SubCaptureMatches<'c, 'h>

Returns an iterator over all capture groups. This includes both matching and non-matching groups.

The iterator always yields at least one matching group: the first group (at index 0) with no name. Subsequent groups are returned in the order of their opening parenthesis in the regex.

The elements yielded have type Option<Match<'h>>, where a non-None value is present if the capture group matches.

Example

use regex::Regex;

let re = Regex::new(r"(\w)(\d)?(\w)").unwrap();
let caps = re.captures("AZ").unwrap();

let mut it = caps.iter();
assert_eq!(it.next().unwrap().map(|m| m.as_str()), Some("AZ"));
assert_eq!(it.next().unwrap().map(|m| m.as_str()), Some("A"));
assert_eq!(it.next().unwrap().map(|m| m.as_str()), None);
assert_eq!(it.next().unwrap().map(|m| m.as_str()), Some("Z"));
assert_eq!(it.next(), None);

fn len(&self) -> usize

Returns the total number of capture groups. This includes both matching and non-matching groups.

The length returned is always equivalent to the number of elements yielded by Captures::iter. Consequently, the length is always greater than zero since every Captures value always includes the match for the entire regex.

Example

use regex::Regex;

let re = Regex::new(r"(\w)(\d)?(\w)").unwrap();
let caps = re.captures("AZ").unwrap();
assert_eq!(caps.len(), 4);