Trait Replacer

pub trait Replacer {
    // Required method
    fn replace_append(&mut self, caps: &Captures<'_>, dst: &mut String);

    // Provided methods
    fn no_expansion<'r>(&'r mut self) -> Option<Cow<'r, str>> { ... }
    fn by_ref<'r>(&'r mut self) -> ReplacerRef<'r, Self> { ... }
}

A trait for types that can be used to replace matches in a haystack.

In general, users of this crate shouldn’t need to implement this trait, since implementations are already provided for &str along with other variants of string types, as well as FnMut(&Captures) -> String (or any FnMut(&Captures) -> T where T: AsRef<str>). Those cover most use cases, but callers can implement this trait directly if necessary.

Example

This example shows a basic implementation of the Replacer trait. This can be done much more simply using the replacement string interpolation support (e.g., $first $last), but this approach avoids needing to parse the replacement string at all.

use regex::{Captures, Regex, Replacer};

struct NameSwapper;

impl Replacer for NameSwapper {
    fn replace_append(&mut self, caps: &Captures<'_>, dst: &mut String) {
        dst.push_str(&caps["first"]);
        dst.push_str(" ");
        dst.push_str(&caps["last"]);
    }
}

let re = Regex::new(r"(?<last>[^,\s]+),\s+(?<first>\S+)").unwrap();
let result = re.replace("Springsteen, Bruce", NameSwapper);
assert_eq!(result, "Bruce Springsteen");

Required Methods

fn replace_append(&mut self, caps: &Captures<'_>, dst: &mut String)

Appends possibly empty data to dst to replace the current match.

The current match is represented by caps, which is guaranteed to have a match at capture group 0.

For example, a no-op replacement would be dst.push_str(&caps[0]).

Provided Methods

fn no_expansion<'r>(&'r mut self) -> Option<Cow<'r, str>>

Return a fixed unchanging replacement string.

When doing replacements, if access to Captures is not needed (e.g., the replacement string does not need $ expansion), then it can be beneficial to avoid finding sub-captures.

In general, this is called once for every call to a replacement routine such as Regex::replace_all.

fn by_ref<'r>(&'r mut self) -> ReplacerRef<'r, Self>

Returns a type that implements Replacer, but that borrows and wraps this Replacer.

This is useful when you want to take a generic Replacer (which might not be cloneable) and use it without consuming it, so it can be used more than once.

Example

use regex::{Regex, Replacer};

fn replace_all_twice<R: Replacer>(
    re: Regex,
    src: &str,
    mut rep: R,
) -> String {
    let dst = re.replace_all(src, rep.by_ref());
    let dst = re.replace_all(&dst, rep.by_ref());
    dst.into_owned()
}

Object Safety

This trait is not object safe.

Implementations on Foreign Types

impl Replacer for String

fn replace_append(&mut self, caps: &Captures<'_>, dst: &mut String)

fn no_expansion(&mut self) -> Option<Cow<'_, str>>

impl<'a> Replacer for &'a Cow<'a, str>

fn replace_append(&mut self, caps: &Captures<'_>, dst: &mut String)

fn no_expansion(&mut self) -> Option<Cow<'_, str>>

impl<'a> Replacer for &'a str

fn replace_append(&mut self, caps: &Captures<'_>, dst: &mut String)

fn no_expansion(&mut self) -> Option<Cow<'_, str>>

impl<'a> Replacer for &'a String

fn replace_append(&mut self, caps: &Captures<'_>, dst: &mut String)

fn no_expansion(&mut self) -> Option<Cow<'_, str>>

impl<'a> Replacer for Cow<'a, str>

fn replace_append(&mut self, caps: &Captures<'_>, dst: &mut String)

fn no_expansion(&mut self) -> Option<Cow<'_, str>>

Implementors

impl<'a, R> Replacer for ReplacerRef<'a, R>

where R: Replacer + 'a + ?Sized,

impl<'s> Replacer for NoExpand<'s>

impl<F, T> Replacer for F

where F: FnMut(&Captures<'_>) -> T, T: AsRef<str>,