Trait CowUtils

pub trait CowUtils<'s> {
    type Output;

    // Required methods
    fn cow_replace(self, pattern: impl Pattern<'s>, to: &str) -> Self::Output;
    fn cow_replacen(
        self,
        from: impl Pattern<'s>,
        to: &str,
        count: usize,
    ) -> Self::Output;
    fn cow_to_ascii_lowercase(self) -> Self::Output;
    fn cow_to_lowercase(self) -> Self::Output;
    fn cow_to_ascii_uppercase(self) -> Self::Output;
    fn cow_to_uppercase(self) -> Self::Output;
}

Some str methods perform destructive transformations and so return String even when no modification is necessary.

This helper trait provides drop-in variants of such methods, but instead avoids allocations when no modification is necessary.

For now only implemented for &str and returns Cow<str>, but in the future might be extended to other types.

Required Associated Types

type Output

Required Methods

fn cow_replace(self, pattern: impl Pattern<'s>, to: &str) -> Self::Output

Replaces all matches of a pattern with another string.

fn cow_replacen( self, from: impl Pattern<'s>, to: &str, count: usize, ) -> Self::Output

Replaces first N matches of a pattern with another string.

fn cow_to_ascii_lowercase(self) -> Self::Output

Returns a copy of this string where each character is mapped to its ASCII lower case equivalent.

fn cow_to_lowercase(self) -> Self::Output

Returns the lowercase equivalent of this string slice.

fn cow_to_ascii_uppercase(self) -> Self::Output

Returns a copy of this string where each character is mapped to its ASCII upper case equivalent.

fn cow_to_uppercase(self) -> Self::Output

Returns the uppercase equivalent of this string slice.

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<'s> CowUtils<'s> for &'s str

fn cow_replace(self, pattern: impl Pattern<'s>, to: &str) -> Self::Output

This is similar to str::replace, but returns a slice of the original string when possible:

assert_matches!("abc".cow_replace("def", "ghi"), Cow::Borrowed("abc"));
assert_matches!("$$str$$".cow_replace("$", ""), Cow::Borrowed("str"));
assert_matches!("aaaaa".cow_replace("a", ""), Cow::Borrowed(""));
assert_matches!("abc".cow_replace("b", "d"), Cow::Owned(s) if s == "adc");
assert_matches!("$a$b$".cow_replace("$", ""), Cow::Owned(s) if s == "ab");

fn cow_replacen( self, pattern: impl Pattern<'s>, to: &str, count: usize, ) -> Self::Output

This is similar to str::replacen, but returns a slice of the original string when possible:

assert_matches!("abc".cow_replacen("def", "ghi", 10), Cow::Borrowed("abc"));
assert_matches!("$$str$$".cow_replacen("$", "", 2), Cow::Borrowed("str$$"));
assert_matches!("$a$b$".cow_replacen("$", "", 1), Cow::Borrowed("a$b$"));
assert_matches!("aaaaa".cow_replacen("a", "", 10), Cow::Borrowed(""));
assert_matches!("aaaaa".cow_replacen("a", "b", 0), Cow::Borrowed("aaaaa"));
assert_matches!("abc".cow_replacen("b", "d", 1), Cow::Owned(s) if s == "adc");

fn cow_to_ascii_lowercase(self) -> Self::Output

This is similar to str::to_ascii_lowercase, but returns original slice when possible:

assert_matches!("abcd123".cow_to_ascii_lowercase(), Cow::Borrowed("abcd123"));
assert_matches!("ὀδυσσεύς".cow_to_ascii_lowercase(), Cow::Borrowed("ὀδυσσεύς"));
assert_matches!("ὈΔΥΣΣΕΎΣ".cow_to_ascii_lowercase(), Cow::Borrowed("ὈΔΥΣΣΕΎΣ"));
assert_matches!("AbCd".cow_to_ascii_lowercase(), Cow::Owned(s) if s == "abcd");

fn cow_to_lowercase(self) -> Self::Output

This is similar to str::to_lowercase, but returns original slice when possible:

assert_matches!("abcd123".cow_to_lowercase(), Cow::Borrowed("abcd123"));
assert_matches!("ὀδυσσεύς".cow_to_lowercase(), Cow::Borrowed("ὀδυσσεύς"));
assert_matches!("ὈΔΥΣΣΕΎΣ".cow_to_lowercase(), Cow::Owned(s) if s == "ὀδυσσεύς");
assert_matches!("AbCd".cow_to_lowercase(), Cow::Owned(s) if s == "abcd");
assert_matches!("ᾈ".cow_to_lowercase(), Cow::Owned(s) if s == "ᾀ");

fn cow_to_ascii_uppercase(self) -> Self::Output

This is similar to str::to_ascii_uppercase, but returns original slice when possible:

assert_matches!("ABCD123".cow_to_ascii_uppercase(), Cow::Borrowed("ABCD123"));
assert_matches!("ὈΔΥΣΣΕΎΣ".cow_to_ascii_uppercase(), Cow::Borrowed("ὈΔΥΣΣΕΎΣ"));
assert_matches!("ὀδυσσεύς".cow_to_ascii_uppercase(), Cow::Borrowed("ὀδυσσεύς"));
assert_matches!("AbCd".cow_to_ascii_uppercase(), Cow::Owned(s) if s == "ABCD");

fn cow_to_uppercase(self) -> Self::Output

This is similar to str::to_uppercase, but returns original slice when possible:

assert_matches!("ABCD123".cow_to_uppercase(), Cow::Borrowed("ABCD123"));
assert_matches!("ὈΔΥΣΣΕΎΣ".cow_to_uppercase(), Cow::Borrowed("ὈΔΥΣΣΕΎΣ"));
assert_matches!("ὀδυσσεύς".cow_to_uppercase(), Cow::Owned(s) if s == "ὈΔΥΣΣΕΎΣ");
assert_matches!("AbCd".cow_to_uppercase(), Cow::Owned(s) if s == "ABCD");
assert_matches!("ᾈ".cow_to_uppercase(), Cow::Owned(s) if s == "ἈΙ");

type Output = Cow<'s, str>

Implementors