Struct regex::bytes::Match

source ·
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>

source

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.

source

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.

source

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)?.

source

pub fn len(&self) -> usize

Returns the length, in bytes, of this match.

source

pub fn range(&self) -> Range<usize>

Returns the range over the starting and ending byte offsets of the match in the haystack.

source

pub fn as_bytes(&self) -> &'h [u8]

Returns the substring of the haystack that matched.

Trait Implementations§

source§

impl<'h> Clone for Match<'h>

source§

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

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl<'h> Debug for Match<'h>

source§

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

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

impl<'h> From<Match<'h>> for &'h [u8]

source§

fn from(m: Match<'h>) -> &'h [u8]

Converts to this type from the input type.
source§

impl<'h> From<Match<'h>> for Range<usize>

source§

fn from(m: Match<'h>) -> Range<usize>

Converts to this type from the input type.
source§

impl<'h> PartialEq for Match<'h>

source§

fn eq(&self, other: &Match<'h>) -> bool

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl<'h> Copy for Match<'h>

source§

impl<'h> Eq for Match<'h>

source§

impl<'h> StructuralEq for Match<'h>

source§

impl<'h> StructuralPartialEq for Match<'h>

Auto Trait Implementations§

§

impl<'h> RefUnwindSafe for Match<'h>

§

impl<'h> Send for Match<'h>

§

impl<'h> Sync for Match<'h>

§

impl<'h> Unpin for Match<'h>

§

impl<'h> UnwindSafe for Match<'h>

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,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

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

source§

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

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

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

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> ToOwned for Twhere T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

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

§

type Error = Infallible

The type returned in the event of a conversion error.
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.
source§

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

Performs the conversion.