pub struct Match<'h> { /* private fields */ }Expand description
Represents a single match of a regex in a haystack.
A Match contains both the start and end byte offsets of the match and the
actual substring corresponding to the range of those byte offsets. It is
guaranteed that start <= end. When start == end, the match is empty.
Unlike the top-level Match type, this Match type is produced by APIs
that search &[u8] haystacks. This means that the offsets in a Match can
point to anywhere in the haystack, including in a place that splits the
UTF-8 encoding of a Unicode scalar value.
The lifetime parameter 'h refers to the lifetime of the matched of the
haystack that this match was produced from.
Numbering
The byte offsets in a Match form a half-open interval. That is, the
start of the range is inclusive and the end of the range is exclusive.
For example, given a haystack abcFOOxyz and a match of FOO, its byte
offset range starts at 3 and ends at 6. 3 corresponds to F and
6 corresponds to x, which is one past the end of the match. This
corresponds to the same kind of slicing that Rust uses.
For more on why this was chosen over other schemes (aside from being consistent with how Rust the language works), see this discussion and Dijkstra’s note on a related topic.
Example
This example shows the value of each of the methods on Match for a
particular search.
use regex::bytes::Regex;
let re = Regex::new(r"\p{Greek}+").unwrap();
let hay = "Greek: αβγδ".as_bytes();
let m = re.find(hay).unwrap();
assert_eq!(7, m.start());
assert_eq!(15, m.end());
assert!(!m.is_empty());
assert_eq!(8, m.len());
assert_eq!(7..15, m.range());
assert_eq!("αβγδ".as_bytes(), m.as_bytes());Implementations§
source§impl<'h> Match<'h>
impl<'h> Match<'h>
sourcepub fn start(&self) -> usize
pub fn start(&self) -> usize
Returns the byte offset of the start of the match in the haystack. The start of the match corresponds to the position where the match begins and includes the first byte in the match.
It is guaranteed that Match::start() <= Match::end().
Unlike the top-level Match type, the start offset may appear anywhere
in the haystack. This includes between the code units of a UTF-8
encoded Unicode scalar value.
sourcepub fn end(&self) -> usize
pub fn end(&self) -> usize
Returns the byte offset of the end of the match in the haystack. The
end of the match corresponds to the byte immediately following the last
byte in the match. This means that &slice[start..end] works as one
would expect.
It is guaranteed that Match::start() <= Match::end().
Unlike the top-level Match type, the start offset may appear anywhere
in the haystack. This includes between the code units of a UTF-8
encoded Unicode scalar value.
sourcepub fn is_empty(&self) -> bool
pub fn is_empty(&self) -> bool
Returns true if and only if this match has a length of zero.
Note that an empty match can only occur when the regex itself can
match the empty string. Here are some examples of regexes that can
all match the empty string: ^, ^$, \b, a?, a*, a{0},
(foo|\d+|quux)?.