Clone-on-Write with `Cow<'_, T>`

18 min read

Cow (“clone on write”) is a smart pointer that holds either borrowed or owned data behind a single type, and only allocates a fresh copy at the exact moment you need to mutate or keep it. It is Rust’s idiomatic tool for functions that usually return their input unchanged but occasionally need to produce a modified version — letting you skip an allocation on the common path.

Quick Overview

Cow<'a, T> (in std::borrow) is an enum with two variants: Borrowed(&'a T) and Owned(<T as ToOwned>::Owned). For strings that means it wraps either a &str or a String; for slices, either a &[T] or a Vec<T>. Because it derefs to the borrowed form, you read through it like a plain reference, and you only pay for an allocation when you actually have to change the data.

For a TypeScript/JavaScript developer, the closest mental hook is a function that returns “the same string I was given, or a new one if I had to edit it” — except in JavaScript strings are immutable and copies are invisible, whereas Cow makes the borrow-versus-allocate decision explicit and free of charge on the hot path.

TypeScript/JavaScript Example

In JavaScript, strings are immutable, so “modify if needed” functions either return the original reference or build a brand-new string. The allocation is implicit and you have no way to express “I borrowed the caller’s data and changed nothing.”

1
// Normalize a URL to https, only producing a new string when we must change it.
2
function ensureHttps(url: string): string {
3
  if (url.startsWith("https://")) {
4
    return url; // returns the SAME reference — no copy
5
  }
6
  if (url.startsWith("http://")) {
7
    return "https://" + url.slice("http://".length); // brand-new string
8
  }
9
  return "https://" + url; // brand-new string
10
}
11

12
const already = ensureHttps("https://example.com"); // same reference back
13
const upgraded = ensureHttps("http://example.com"); // freshly allocated
14

15
console.log(already); // https://example.com
16
console.log(upgraded); // https://example.com
17

18
// In JS you cannot tell, from the outside, whether `already` is the original
19
// string or a copy — and you cannot prevent the engine from copying internally.

This pattern is everywhere: HTML escaping, input sanitizing, path normalization, config defaulting. In each case the typical input needs no change, but the type system gives you no way to say “borrowed, untouched” versus “owned, rebuilt.”

Rust Equivalent

Cow<'_, str> expresses exactly that distinction, and the compiler guarantees the borrow is valid:

1
use std::borrow::Cow;
2

3
fn ensure_https(url: &str) -> Cow<'_, str> {
4
    if url.starts_with("https://") {
5
        Cow::Borrowed(url) // no allocation: the input was already fine
6
    } else if let Some(rest) = url.strip_prefix("http://") {
7
        Cow::Owned(format!("https://{rest}")) // allocate only when we must change it
8
    } else {
9
        Cow::Owned(format!("https://{url}"))
10
    }
11
}
12

13
fn main() {
14
    let already = ensure_https("https://example.com");
15
    let upgraded = ensure_https("http://example.com");
16
    let bare = ensure_https("example.com");
17

18
    println!("{already}");
19
    println!("{upgraded}");
20
    println!("{bare}");
21

22
    // Inspect which variant we got:
23
    println!("already is borrowed: {}", matches!(already, Cow::Borrowed(_)));
24
    println!("upgraded is owned:   {}", matches!(upgraded, Cow::Owned(_)));
25
}

Output (verified with cargo run):

1
https://example.com
2
https://example.com
3
https://example.com
4
already is borrowed: true
5
upgraded is owned:   true

The already case returns a Cow::Borrowed pointing straight at the caller’s string slice — zero heap allocation. Only the http:// and bare-host cases build a new String.

Detailed Explanation

The shape of `Cow`

Cow is a plain enum in the standard library, roughly:

1
// From std::borrow (simplified)
2
pub enum Cow<'a, B>
3
where
4
    B: ToOwned + ?Sized,
5
{
6
    Borrowed(&'a B),
7
    Owned(<B as ToOwned>::Owned),
8
}

The B: ToOwned bound is what makes the two halves line up. ToOwned is the trait that knows how to turn a borrowed value into an owned one:

Borrowed form `B`	Owned form `<B as ToOwned>::Owned`
`str`	`String`
`[T]`	`Vec<T>`
`Path`	`PathBuf`
`CStr`	`CString`
any `T: Clone`	`T`

So Cow<'a, str> is “either a &'a str or a String,” and Cow<'a, [i32]> is “either a &'a [i32] or a Vec<i32>.” (The lifetime 'a only constrains the Borrowed variant; an Owned value has no borrow to track.)

Reading through `Cow` (`Deref`)

Cow<'_, B> implements Deref<Target = B>, so every read-only method of the borrowed type is available directly — you do not match on the variant just to call .len():

1
use std::borrow::Cow;
2

3
fn main() {
4
    let c: Cow<'_, str> = Cow::Borrowed("Hello, Cow");
5
    // All of these are &str methods, reached through Deref:
6
    println!("{}", c.len());
7
    println!("{}", c.to_uppercase());
8
    println!("{}", c.starts_with("Hello"));
9

10
    // Cow<'_, str> can be compared to &str directly:
11
    println!("{}", c == "Hello, Cow");
12

13
    // From conversions:
14
    let from_str: Cow<'_, str> = "literal".into();                // -> Borrowed
15
    let from_string: Cow<'_, str> = String::from("owned").into(); // -> Owned
16
    println!(
17
        "{} {}",
18
        matches!(from_str, Cow::Borrowed(_)),
19
        matches!(from_string, Cow::Owned(_))
20
    );
21
}

Output (verified):

1
10
2
HELLO, COW
3
true
4
true
5
true true

The Deref coercion here is the same machinery that makes &String work where &str is expected — covered in depth in deref-trait.md. Notice also the From impls: a &str becomes Cow::Borrowed, a String becomes Cow::Owned, so .into() does the right thing.

Writing through `Cow` (`to_mut` and `into_owned`)

The “clone on write” name comes from two methods:

to_mut(&mut self) -> &mut <B as ToOwned>::Owned — gives you a mutable handle to the owned form. If the Cow is currently Borrowed, it clones the data into an owned value first (that is the “write” that triggers the “clone”), switches the variant to Owned, and hands you &mut to it. If it was already Owned, no clone happens.
into_owned(self) -> <B as ToOwned>::Owned — unconditionally consumes the Cow and returns the owned value, cloning only if it was borrowed.

1
use std::borrow::Cow;
2

3
fn main() {
4
    // to_mut(): get a &mut to the owned data, cloning lazily on first call.
5
    let mut data: Cow<'_, str> = Cow::Borrowed("hello");
6
    println!("before: borrowed = {}", matches!(data, Cow::Borrowed(_)));
7
    data.to_mut().push_str(", world"); // clones "hello" into a String here
8
    println!("after:  borrowed = {}", matches!(data, Cow::Borrowed(_)));
9
    println!("value:  {data}");
10

11
    // into_owned(): unconditionally produce the owned type.
12
    let s: Cow<'_, str> = Cow::Borrowed("owned me");
13
    let owned: String = s.into_owned();
14
    println!("owned:  {owned}");
15
}

Output (verified):

1
before: borrowed = true
2
after:  borrowed = false
3
value:  hello, world
4
owned:  owned me

The push_str call works because to_mut() returns &mut String, and String does have push_str. Before that call, data was a Cow::Borrowed; after it, it is Cow::Owned — the clone happened exactly once, on first mutation.

Why this matters: the allocation you avoid

Imagine a sanitizer applied to every field of every request. If 99% of inputs are already clean, eagerly calling .to_string() allocates a String for every single one. Cow lets the clean path stay a borrow:

1
use std::borrow::Cow;
2

3
// Replace any control chars; only allocate if there is something to replace.
4
fn sanitize(input: &str) -> Cow<'_, str> {
5
    if input.chars().any(|c| c.is_control()) {
6
        // We must build a new String -> Owned variant.
7
        let cleaned: String = input.chars().filter(|c| !c.is_control()).collect();
8
        Cow::Owned(cleaned)
9
    } else {
10
        Cow::Borrowed(input) // hot path: clean input, zero allocation
11
    }
12
}
13

14
fn main() {
15
    let clean = sanitize("normal text");
16
    let dirty = sanitize("bad\u{7}text"); // contains a BEL control char
17

18
    println!("clean borrowed: {}", matches!(clean, Cow::Borrowed(_)));
19
    println!("dirty owned:    {}", matches!(dirty, Cow::Owned(_)));
20
    println!("dirty value:    {dirty:?}");
21
}

Output (verified):

1
clean borrowed: true
2
dirty owned:    true
3
dirty value:    "badtext"

Tip: The standard library uses this pattern in its own API. For example, str::from_utf8_lossy returns Cow<'_, str>: if the bytes are already valid UTF-8 it borrows them unchanged, and only allocates when it has to substitute the replacement character �.

Key Differences

`Cow` is not just for strings

Cow<'_, [T]> works for any slice whose element is Clone. The decision and the deref behavior are identical:

1
use std::borrow::Cow;
2

3
// Cow works for any [T] where T: Clone, not just str.
4
fn drop_negatives(nums: &[i32]) -> Cow<'_, [i32]> {
5
    if nums.iter().any(|&n| n < 0) {
6
        Cow::Owned(nums.iter().copied().filter(|&n| n >= 0).collect())
7
    } else {
8
        Cow::Borrowed(nums)
9
    }
10
}
11

12
fn main() {
13
    let already = drop_negatives(&[1, 2, 3]);
14
    let filtered = drop_negatives(&[1, -2, 3]);
15

16
    println!("already borrowed: {}", matches!(already, Cow::Borrowed(_)));
17
    println!("filtered owned:   {}", matches!(filtered, Cow::Owned(_)));
18
    println!("filtered: {filtered:?}");
19
    println!("len via deref: {}", filtered.len()); // read through Deref to &[i32]
20
}

Output (verified):

1
already borrowed: true
2
filtered owned:   true
3
filtered: [1, 3]
4
len via deref: 2

`Cow` versus the other smart pointers

Need	Reach for	Why not `Cow`
Heap-allocate one value, always owned	`Box<T>`	`Cow` is about avoiding the allocation when possible
Share ownership across many holders	`Rc<T>`/`Arc<T>`	`Cow` has a single logical owner; it does not refcount
Mutate shared data behind a shared reference	`RefCell`/`Mutex`, `Cell`	`Cow` mutation always produces a private owned copy
”Maybe borrow, maybe own — decide at runtime, allocate lazily”	`Cow<'_, T>`	—

Cow is the only one of these focused on deferring an allocation. The full decision matrix lives in comparison.md.

Mental model versus TypeScript

JavaScript strings: always immutable; “return original or new” is invisible to you, and the engine may copy freely. Cow makes the borrow/own choice a value you can inspect and a cost the compiler tracks.
TypeScript types are erased at runtime; a string is just a string. Rust monomorphizes Cow<'a, str> into a concrete two-variant enum with a discriminant, so “is this borrowed or owned?” is a real, checkable runtime fact (matches!(x, Cow::Borrowed(_))).
Unlike JavaScript’s structural typing, the lifetime 'a ties a Cow::Borrowed to the data it points at. You cannot return a Cow that borrows something the function is about to drop (see Pitfalls).

Common Pitfalls

Pitfall 1: borrowing a local into `Cow::Borrowed`

A natural mistake is to build an owned value, then wrap a reference to it in Cow::Borrowed. The local is dropped at the end of the function, so the borrow would dangle — Rust rejects it.

1
use std::borrow::Cow;
2

3
fn shout(input: &str) -> Cow<'_, str> {
4
    let upper = input.to_uppercase(); // local String
5
    Cow::Borrowed(&upper)             // does not compile (error[E0515])
6
}

Real compiler output (cargo build):

1
error[E0515]: cannot return value referencing local variable `upper`
2
 --> src/main.rs:5:5
3
  |
4
5 |     Cow::Borrowed(&upper)             // does not compile (error[E0515])
5
  |     ^^^^^^^^^^^^^^------^
6
  |     |             |
7
  |     |             `upper` is borrowed here
8
  |     returns a value referencing data owned by the current function

Fix: if you built a new value, it is owned, so use Cow::Owned(upper) (move the String in, no &). Use Cow::Borrowed only for data the caller owns (the &str parameter) or 'static literals.

Pitfall 2: trying to mutate a `Cow` directly

Cow<'_, str> derefs to &str, which is immutable, so methods like push_str are not in scope on the Cow itself.

1
use std::borrow::Cow;
2

3
fn main() {
4
    let mut data: Cow<'_, str> = Cow::Borrowed("hello");
5
    data.push_str("!"); // does not compile (error[E0599])
6
    println!("{data}");
7
}

Real compiler output (cargo build):

1
error[E0599]: no method named `push_str` found for enum `Cow<'_, str>` in the current scope
2
 --> src/main.rs:5:10
3
  |
4
5 |     data.push_str("!"); // does not compile (error[E0599])
5
  |          ^^^^^^^^ method not found in `Cow<'_, str>`

Fix: go through to_mut() to get the underlying &mut String: data.to_mut().push_str("!"). That is the “write” that triggers the lazy clone.

Pitfall 3: using `Cow` when you always allocate anyway

If every code path produces an owned value, Cow buys you nothing but ceremony — just return String. Cow pays off only when at least one common path can stay borrowed.

1
// Anti-pattern: both arms are Owned, so Cow adds no value.
2
// fn f(s: &str) -> Cow<'_, str> { Cow::Owned(s.to_uppercase()) }
3
// Prefer:
4
fn f(s: &str) -> String {
5
    s.to_uppercase()
6
}
7

8
fn main() {
9
    println!("{}", f("hi"));
10
}

Pitfall 4: assuming `Cow::Owned` from a `String` is free to compare

Comparisons and most reads work via Deref, so they are fine — but remember that putting a Cow into a struct adds a lifetime parameter to that struct when the Borrowed variant can occur. That can ripple through your API (see Best Practices).

Best Practices

Return Cow<'a, str> (or Cow<'a, [T]>) from “transform-if-needed” functions — escapers, sanitizers, normalizers, defaulters. This is the canonical, idiomatic use.
Prefer strip_prefix/trim/slicing in the borrowed arm. These return sub-slices of the input, which stay Cow::Borrowed — no allocation. Reach for format!/replace/collect only in the owned arm.
Use into_owned() at the boundary where you need to store the value past the borrow’s lifetime (e.g. before putting it in a long-lived struct without a lifetime parameter, or sending it across threads). into_owned is cheaper than to_string() when the value is already Owned.
Let .into() pick the variant. let c: Cow<str> = some_string.into(); becomes Owned; let c: Cow<str> = "x".into(); becomes Borrowed. This reads cleanly when the source type already makes the choice obvious.
Be deliberate about adding a lifetime to a struct. A field of type Cow<'a, str> forces struct Config<'a>. If most instances are built at runtime and stored long-term, a plain String field may be simpler; use Cow in the field when you genuinely want to hold borrowed literals without copying.
Run Clippy. It flags some redundant allocations and can suggest Cow patterns; the examples in this file are Clippy-clean on stable 1.96.0.

Note: Cow deliberately favors correctness and zero-copy on the common path over micro-optimizing the rare path. The owned arm still allocates exactly as a hand-written String would — you have simply moved that cost off the hot path.

Real-World Example

A small templating layer that HTML-escapes interpolated values. The vast majority of values are plain text needing no escaping, so we keep those borrowed and only allocate for values that contain <, >, &, or ".

1
use std::borrow::Cow;
2
use std::collections::HashMap;
3

4
/// Escape the HTML-significant characters in `input`.
5
/// Returns a borrow when nothing needs escaping (the common case for plain text),
6
/// and only allocates a new String when an unsafe character is present.
7
fn escape_html(input: &str) -> Cow<'_, str> {
8
    // Fast scan: is there anything to escape at all?
9
    if !input.bytes().any(|b| matches!(b, b'<' | b'>' | b'&' | b'"')) {
10
        return Cow::Borrowed(input);
11
    }
12

13
    let mut escaped = String::with_capacity(input.len() + 16);
14
    for ch in input.chars() {
15
        match ch {
16
            '<' => escaped.push_str("&lt;"),
17
            '>' => escaped.push_str("&gt;"),
18
            '&' => escaped.push_str("&amp;"),
19
            '"' => escaped.push_str("&quot;"),
20
            other => escaped.push(other),
21
        }
22
    }
23
    Cow::Owned(escaped)
24
}
25

26
/// Render a tiny template row, escaping each interpolated value.
27
fn render_row(fields: &HashMap<&str, &str>) -> String {
28
    let name = escape_html(fields.get("name").copied().unwrap_or(""));
29
    let bio = escape_html(fields.get("bio").copied().unwrap_or(""));
30
    // `name` / `bio` are Cow<str>; they Deref to &str inside format!.
31
    format!("<tr><td>{name}</td><td>{bio}</td></tr>")
32
}
33

34
fn main() {
35
    let mut row = HashMap::new();
36
    row.insert("name", "Ada Lovelace"); // safe -> borrowed, no allocation
37
    row.insert("bio", "Wrote the first <algorithm> & more"); // unsafe -> owned
38
    println!("{}", render_row(&row));
39

40
    // Confirm the allocation decision:
41
    let safe = escape_html("plain");
42
    let unsafe_ = escape_html("a & b");
43
    println!("safe borrowed:  {}", matches!(safe, Cow::Borrowed(_)));
44
    println!("unsafe owned:   {}", matches!(unsafe_, Cow::Owned(_)));
45
}

Output (verified with cargo run, and cargo clippy clean):

1
<tr><td>Ada Lovelace</td><td>Wrote the first &lt;algorithm&gt; &amp; more</td></tr>
2
safe borrowed:  true
3
unsafe owned:   true

In a request handler processing thousands of fields per second, the Cow::Borrowed fast path means the overwhelmingly common “no escaping needed” case touches the heap zero times — exactly the kind of needless-allocation savings Cow exists to provide.

Tip: Holding the result as a Cow also lets the caller decide whether to keep it borrowed (cheap) or call .into_owned() to detach it. You preserve the choice instead of forcing an allocation on everyone.

Exercises

Exercise 1: Trim only when needed

Difficulty: Beginner

Objective: Write a function that trims surrounding whitespace but stays Cow::Borrowed even when it does trim — proving that sub-slicing does not allocate.

Instructions: Implement trim_if_needed(input: &str) -> Cow<'_, str>. If the trimmed string equals the input length, return the input untouched; otherwise return the trimmed sub-slice. Both arms should be Cow::Borrowed. Verify with inputs "clean" and " spaced ".

1
use std::borrow::Cow;
2

3
fn trim_if_needed(input: &str) -> Cow<'_, str> {
4
    // TODO: return Cow::Borrowed in both cases (hint: trim() returns a sub-slice)
5
    todo!()
6
}
7

8
fn main() {
9
    let a = trim_if_needed("clean");
10
    let b = trim_if_needed("  spaced  ");
11
    println!("{a:?} borrowed={}", matches!(a, Cow::Borrowed(_)));
12
    println!("{b:?} borrowed={}", matches!(b, Cow::Borrowed(_)));
13
}

Solution

1
use std::borrow::Cow;
2

3
fn trim_if_needed(input: &str) -> Cow<'_, str> {
4
    let trimmed = input.trim();
5
    if trimmed.len() == input.len() {
6
        Cow::Borrowed(input)
7
    } else {
8
        Cow::Borrowed(trimmed) // still a borrow! trim returns a sub-slice of input
9
    }
10
}
11

12
fn main() {
13
    let a = trim_if_needed("clean");
14
    let b = trim_if_needed("  spaced  ");
15
    println!("{a:?} borrowed={}", matches!(a, Cow::Borrowed(_)));
16
    println!("{b:?} borrowed={}", matches!(b, Cow::Borrowed(_)));
17
}

Output:

1
"clean" borrowed=true
2
"spaced" borrowed=true

The key insight: trim() returns a slice into the original string, so no allocation occurs even when characters are removed. Cow carries the same lifetime, so the borrow stays valid.

Exercise 2: Normalize line endings

Difficulty: Intermediate

Objective: Avoid allocating for text that is already in Unix line-ending form.

Instructions: Implement normalize_newlines(text: &str) -> Cow<'_, str> that converts \r\n and lone \r to \n. If the text contains no \r, return it borrowed; otherwise build the normalized String and return it owned. Verify with "a\nb\nc" (borrowed) and "a\r\nb\r\nc" (owned).

1
use std::borrow::Cow;
2

3
fn normalize_newlines(text: &str) -> Cow<'_, str> {
4
    // TODO: borrow if there is no '\r'; otherwise replace and own
5
    todo!()
6
}
7

8
fn main() {
9
    let unix = normalize_newlines("a\nb\nc");
10
    let win = normalize_newlines("a\r\nb\r\nc");
11
    println!("unix borrowed: {}", matches!(unix, Cow::Borrowed(_)));
12
    println!("win owned:     {}", matches!(win, Cow::Owned(_)));
13
    println!("win value:     {win:?}");
14
}

Solution

1
use std::borrow::Cow;
2

3
fn normalize_newlines(text: &str) -> Cow<'_, str> {
4
    if text.contains('\r') {
5
        // Replace CRLF first, then any remaining lone CR.
6
        Cow::Owned(text.replace("\r\n", "\n").replace('\r', "\n"))
7
    } else {
8
        Cow::Borrowed(text)
9
    }
10
}
11

12
fn main() {
13
    let unix = normalize_newlines("a\nb\nc");
14
    let win = normalize_newlines("a\r\nb\r\nc");
15
    println!("unix borrowed: {}", matches!(unix, Cow::Borrowed(_)));
16
    println!("win owned:     {}", matches!(win, Cow::Owned(_)));
17
    println!("win value:     {win:?}");
18
}

Output:

1
unix borrowed: true
2
win owned:     true
3
win value:     "a\nb\nc"

str::replace always allocates a String, which is why we only call it inside the owned arm — files that are already LF-only never touch the heap.

Exercise 3: Store borrowed-or-owned in a struct

Difficulty: Advanced

Objective: Use Cow as a struct field so the same type can hold a 'static literal without copying or a runtime-generated String, and write a function returning Cow<'a, str> that conditionally appends a default file extension.

Instructions: (a) Define struct Config<'a> { name: Cow<'a, str> } with constructors from_static(name: &'a str) (borrowed) and generated(n: u32) (owned, e.g. format!("node-{n}")). (b) Implement with_extension<'a>(path: &'a str, ext: &str) -> Cow<'a, str> that returns the path borrowed if it already has an extension, otherwise appends .{ext} and owns it. Use std::path::Path::new(path).extension() to detect an existing extension.

1
use std::borrow::Cow;
2

3
struct Config<'a> {
4
    name: Cow<'a, str>,
5
}
6

7
impl<'a> Config<'a> {
8
    fn from_static(name: &'a str) -> Self {
9
        todo!()
10
    }
11
    fn generated(n: u32) -> Self {
12
        todo!()
13
    }
14
}
15

16
fn with_extension<'a>(path: &'a str, ext: &str) -> Cow<'a, str> {
17
    todo!()
18
}
19

20
fn main() {
21
    let a = Config::from_static("default");
22
    let b = Config::generated(7);
23
    println!("a.name = {}, len {}", a.name, a.name.len());
24
    println!("b.name = {}", b.name);
25

26
    let p1 = with_extension("report.pdf", "txt");
27
    let p2 = with_extension("report", "txt");
28
    println!("{p1} borrowed={}", matches!(p1, Cow::Borrowed(_)));
29
    println!("{p2} owned={}", matches!(p2, Cow::Owned(_)));
30
}

Solution

1
use std::borrow::Cow;
2

3
#[derive(Debug)]
4
struct Config<'a> {
5
    name: Cow<'a, str>,
6
}
7

8
impl<'a> Config<'a> {
9
    // Zero-copy when the caller passes a literal (or any &'a str).
10
    fn from_static(name: &'a str) -> Self {
11
        Config { name: Cow::Borrowed(name) }
12
    }
13
    // Owned when built at runtime.
14
    fn generated(n: u32) -> Self {
15
        Config { name: Cow::Owned(format!("node-{n}")) }
16
    }
17
}
18

19
fn with_extension<'a>(path: &'a str, ext: &str) -> Cow<'a, str> {
20
    if std::path::Path::new(path).extension().is_some() {
21
        Cow::Borrowed(path)
22
    } else {
23
        Cow::Owned(format!("{path}.{ext}"))
24
    }
25
}
26

27
fn main() {
28
    let a = Config::from_static("default");
29
    let b = Config::generated(7);
30
    // .name derefs to &str
31
    println!("a.name = {}, len {}", a.name, a.name.len());
32
    println!("b.name = {}", b.name);
33

34
    let p1 = with_extension("report.pdf", "txt");
35
    let p2 = with_extension("report", "txt");
36
    println!("{p1} borrowed={}", matches!(p1, Cow::Borrowed(_)));
37
    println!("{p2} owned={}", matches!(p2, Cow::Owned(_)));
38
}

Output:

1
a.name = default, len 7
2
b.name = node-7
3
report.pdf borrowed=true
4
report.txt owned=true

Adding Cow<'a, str> as a field forces the lifetime parameter 'a onto Config. That is the price of holding borrowed data — and the reward is that from_static("default") stores the literal with no heap allocation, while generated still owns its runtime string in the very same type.

Clone-on-Write with `Cow<'_, T>`

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

The shape of `Cow`

Reading through `Cow` (`Deref`)

Writing through `Cow` (`to_mut` and `into_owned`)

Why this matters: the allocation you avoid

Key Differences

`Cow` is not just for strings

`Cow` versus the other smart pointers

Mental model versus TypeScript

Common Pitfalls

Pitfall 1: borrowing a local into `Cow::Borrowed`

Pitfall 2: trying to mutate a `Cow` directly

Pitfall 3: using `Cow` when you always allocate anyway

Pitfall 4: assuming `Cow::Owned` from a `String` is free to compare

Best Practices

Real-World Example

Further Reading

Official documentation

Exercises

Exercise 1: Trim only when needed

Exercise 2: Normalize line endings

Exercise 3: Store borrowed-or-owned in a struct

Clone-on-Write with Cow<'_, T>

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

The shape of Cow

Reading through Cow (Deref)

Writing through Cow (to_mut and into_owned)

Why this matters: the allocation you avoid

Key Differences

Cow is not just for strings

Cow versus the other smart pointers

Mental model versus TypeScript

Common Pitfalls

Pitfall 1: borrowing a local into Cow::Borrowed

Pitfall 2: trying to mutate a Cow directly

Pitfall 3: using Cow when you always allocate anyway

Pitfall 4: assuming Cow::Owned from a String is free to compare

Best Practices

Real-World Example

Further Reading

Official documentation

Related sections in this guide

Exercises

Exercise 1: Trim only when needed

Exercise 2: Normalize line endings

Exercise 3: Store borrowed-or-owned in a struct

Clone-on-Write with `Cow<'_, T>`

The shape of `Cow`

Reading through `Cow` (`Deref`)

Writing through `Cow` (`to_mut` and `into_owned`)

`Cow` is not just for strings

`Cow` versus the other smart pointers

Pitfall 1: borrowing a local into `Cow::Borrowed`

Pitfall 2: trying to mutate a `Cow` directly

Pitfall 3: using `Cow` when you always allocate anyway

Pitfall 4: assuming `Cow::Owned` from a `String` is free to compare