Cow (Clone-on-Write)

Cow<'a, T> is either borrowed &'a T or owned T - clones on write when mutation required.

Recipe

use std::borrow::Cow;
 
fn maybe_upper(s: Cow<str>) -> Cow<str> {
    if s.contains("urgent") {
        Cow::Owned(s.to_uppercase())
    } else {
        s
    }
}

When to reach for this: APIs accepting &str or String and sometimes needing owned mutation.

Working Example

use std::borrow::Cow;
 
fn append_suffix<'a>(s: Cow<'a, str>, suffix: &str) -> Cow<'a, str> {
    if suffix.is_empty() { return s; }
    let mut owned = s.into_owned();
    owned.push_str(suffix);
    Cow::Owned(owned)
}
 
fn main() {
    let borrowed = Cow::Borrowed("hello");
    let owned = append_suffix(borrowed, "!");
    println!("{owned}");
}

What this demonstrates:

• into_owned converts borrow to owned copy if needed
• Mutation triggers allocation only when necessary
• Return Cow avoids forcing caller to allocate

Deep Dive

Cow<str>, Cow<[u8]>, Cow<OsStr> common. Implements Deref to target.

Gotchas

• into_owned clones borrowed - Cost on first mutation. Fix: Accept cost or use String upfront.
• Lifetime tied to borrow - Returned Cow may need 'static owned branch.
• Overuse Cow - Complexity vs String/&str overloads. Fix: impl AsRef<str> simpler sometimes.
• Cow in struct - Lifetime on struct. Fix: Owned String in stored structs often.
• serde Cow - Deserializes to owned usually.

Alternatives

FAQs

Related

• Strings Basics
• Box<T>
• Ownership Best Practices
• Common Standard Traits

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.