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()
}

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.

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>,