Trait grep_matcher::Captures
source · 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> { ... }
}
Expand description
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§
sourcefn len(&self) -> usize
fn len(&self) -> usize
Return the total number of capturing groups. This includes capturing groups that have not matched anything.
sourcefn get(&self, i: usize) -> Option<Match>
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§
sourcefn is_empty(&self) -> bool
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.
sourcefn interpolate<F>(
&self,
name_to_index: F,
haystack: &[u8],
replacement: &[u8],
dst: &mut Vec<u8>
)where
F: FnMut(&str) -> Option<usize>,
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.