Trait Captures

pub trait Captures {
    // Required methods
    fn len(&self) -> usize;
    fn get(&self, i: usize) -> Option<Match>;

    // Provided methods
    fn is_empty(&self) -> bool { ... }
    fn interpolate<F>(
        &self,
        name_to_index: F,
        haystack: &[u8],
        replacement: &[u8],
        dst: &mut Vec<u8>,
    )
       where F: FnMut(&str) -> Option<usize> { ... }
}

A trait that describes implementations of capturing groups.

When a matcher supports capturing group extraction, then it is the matcher’s responsibility to provide an implementation of this trait.

Principally, this trait provides a way to access capturing groups in a uniform way that does not require any specific representation. Namely, different matcher implementations may require different in-memory representations of capturing groups. This trait permits matchers to maintain their specific in-memory representation.

Note that this trait explicitly does not provide a way to construct a new capture value. Instead, it is the responsibility of a Matcher to build one, which might require knowledge of the matcher’s internal implementation details.

Required Methods

fn len(&self) -> usize

Return the total number of capturing groups. This includes capturing groups that have not matched anything.

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

Return the capturing group match at the given index. If no match of that capturing group exists, then this returns None.

When a matcher reports a match with capturing groups, then the first capturing group (at index 0) must always correspond to the offsets for the overall match.

Provided Methods

fn is_empty(&self) -> bool

Returns true if and only if these captures are empty. This occurs when len is 0.

Note that capturing groups that have non-zero length but otherwise contain no matching groups are not empty.

fn interpolate<F>( &self, name_to_index: F, haystack: &[u8], replacement: &[u8], dst: &mut Vec<u8>, )

where F: FnMut(&str) -> Option<usize>,

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

(Note: If you’re looking for a convenient way to perform replacements with interpolation, then you’ll want to use the replace_with_captures method on the Matcher trait.)

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.

A name is translated to a capture group index via the given name_to_index function. 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 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, use braces, e.g., ${1}a. In all cases, capture group names are limited to ASCII letters, numbers and underscores.

To write a literal $ use $$.

Note that the capture group match indices are resolved by slicing the given haystack. Generally, this means that haystack should be the same slice that was searched to get the current capture group matches.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl Captures for NoCaptures