Trait Regex 

pub trait Regex<I, const N: usize>: Debug
where
    I: HaystackItem,
{
    type Pattern: Matcher<I>;
    type Capture<'a, S: HaystackSlice<'a>>: CaptureFromRanges<'a, S, N>
       where I: 'a;

    // Provided methods
    fn is_match<'a, H>(hay: impl IntoHaystack<'a, H>) -> bool
       where H: HaystackOf<'a, I> { ... }
    fn contains_match<'a, H>(hay: impl IntoHaystack<'a, H>) -> bool
       where H: HaystackOf<'a, I> { ... }
    fn count_matches<'a, H>(
        hay: impl IntoHaystack<'a, H>,
        overlapping: bool,
    ) -> usize
       where H: HaystackOf<'a, I> { ... }
    fn range_of_match<'a, H>(
        hay: impl IntoHaystack<'a, H>,
    ) -> Option<Range<usize>>
       where H: HaystackOf<'a, I> { ... }
    fn range_of_all_matches<'a, H>(
        hay: impl IntoHaystack<'a, H>,
        overlapping: bool,
    ) -> RangeOfAllMatches<'a, I, H, Self::Pattern> 
       where H: HaystackOf<'a, I> { ... }
    fn slice_match<'a, H>(
        hay: impl IntoHaystack<'a, H>,
    ) -> Option<<H as HaystackIter<'a>>::Slice>
       where H: HaystackOf<'a, I> { ... }
    fn slice_all_matches<'a, H>(
        hay: impl IntoHaystack<'a, H>,
        overlapping: bool,
    ) -> SliceAllMatches<'a, I, H, Self::Pattern> 
       where H: HaystackOf<'a, I> { ... }
    fn do_capture<'a, H>(
        hay: impl IntoHaystack<'a, H>,
    ) -> Option<Self::Capture<'a, <H as HaystackIter<'a>>::Slice>>
       where H: HaystackOf<'a, I> { ... }
    fn find_capture<'a, H>(
        hay: impl IntoHaystack<'a, H>,
    ) -> Option<Self::Capture<'a, <H as HaystackIter<'a>>::Slice>>
       where H: HaystackOf<'a, I> { ... }
    fn find_all_captures<'a, H>(
        hay: impl IntoHaystack<'a, H>,
        overlapping: bool,
    ) -> FindAllCaptures<'a, Self, I, H, N> 
       where H: HaystackOf<'a, I> { ... }
    fn replace<'a, M>(
        hay_mut: &mut M,
        with: <<M as OwnedHaystackable<I>>::Hay<'a> as HaystackIter<'a>>::Slice,
    ) -> bool
       where M: OwnedHaystackable<I> { ... }
    fn replace_all<'a, M>(
        hay_mut: &mut M,
        with: <<M as OwnedHaystackable<I>>::Hay<'a> as HaystackIter<'a>>::Slice,
    ) -> usize
       where M: OwnedHaystackable<I> { ... }
    fn replace_all_using<M>(hay_mut: &mut M, using: impl FnMut() -> M) -> usize
       where M: OwnedHaystackable<I> { ... }
    fn replace_captured<M, F>(hay_mut: &mut M, replacer: F) -> bool
       where M: OwnedHaystackable<I>,
             F: for<'a> FnOnce(Self::Capture<'a, <<M as OwnedHaystackable<I>>::Hay<'a> as HaystackIter<'a>>::Slice>) -> M { ... }
    fn replace_all_captured<M, F>(hay_mut: &mut M, replacer: F) -> usize
       where M: OwnedHaystackable<I>,
             F: for<'a> FnMut(Self::Capture<'a, <<M as OwnedHaystackable<I>>::Hay<'a> as HaystackIter<'a>>::Slice>) -> M { ... }
}

A trait that is automatically implemented for types produced by the regex! macro. Various function are included that test this pattern against a provided Haystack.

Most methods will take an IntoHaystack or OwnedHaystackable parameter to save the user from creating their own Haystack. This allows values with types like &str and &mut String to be passed to these methods.

Altough rarely encountered, this trait’s generic parameter, I refers to the item that can be matched individually from the provided Haystack. This is used so that the same expression can be used to match various haystack types, including &str (I = char) and &[u8] (I = u8). Implementations for both of these slice/item pairs will be implemented by the macro.

Function Coverage

Description	Whole	First*	All
Checks for a match	is_match	contains_match	count_matches
Returns range of match	-	range_of_match	range_of_all_matches
Returns match as a slice	-	slice_match	slice_all_matches
Performs capturing using groups	do_capture	find_capture	find_all_captures
Replaces match with value	-	replace	replace_all, _using
Replaces match by transforming capture	-	replace_captured	replace_all_captured

* Note that these function runs through the Regex first and then the haystack. This means that substring involved is the one that matches the Regex first, not necessarily the first match in the haystack. In many cases, this makes no difference.

Required Associated Types

type Pattern: Matcher<I>

This type is a macro generated combination of ZSTs responsible for doing all of the heavy lifting involved in actually matching or capturing against a Haystack. For realistic expressions, this type will be very long an unpleasant to type, hence implementing it as an associated type.

type Capture<'a, S: HaystackSlice<'a>>: CaptureFromRanges<'a, S, N> where I: 'a

A macro generated type holding all N capture groups in this expression, producing ranges or slices of the haystack with aliases for named groups. The generated type also understands which groups will always exist in a match and which are optional.

Provided Methods

fn is_match<'a, H>(hay: impl IntoHaystack<'a, H>) -> bool

where H: HaystackOf<'a, I>,

Returns true if this Regex matches the entire haystack provided. This should probably be the default matching function to use.

A similar behavior can be achieved by using start and end anchors in an expression and then calling contains_match. This function should be prefered however, because it fails fast if the first character doesn’t match.

To check if this Regex matches and perform capturing, use do_capture instead.

fn contains_match<'a, H>(hay: impl IntoHaystack<'a, H>) -> bool

where H: HaystackOf<'a, I>,

Returns true if this Regex matches any substring of the haystack provided. To retrieve the actual substring itself, use slice_match or find_capture.

Anchors can be used as a part of this Regex to perform more complex behaviors, but if you’re just wrapping an expression with ^ and $, see is_match instead.

fn count_matches<'a, H>( hay: impl IntoHaystack<'a, H>, overlapping: bool, ) -> usize

where H: HaystackOf<'a, I>,

Returns the number of matches present in the haystack provided, optionally including overlapping matches.

If using this in conjunction with the actual matches themselves, you might be better of collecting the other output and checking the length.

fn range_of_match<'a, H>(hay: impl IntoHaystack<'a, H>) -> Option<Range<usize>>

where H: HaystackOf<'a, I>,

Returns the range that matches this Regex first. This is the range variant of contains_match. For the actual substring itself, see slice_match.

Note that there is no range equivalent of is_match, because any match has to be the entire haystack.

fn range_of_all_matches<'a, H>( hay: impl IntoHaystack<'a, H>, overlapping: bool, ) -> RangeOfAllMatches<'a, I, H, Self::Pattern>

where H: HaystackOf<'a, I>,

Returns an iterator over the ranges of all substrings in the provided haystack that match this Regex, optionally overlapping. For the actual substrins themself, see slice_all_matches.

Note that each match is still made greedily. Even with overlapping = true, if two possible matches start at the same index in the haystack, only the first to match the regex will be included.

fn slice_match<'a, H>( hay: impl IntoHaystack<'a, H>, ) -> Option<<H as HaystackIter<'a>>::Slice>

where H: HaystackOf<'a, I>,

Returns the slice that matches this Regex first. This is the slicing variant of range_of_match.

Note that there is no slicing equivalent of is_match, because any match has to be the entire haystack.

fn slice_all_matches<'a, H>( hay: impl IntoHaystack<'a, H>, overlapping: bool, ) -> SliceAllMatches<'a, I, H, Self::Pattern>

where H: HaystackOf<'a, I>,

Returns an iterator over all slices of the provided haystack that match this Regex, optionally overlapping.

Note that each match is still made greedily. Even with overlapping = true, if two possible matches start at the same index in the haystack, only the first to match the regex will be included.

The returned iterator doesn’t implement ExactSizeIterator because it is lazy, if you need to know how many matches are included, collect it first.

fn do_capture<'a, H>( hay: impl IntoHaystack<'a, H>, ) -> Option<Self::Capture<'a, <H as HaystackIter<'a>>::Slice>>

where H: HaystackOf<'a, I>,

Returns a Self::Capture representing the provided haystack matched against this Regex. This includes any named or numbered capturing groups in the expression. As with is_match, this function acts on the entire haystack, and needs to match every character from start to end.

Provides the same result as find_capture with start and end anchors, although without needing to check any non-starting substring.

fn find_capture<'a, H>( hay: impl IntoHaystack<'a, H>, ) -> Option<Self::Capture<'a, <H as HaystackIter<'a>>::Slice>>

where H: HaystackOf<'a, I>,

Returns the Self::Capture that matches this Regex first, similar to slice_match but with any named or numbered groups included.

Anchors should be used for complex behavior, beyond unconditional start and end matches. See do_capture instead to capture a full haystack.

fn find_all_captures<'a, H>( hay: impl IntoHaystack<'a, H>, overlapping: bool, ) -> FindAllCaptures<'a, Self, I, H, N>

where H: HaystackOf<'a, I>,

Returns an iterator over Self::Captures representing every full match of this Regex in the provided haystack, similar to slice_all_matches. This can optionally include overlapping matches.

Note that each match is still made greedily. Even with overlapping = true, if two possible matches start at the same index in the haystack, only the first to match the regex will be included.

fn replace<'a, M>( hay_mut: &mut M, with: <<M as OwnedHaystackable<I>>::Hay<'a> as HaystackIter<'a>>::Slice, ) -> bool

where M: OwnedHaystackable<I>,

Replaces the first match of this Regex in the provided haystack with the provided slice. The slice type required is the one associated with the provided haystack. The return value is a boolean indicating whether a match was found and replaced.

fn replace_all<'a, M>( hay_mut: &mut M, with: <<M as OwnedHaystackable<I>>::Hay<'a> as HaystackIter<'a>>::Slice, ) -> usize

where M: OwnedHaystackable<I>,

Replaces every matching substring in the provided haystack with a copy of the provided slice. The slice type required is the one associated with the provided haystack. The return value is an integer representing the number of matches and replacements that occured.

fn replace_all_using<M>(hay_mut: &mut M, using: impl FnMut() -> M) -> usize

where M: OwnedHaystackable<I>,

Replaces every matching substring in the provided haystack with the return value of the provided function. The return type of this functions needs to match the provided haystack. The return value is an integer representing the number of matches and replacements that occured.

Because of the use of FnMut for the parameter, this can be used to replace all matches using an iterator by passing in || iter.next().unwrap_or_default().

fn replace_captured<M, F>(hay_mut: &mut M, replacer: F) -> bool

where M: OwnedHaystackable<I>, F: for<'a> FnOnce(Self::Capture<'a, <<M as OwnedHaystackable<I>>::Hay<'a> as HaystackIter<'a>>::Slice>) -> M,

Replaces the first captured substring in the provided haystack with a computed value. The return value is a boolean indicating whether a match was found and replaced.

The provided function is used to create a replacement value when given the capture. The replacement value shares a type with the provided haystack. Its simplified signature would be F: FnOnce(Self::Capture<'_, <M::Hay>::Slice>) -> M. Because of limitations with higher ranked trait bounds surrounding closure, it may be necessary to implement this as function with lifetime annotations like so:

regex!(PhoneNum = r"(0|(?<country_code>\+[0-9]+))(?<number>[0-9]{9})");

fn remove_country_code<'a>(value: PhoneNumCapture<'a, &'a str>) -> String {
    format!("0{}", value.number())
}

fn main() {
    let mut hay = String::from("+1234567890");
    PhoneNum::replace_captured(hay, remove_country_code);
    assert_eq!(hay, "0234567890");
}

fn replace_all_captured<M, F>(hay_mut: &mut M, replacer: F) -> usize

where M: OwnedHaystackable<I>, F: for<'a> FnMut(Self::Capture<'a, <<M as OwnedHaystackable<I>>::Hay<'a> as HaystackIter<'a>>::Slice>) -> M,

Replaces all captured substring in the provided haystack with a computed value. The return value is an integer indicating the number of matches found and replaced.

The provided function is used to create a replacement value when given a capture. The replacement value shares a type with the provided haystack. Its simplified signature would be F: FnMut(Self::Capture<'_, <M::Hay>::Slice>) -> M. Because of limitations with higher ranked trait bounds surrounding closure, it may be necessary to implement this as function with lifetime annotations as mentioned in the documentation for replace_captured.

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 Regex<char, 5> for Email

Available on crate feature demo only.

type Pattern = Then<char, CaptureGroup<char, QuantifierNOrMore<char, Or4<char, ScalarRange<'0', '9'>, ScalarRange<'A', 'Z'>, Scalar<'_'>, ScalarRange<'a', 'z'>>, 1>, 1>, Then<char, Scalar<'@'>, CaptureGroup<char, Then<char, CaptureGroup<char, QuantifierNOrMore<char, Or4<char, ScalarRange<'0', '9'>, ScalarRange<'A', 'Z'>, Scalar<'_'>, ScalarRange<'a', 'z'>>, 1>, 3>, QuantifierNToM<char, CaptureGroup<char, Then<char, Scalar<'.'>, QuantifierNOrMore<char, Or4<char, ScalarRange<'0', '9'>, ScalarRange<'A', 'Z'>, Scalar<'_'>, ScalarRange<'a', 'z'>>, 1>>, 4>, 0, 1>>, 2>>>

type Capture<'a, S: HaystackSlice<'a>> = EmailCapture<'a, S>

impl Regex<u8, 5> for Email

Available on crate feature demo only.

type Pattern = Then<u8, CaptureGroup<u8, QuantifierNOrMore<u8, Or4<u8, ByteRange<48, 57>, ByteRange<65, 90>, Byte<95>, ByteRange<97, 122>>, 1>, 1>, Then<u8, Byte<64>, CaptureGroup<u8, Then<u8, CaptureGroup<u8, QuantifierNOrMore<u8, Or4<u8, ByteRange<48, 57>, ByteRange<65, 90>, Byte<95>, ByteRange<97, 122>>, 1>, 3>, QuantifierNToM<u8, CaptureGroup<u8, Then<u8, Byte<46>, QuantifierNOrMore<u8, Or4<u8, ByteRange<48, 57>, ByteRange<65, 90>, Byte<95>, ByteRange<97, 122>>, 1>>, 4>, 0, 1>>, 2>>>

type Capture<'a, S: HaystackSlice<'a>> = EmailCapture<'a, S>