Struct regex::Captures

source ·
pub struct Captures<'t> { /* private fields */ }
Expand description

Captures represents a group of captured strings for a single match.

The 0th capture always corresponds to the entire match. Each subsequent index corresponds to the next capture group in the regex. If a capture group is named, then the matched string is also available via the name method. (Note that the 0th capture is always unnamed and so must be accessed with the get method.)

Positions returned from a capture group are always byte indices.

't is the lifetime of the matched text.

Implementations§

source§

impl<'t> Captures<'t>

source

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

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.

Examples

Get the text of the match with a default of an empty string if this group didn’t participate in the match:

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

let text1 = caps.get(1).map_or("", |m| m.as_str());
let text2 = caps.get(2).map_or("", |m| m.as_str());
assert_eq!(text1, "123");
assert_eq!(text2, "");
source

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

Returns the match for the capture group named name. If name isn’t a valid capture group or didn’t match anything, then None is returned.

source

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

An iterator that yields all capturing matches in the order in which they appear in the regex. If a particular capture group didn’t participate in the match, then None is yielded for that capture.

The first match always corresponds to the overall match of the regex.

source

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

Expands all instances of $name in replacement to the corresponding capture group name, and writes them to the dst buffer given.

name may be an integer corresponding to the index of the capture group (counted by order of opening parenthesis where 0 is the entire match) or it can be a name (consisting of letters, digits or underscores) corresponding to a named capture group.

If name isn’t a valid capture group (whether the name doesn’t exist or isn’t a valid index), then it is replaced with the empty string.

The longest possible name consisting of the characters [_0-9A-Za-z] is used. e.g., $1a looks up the capture group named 1a and not the capture group at index 1. To exert more precise control over the name, or to refer to a capture group name that uses characters outside of [_0-9A-Za-z], use braces, e.g., ${1}a or ${foo[bar].baz}. When using braces, any sequence of characters is permitted. If the sequence does not refer to a capture group name in the corresponding regex, then it is replaced with an empty string.

To write a literal $ use $$.

source

pub fn len(&self) -> usize

Returns the total number of capture groups (even if they didn’t match).

This is always at least 1, since every regex has at least one capture group that corresponds to the full match.

Trait Implementations§

source§

impl<'t> Debug for Captures<'t>

source§

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

Formats the value using the given formatter. Read more
source§

impl<'t, 'i> Index<&'i str> for Captures<'t>

Get a group by name.

't is the lifetime of the matched text and 'i is the lifetime of the group name (the index).

The text can’t outlive the Captures object if this method is used, because of how Index is defined (normally a[i] is part of a and can’t outlive it); to do that, use name instead.

Panics

If there is no group named by the given value.

§

type Output = str

The returned type after indexing.
source§

fn index<'a>(&'a self, name: &'i str) -> &'a str

Performs the indexing (container[index]) operation. Read more
source§

impl<'t> Index<usize> for Captures<'t>

Get a group by index.

't is the lifetime of the matched text.

The text can’t outlive the Captures object if this method is used, because of how Index is defined (normally a[i] is part of a and can’t outlive it); to do that, use get() instead.

Panics

If there is no group at the given index.

§

type Output = str

The returned type after indexing.
source§

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

Performs the indexing (container[index]) operation. Read more

Auto Trait Implementations§

§

impl<'t> RefUnwindSafe for Captures<'t>

§

impl<'t> Send for Captures<'t>

§

impl<'t> Sync for Captures<'t>

§

impl<'t> Unpin for Captures<'t>

§

impl<'t> UnwindSafe for Captures<'t>

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

const: unstable · source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

const: unstable · source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

const: unstable · source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

const: unstable · source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
const: unstable · source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
const: unstable · source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.