Sorting by name, then by age, then by id ends in a nested if a == b { ... } ladder. Ordering::then_with flattens the whole thing into one expression.

The pain: a manual tie-break ladder grows ugly fast.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

items.sort_by(|a, b| {
    let ord = a.last.cmp(&b.last);
    if ord != std::cmp::Ordering::Equal {
        ord
    } else {
        let ord = a.first.cmp(&b.first);
        if ord != std::cmp::Ordering::Equal {
            ord
        } else {
            a.id.cmp(&b.id)
        }
    }
});

Ordering has two combinators built for exactly this:

• then(other) — eager: returns self if it’s not Equal, otherwise other.
• then_with(|| other) — lazy: only computes the next comparison if the previous was Equal.

Prefer then_with whenever the next cmp does real work (string comparison, derived keys), so you don’t pay for it on every pair.

1
2
3
4
5

items.sort_by(|a, b| {
    a.last.cmp(&b.last)
        .then_with(|| a.first.cmp(&b.first))
        .then_with(|| a.id.cmp(&b.id))
});

Reads top-to-bottom in priority order, no nesting, no early-return. Mixing ascending and descending is a one-character change — wrap a field in Reverse:

1
2
3
4
5
6
7
8

use std::cmp::Reverse;

// Last name ascending, then age DESCENDING, then id ascending.
items.sort_by(|a, b| {
    a.last.cmp(&b.last)
        .then_with(|| Reverse(a.age).cmp(&Reverse(b.age)))
        .then_with(|| a.id.cmp(&b.id))
});

The same pattern works in any Ord/PartialOrd impl — then_with is how a hand-written cmp stays readable.

You want to write a config file, a lockfile, or a “did we run yet” sentinel — but only if it isn’t already there. The if path.exists() { … } else { File::create(path) } pattern looks fine until two processes hit it at the same time. There’s a one-line fix sitting in std::fs.

The naive guard is a textbook TOCTOU race: between the moment you check existence and the moment you call create, another process can slip in and put a file there. You’ll then happily truncate their work.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

use std::fs::{self, File};
use std::path::Path;

fn write_once_racy(path: &Path) -> std::io::Result<File> {
    if path.exists() {
        return Err(std::io::Error::new(
            std::io::ErrorKind::AlreadyExists,
            "already there",
        ));
    }
    // Window of vulnerability: another process can create the file here.
    File::create(path) // truncates if it now exists
}

File::create_new (stable since 1.77) collapses both steps into a single syscall — O_CREAT | O_EXCL on Unix, CREATE_NEW on Windows — so the kernel decides the winner:

1
2
3
4
5
6

use std::fs::File;
use std::path::Path;

fn write_once(path: &Path) -> std::io::Result<File> {
    File::create_new(path)
}

If the file already exists, you get back an io::Error with ErrorKind::AlreadyExists and nothing on disk is touched. That’s the whole behaviour — and it’s the same whether one process or fifty are racing for the same path.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

use std::fs::{self, File};
use std::io::{ErrorKind, Write};

let path = std::env::temp_dir().join("rustbites-169.lock");
let _ = fs::remove_file(&path); // start clean

// First call wins and gets a writable handle.
let mut first = File::create_new(&path).expect("first create");
first.write_all(b"owner=me").unwrap();

// Second call fails — no truncation, no clobber.
let err = File::create_new(&path).unwrap_err();
assert_eq!(err.kind(), ErrorKind::AlreadyExists);

fs::remove_file(&path).unwrap();

For the equivalent guarantee on an existing handle you’d previously reach for OpenOptions::new().write(true).create_new(true).open(path) — that still works, and File::create_new is just the shorthand when you want the default “write, create-new, truncate-off” combo.

Use it for lockfiles, idempotent setup steps, “did we already write the manifest” checks, and anywhere the existence test and the create were a single logical step pretending to be two.

You have a Vec<&str> of numbers to parse and you want to bail the moment one of them is malformed. The hand-rolled loop with ? works, but collect() does the same thing in one line — and most people never realize the trick is in the turbofish.

The pain point is everywhere: parse a row of CSV cells, deserialize a batch of records, convert a list of paths — any time you map a fallible function over an iterator and want the first failure to stop the show.

The naive version builds the Vec by hand and threads ? through a loop:

1
2
3
4
5
6
7

fn parse_all_loop(inputs: &[&str]) -> Result<Vec<i32>, std::num::ParseIntError> {
    let mut nums = Vec::with_capacity(inputs.len());
    for s in inputs {
        nums.push(s.parse::<i32>()?);
    }
    Ok(nums)
}

The same thing in one line, by asking collect to produce a Result<Vec<_>, _> instead of a Vec<Result<_, _>>:

1
2
3

fn parse_all(inputs: &[&str]) -> Result<Vec<i32>, std::num::ParseIntError> {
    inputs.iter().map(|s| s.parse::<i32>()).collect()
}

That works because Result<C, E> (where C: FromIterator<T>) implements FromIterator<Result<T, E>>: feed it an iterator of Results and it yields a single Result. The first Err short-circuits the rest of the iteration; if every item is Ok, you get Ok(collection) back.

1
2
3
4
5
6
7
8

let good = ["1", "2", "3"];
let bad  = ["1", "oops", "3"];

let ok: Result<Vec<i32>, _> = good.iter().map(|s| s.parse()).collect();
assert_eq!(ok.unwrap(), vec![1, 2, 3]);

let err: Result<Vec<i32>, _> = bad.iter().map(|s| s.parse()).collect();
assert!(err.is_err());

The same impl exists for Option, so collect::<Option<Vec<_>>>() bails on the first None:

1
2
3
4
5

let some_all: Option<Vec<u32>> = ["1", "2", "3"].iter().map(|s| s.parse().ok()).collect();
assert_eq!(some_all, Some(vec![1, 2, 3]));

let some_none: Option<Vec<u32>> = ["1", "no", "3"].iter().map(|s| s.parse().ok()).collect();
assert_eq!(some_none, None);

You’re not stuck with Vec either — any FromIterator target works, so Result<HashSet<_>, _> or Result<String, _> from a Chars iterator is just as valid.

Use it whenever you’d otherwise write a fold-the-error loop. The intent reads off the type signature, and the iterator stops cold at the first bad item instead of finishing the parse and then sifting through a Vec<Result<_, _>> afterwards.

When every step in a loop or formula could overflow, calling .saturating_add() and .saturating_sub() on each one turns one line of math into a paragraph.

std::num::Saturating<T> is a tuple newtype wrapper that overloads the normal operators (+, -, *, +=, …) to use saturating semantics — operations clamp to the type’s MIN or MAX instead of wrapping or panicking. You write a + b, not a.saturating_add(b).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

use std::num::Saturating;

let hp: Saturating<u8> = Saturating(250);
let heal = Saturating(20u8);
let damage = Saturating(255u8);

// Pins at 255 instead of wrapping or panicking.
let healed = hp + heal;
assert_eq!(healed.0, 255);

// Pins at 0 instead of underflowing.
let dead = hp - damage;
assert_eq!(dead.0, 0);

The unwrapped equivalent works, but every operator turns into a method call:

1
2
3
4
5

let hp: u8 = 250;
let healed = hp.saturating_add(20);
let dead = hp.saturating_sub(255);
assert_eq!(healed, 255);
assert_eq!(dead, 0);

The wrapper really pays off inside a formula or an iterator chain, where you’d otherwise be wrapping each binary op:

1
2
3
4
5

use std::num::Saturating;

let damages = [Saturating(200u8), Saturating(100), Saturating(50)];
let total: Saturating<u8> = damages.iter().copied().sum(); // sticks at 255
assert_eq!(total.0, 255);

There’s a matching std::num::Wrapping<T> when you actually want cyclical math (hashes, CRCs, monotonic counters that should roll over), and both wrappers implement From, Default, Sum, and Product, so you can drop them into structs and iterator chains without ceremony.

Reach for Saturating<T> whenever a value has a logical floor or ceiling — health bars, progress percentages, retry budgets — and overflow should pin to the edge instead of panicking in debug or silently wrapping in release.

*map.entry(k).or_insert(0) += 1 is the classic Rust counter. The moment the “first time” branch needs to look different from the “next time” branch, that pattern stops fitting — and and_modify slots in.

HashMap::entry(k) returns an Entry enum pointing at the slot for k, occupied or vacant. The famous methods are or_insert(default) and or_insert_with(|| ...). Quieter but often nicer is and_modify: it runs a closure on the value when the key is already there, and does nothing when it isn’t. Chain it with or_insert and you get update if present, insert if not in one expression — with a single lookup.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

use std::collections::HashMap;

let mut counts: HashMap<&str, u32> = HashMap::new();

for word in ["rust", "iron", "rust", "rust", "iron"] {
    counts
        .entry(word)
        .and_modify(|n| *n += 1)
        .or_insert(1);
}

assert_eq!(counts["rust"], 3);
assert_eq!(counts["iron"], 2);

For pure counters that’s a tie with *entry.or_insert(0) += 1. The shape really pays off when the two branches store different data. Imagine grouping events by user, where the first event records the user’s name and later events only bump a counter:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

use std::collections::HashMap;

#[derive(Debug, PartialEq)]
struct UserStats { name: String, visits: u32 }

let events = [(1u32, "alice"), (2, "bob"), (1, "alice")];
let mut stats: HashMap<u32, UserStats> = HashMap::new();

for (id, name) in events {
    stats
        .entry(id)
        .and_modify(|s| s.visits += 1)
        .or_insert(UserStats { name: name.into(), visits: 1 });
}

assert_eq!(stats[&1], UserStats { name: "alice".into(), visits: 2 });
assert_eq!(stats[&2], UserStats { name: "bob".into(),   visits: 1 });

and_modify takes &mut V so you mutate in place; or_insert produces the initial V. and_modify also returns the Entry back, which is why the chain works — and which means you can stack several modifications before the final or_insert.

You write a generic struct, never actually store a T in any field, and the compiler stops you with “parameter T is never used”. PhantomData<T> is the zero-cost lie that fixes it — a marker that occupies no bytes but tells the compiler “act as if I own a T.”

The problem shows up the moment you build a typed handle around something that isn’t a T:

1
2
3
4

// Won't compile: T isn't actually stored anywhere.
struct TypedId<T> {
    raw: u64,
}

rustc rejects this because an unused type parameter is almost always a bug — variance, drop checking, and Send/Sync all depend on what a struct claims to own. std::marker::PhantomData<T> is the escape hatch: a zero-sized struct that pretends the type parameter is used:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

use std::marker::PhantomData;

struct TypedId<T> {
    raw: u64,
    _marker: PhantomData<T>,
}

impl<T> TypedId<T> {
    fn new(raw: u64) -> Self {
        Self { raw, _marker: PhantomData }
    }
}

struct User;
struct Order;

let u: TypedId<User>  = TypedId::new(1);
let o: TypedId<Order> = TypedId::new(1);

// Same raw value, different types — the compiler refuses to mix them.
// let _: TypedId<User> = o; // error: expected TypedId<User>, found TypedId<Order>

assert_eq!(std::mem::size_of::<TypedId<User>>(), 8); // still just the u64

The _marker field disappears at runtime — size_of::<TypedId<User>>() is exactly size_of::<u64>(). But at compile time, TypedId<User> and TypedId<Order> are distinct types you can’t accidentally swap.

The same pattern fixes lifetimes too. FFI wrappers borrow from a buffer they don’t physically point into:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

use std::marker::PhantomData;

struct CursorHandle<'a> {
    raw_ptr: *const u8,
    _borrow: PhantomData<&'a [u8]>,
}

impl<'a> CursorHandle<'a> {
    fn new(buf: &'a [u8]) -> Self {
        Self { raw_ptr: buf.as_ptr(), _borrow: PhantomData }
    }
}

let buf = vec![1u8, 2, 3];
let cursor = CursorHandle::new(&buf);
// drop(buf); // compile error — cursor still borrows it, thanks to PhantomData
let _ = cursor;

Without the PhantomData<&'a [u8]>, the 'a would be unused and the compiler wouldn’t enforce that buf outlives cursor. With it, the borrow checker treats CursorHandle<'a> as if it held a real &'a [u8].

Three flavors of PhantomData you’ll see in the wild — pick by what you want the compiler to believe:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

use std::marker::PhantomData;

// 1. Owns a T (covariant, drops a T): PhantomData<T>
struct Owns<T>(PhantomData<T>);

// 2. Borrows a T (no drop): PhantomData<&'a T>
struct Borrows<'a, T>(PhantomData<&'a T>);

// 3. Neither Send nor Sync: PhantomData<*const ()>
struct NotThreadSafe(PhantomData<*const ()>);

fn assert_send<T: Send>() {}
// assert_send::<NotThreadSafe>(); // would fail — raw ptr makes it !Send

assert_eq!(std::mem::size_of::<Owns<u64>>(), 0);
assert_eq!(std::mem::size_of::<Borrows<'_, u64>>(), 0);
assert_eq!(std::mem::size_of::<NotThreadSafe>(), 0);

That last one is the cheap way to opt a type out of Send/Sync without unsafe — Rc<T> uses exactly this trick internally to stay single-threaded.

PhantomData is the bookkeeping behind almost every wrapper type you’ve used. Cell, Cow, Pin, Rc, and NonNull all carry one — it’s how they tell the compiler what they conceptually own without paying for it at runtime.

The moment you hand-roll Future::poll, you have a Pin<&mut Self> and a question Rust won’t answer for you: how do I touch my fields? self.inner doesn’t compile, &mut self.inner is what Pin exists to prevent, and the answer — pin projection — is one of those idioms everyone reinvents until they reach for pin-project-lite.

bite-162 covered what Pin<P> is and why async futures need it. This one is about the very next thing you trip over: actually polling the inner future from your own poll method.

The problem

A wrapper that polls an inner future and counts how many times it was polled:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

struct Logged<F> {
    inner: F,
    polls: u32,
}

impl<F: Future> Future for Logged<F> {
    type Output = F::Output;
    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        self.inner.poll(cx) // ERROR: can't borrow through Pin<&mut Self>
    }
}

Pin<&mut Self> deliberately won’t deref-mut into &mut Self — that would hand back the exact &mut you need to mem::swap the whole struct out from under whatever pinned it. So self.inner is a non-starter. You have to project: turn a Pin<&mut Self> into a Pin<&mut F> pointing at the inner field.

Manual projection with unsafe

The raw tools are Pin::get_unchecked_mut and Pin::new_unchecked. You take &mut Self out of the pin (unsafe — you’re promising not to move the whole value), borrow disjoint fields, then re-pin the ones that need it.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll};

struct Logged<F> {
    inner: F,
    polls: u32,
}

impl<F: Future> Future for Logged<F> {
    type Output = F::Output;
    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        // SAFETY: we promise not to move `self`. `inner` is treated as
        // structurally pinned; `polls` is treated as freely movable.
        let this = unsafe { self.get_unchecked_mut() };
        this.polls += 1;
        let inner = unsafe { Pin::new_unchecked(&mut this.inner) };
        inner.poll(cx)
    }
}

Two unsafe blocks and an invariant you have to remember everywhere else in the file: if some other method ever does mem::replace(&mut this.inner, _), you’ve broken the pin contract and quietly created UB. The compiler will not catch it.

The clean answer: pin-project-lite

pin-project-lite mechanically derives the safe projection. Mark each structurally-pinned field with #[pin]:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll};
use pin_project_lite::pin_project;

pin_project! {
    struct Logged<F> {
        #[pin]
        inner: F,
        polls: u32,
    }
}

impl<F: Future> Future for Logged<F> {
    type Output = F::Output;
    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        let this = self.project();
        *this.polls += 1;
        this.inner.poll(cx)
    }
}

self.project() returns a generated struct where every #[pin] field is a Pin<&mut Field> and every other field is a plain &mut Field. No unsafe, no projection mistakes, no chance of accidentally mem::replace-ing a pinned field — the macro generates the accessors so the wrong move never compiles. This is the pattern tokio, hyper, futures, and effectively every library implementing custom futures lives on.

Structural vs non-structural — the choice you’re making

Marking a field #[pin] locks in three guarantees:

• You will never move out of it once Self is pinned (no mem::replace, no mem::swap).
• Its Drop impl runs while the field is still pinned.
• Accessors hand you Pin<&mut Field>, not &mut Field.

Unmarked fields go the other way: you treat them as freely movable. Pick wrong — pin one structurally and then mem::swap it elsewhere — and you’ve quietly invalidated whatever pointers something else handed out into that field.

Rule of thumb: if a field is itself a future, or any !Unpin type that needs to be polled in place, mark it #[pin]. Counters, flags, owned Strings — leave them unmarked.

Self-referential structs are the obvious “this should work but doesn’t” pattern in Rust: a struct that holds a buffer plus a reference into that buffer falls apart the moment it moves and the reference dangles. Pin<P> is the type that says “the pointee is fixed in memory” — and is the reason every async fn future you’ve ever .awaited can keep a pointer to its own local variables.

Why Pin exists at all

Take a String and a slice into it:

1
2
3
4

struct Mess<'a> {
    buf: String,
    view: &'a str,   // borrows from buf
}

You can’t actually build this — Rust won’t let you write a struct that borrows from one of its own fields, because the move that follows construction would invalidate the borrow. Any helper that produces a Mess and returns it by value moves buf into the caller’s stack frame; view would still point at the old location. Disaster.

async fn bodies generate exactly this kind of struct under the hood: an enum of “states,” each carrying the locals live across an .await. If one of those locals is a reference to another local, the future is self-referential. Move it after polling and you’ve hit UB.

What Pin actually does

Pin<P> wraps a pointer — Box<T>, &mut T, Rc<T>, etc. — and downgrades its API. Specifically: you can no longer reach the inner &mut T unless T: Unpin.

Without &mut T, you can’t std::mem::swap or mem::replace to move the value out. That’s the whole guarantee: the value behind a Pin<P> will never move again, except by running its destructor.

1
2
3
4
5
6

use std::pin::Pin;

let mut boxed: Pin<Box<i32>> = Box::pin(42);
// i32: Unpin, so we can still write through the pin.
*boxed = 99;
assert_eq!(*boxed, 99);

For i32 the pinning is theatre — primitives implement Unpin, the marker that says “moving me is fine.” Pin only bites when the inner type is !Unpin.

Where it bites: polling a future

Future::poll takes self: Pin<&mut Self>. The compiler-generated futures from async {} are !Unpin, so you can’t poll them through a plain &mut. You have to pin first.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll, Waker};

let fut = async { 7 * 6 };
let mut boxed: Pin<Box<_>> = Box::pin(fut);

let mut cx = Context::from_waker(Waker::noop());

match boxed.as_mut().poll(&mut cx) {
    Poll::Ready(v) => assert_eq!(v, 42),
    Poll::Pending => unreachable!(),
}

Box::pin is the easy answer when you need an owned, heap-allocated, pinned future. The allocation is what makes the address stable — Box already promised that.

Stack pinning with pin!

Heap allocation just to poll a future feels heavy, and it is. The pin! macro pins a value on the stack instead: it shadows the binding so you can never get a non-pinned reference to it again.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

use std::future::Future;
use std::pin::pin;
use std::task::{Context, Poll, Waker};

let mut fut = pin!(async { String::from("ready") });

let mut cx = Context::from_waker(Waker::noop());

if let Poll::Ready(s) = fut.as_mut().poll(&mut cx) {
    assert_eq!(s, "ready");
}

The trick is that pin! re-binds fut to a Pin<&mut _> that borrows from a hidden, scope-local slot. The original value lives until the end of the block; nothing can sneak in and move it. Stable since Rust 1.68.

Unpin: the escape hatch for ordinary types

Unpin is an auto trait: almost everything implements it automatically. String, Vec<T>, your own struct of plain fields — all Unpin. For those, Pin<&mut T> and &mut T are interchangeable via Pin::new and Pin::into_inner:

1
2
3
4
5
6
7
8
9

use std::pin::Pin;

let mut s = String::from("hi");
let pinned: Pin<&mut String> = Pin::new(&mut s);
// String: Unpin, so we get back a normal &mut String.
// `into_inner` is an associated function, not a method — avoids
// shadowing whatever `into_inner` the underlying type might have.
Pin::into_inner(pinned).push_str(", world");
assert_eq!(s, "hi, world");

This is why most of the time you can pretend Pin doesn’t exist. It only shows teeth when something is deliberately !Unpin — async-generated futures, intrusive linked-list nodes, and any self-referential struct you opt into with PhantomPinned.

When you’ll see it yourself

In day-to-day code you almost never write Pin<P> directly — the pin! macro and Box::pin cover polling, and tokio::pin! or tokio::spawn cover the async runtime case. You’ll meet Pin<&mut Self> in earnest when you:

• Hand-roll a Future. poll takes Pin<&mut Self>, so any state machine you implement by hand has to thread it through.
• Write a self-referential struct. Stick a PhantomPinned field in, and from then on the only way to use the type is through a Pin.
• Build a custom executor. Pinning the futures the executor stores is exactly the invariant the Future trait is asking you for.

The mental model that sticks: Pin<P> doesn’t pin the pointer — it pins what the pointer points at. The pointer can move, be copied, be passed around; the value under it has promised to stay where it was first pinned, all the way until Drop. That’s the contract the async machinery is built on, and the reason it’s safe to keep an .await point inside a function call hundreds of frames deep.

Cow<str> is the type everyone reaches for when a function might need to modify its input. Cow::Borrowed and Cow::Owned are the constructors that get the spotlight; to_mut is the third piece, and it’s the one that actually pays off the laziness.

What to_mut does

to_mut takes &mut Cow<str> and hands back &mut String:

• If the Cow is already Owned, you get a direct &mut to the inner String.
• If it’s Borrowed, to_mut clones the slice into a fresh String, swaps the Cow over to Owned, and then hands you the mutable reference.

That asymmetry is the whole point. Many callers borrow and never touch to_mut — they never allocate. The ones that do call it pay the allocation cost exactly once, on first write.

A walking-the-string example

Expand \t into two spaces, but only allocate if the input actually contains a tab:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

use std::borrow::Cow;

fn expand_tabs(s: &str) -> Cow<'_, str> {
    let mut out: Cow<'_, str> = Cow::Borrowed(s);
    if let Some(i) = s.find('\t') {
        // First write — `to_mut` clones the slice into a String, then we
        // rebuild from byte `i` onwards.
        let buf = out.to_mut();
        buf.truncate(i);
        for c in s[i..].chars() {
            if c == '\t' {
                buf.push_str("  ");
            } else {
                buf.push(c);
            }
        }
    }
    out
}

The happy path — input has no tab — never enters the if, never allocates, and returns the original slice wrapped in Cow::Borrowed. The unhappy path allocates exactly once.

Composing transformations

to_mut really earns its keep when you chain several optional mutations. The first one that fires flips the Cow to Owned; every following mutation sees an already-owned buffer and reuses it:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

use std::borrow::Cow;

fn apply_rules<'a>(s: &'a str, rules: &[(char, &str)]) -> Cow<'a, str> {
    let mut out: Cow<'a, str> = Cow::Borrowed(s);
    for &(from, to) in rules {
        if out.contains(from) {
            let replaced = out.replace(from, to);
            *out.to_mut() = replaced;
        }
    }
    out
}

Three things worth pointing at. First, out.contains(from) works because Cow<str> derefs to str. Second, the assignment *out.to_mut() = replaced replaces the inner String, not the Cow itself. Third, once the first rule fires, all subsequent to_mut calls are a no-op &mut String — no extra clones.

Pitfall: to_mut always commits

There’s no “preview, then maybe commit” mode. Calling to_mut on a borrowed Cow clones immediately, even if you never end up writing through the returned reference. So this is a trap:

1
2
3
4

if !out.is_empty() {
    let _ = out.to_mut();  // allocates even though we may not change anything
    // ... maybe mutate, maybe not
}

Guard the call with the actual condition that means “I’m about to write,” not the condition that means “I might.” The mental shortcut: to_mut is the moment you trade your &str for a String. Reach for it lazily, but commit completely.

Rc<T> is a counter, not a tracing GC: two Rcs pointing at each other will sit in memory forever, each propping the other’s strong-count above zero. Weak<T> is the cure — a pointer that observes an Rc’s allocation without keeping it alive.

The leak Rc lets you write

A parent node owning its children with Rc, and each child holding an Rc back at the parent, looks innocent — and leaks every node:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

use std::cell::RefCell;
use std::rc::Rc;

struct Node {
    name: String,
    parent: RefCell<Option<Rc<Node>>>,    // <-- the trap
    children: RefCell<Vec<Rc<Node>>>,
}

let root  = Rc::new(Node {
    name: "root".into(),
    parent: RefCell::new(None),
    children: RefCell::new(vec![]),
});
let child = Rc::new(Node {
    name: "child".into(),
    parent: RefCell::new(Some(Rc::clone(&root))),  // child owns root
    children: RefCell::new(vec![]),
});
root.children.borrow_mut().push(Rc::clone(&child));  // root owns child

// drop(root); drop(child);  -> strong_count of each is still 1. Memory never freed.

Once root and child go out of scope, their last external Rcs drop, but each still holds an Rc to the other. The strong-counts never hit zero. Drop never runs. The allocation stays put until the process exits.

Weak<T>: a pointer that doesn’t keep things alive

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

use std::cell::RefCell;
use std::rc::{Rc, Weak};

struct Node {
    name: String,
    parent: RefCell<Weak<Node>>,          // <-- the fix
    children: RefCell<Vec<Rc<Node>>>,
}

let root = Rc::new(Node {
    name: "root".into(),
    parent: RefCell::new(Weak::new()),
    children: RefCell::new(vec![]),
});

let child = Rc::new(Node {
    name: "child".into(),
    parent: RefCell::new(Rc::downgrade(&root)),  // weak — doesn't bump strong count
    children: RefCell::new(vec![]),
});
root.children.borrow_mut().push(Rc::clone(&child));

assert_eq!(Rc::strong_count(&root), 1);   // only `root` itself
assert_eq!(Rc::weak_count(&root), 1);     // `child.parent`
assert_eq!(Rc::strong_count(&child), 2);  // `child` + `root.children[0]`

Strong pointers own; weak pointers observe. Rc::downgrade(&root) gives you a Weak<Node> that points at the same allocation but only bumps the weak counter. The strong counter — the one that decides when to drop — is unaffected. When the last Rc to a node disappears, the node is destroyed, even if a hundred Weaks are still aimed at it.

Reading through a Weak: upgrade

A Weak doesn’t deref. To get at the value, ask for a temporary Rc back — and be ready for None, because the allocation may already be gone:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

use std::rc::{Rc, Weak};

let strong = Rc::new(String::from("alive"));
let weak: Weak<String> = Rc::downgrade(&strong);

if let Some(rc) = weak.upgrade() {
    assert_eq!(*rc, "alive");
}

drop(strong);            // strong count -> 0, value dropped
assert!(weak.upgrade().is_none());

upgrade is the only way to read through a Weak<T>. The Option return type is the whole point: it forces every caller to handle the case where the upgraded pointer no longer refers to anything. That’s exactly the discipline a back-pointer in a tree needs — “give me my parent, if it’s still around.”

A standalone Weak: Weak::new

You usually want a Weak field initialised before its target exists. Weak::new makes one that points at nothing and upgrades to None:

1
2
3
4

use std::rc::Weak;

let dangling: Weak<i32> = Weak::new();
assert!(dangling.upgrade().is_none());

This is what filled the parent field of root above before we had any pointer to give it. No allocation happens until something is actually downgraded into it.

Counts: strong_count and weak_count

Both counters are inspectable. weak_count is what Rc::downgrade increments; strong_count is the one that gates the drop:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

use std::rc::{Rc, Weak};

let a = Rc::new(42);
let w1: Weak<i32> = Rc::downgrade(&a);
let w2: Weak<i32> = Rc::downgrade(&a);

assert_eq!(Rc::strong_count(&a), 1);
assert_eq!(Rc::weak_count(&a), 2);

drop(w1);
assert_eq!(Rc::weak_count(&a), 1);

// Dropping the only strong owner frees the *value* immediately.
// The remaining weak pointer keeps the allocation header alive but
// upgrades will return None.
drop(a);
assert!(w2.upgrade().is_none());

One nuance worth knowing: a live Weak keeps a small allocation header around (so it can check whether the value is still there), but not the value itself. Drop runs on the inner T as soon as the strong-count hits zero, even if a million Weaks outlive it.

When to reach for Weak

Whenever the ownership graph has a back-edge or a cycle:

• Parent pointers in a tree. Children own children with Rc; children point back to parents with Weak.
• Observer / listener lists. A subject holds Weak<Listener> so listeners can be dropped externally without first deregistering.
• Caches. A cache holding Weak<T> lets entries vanish the moment their last real user lets go.

The rule is mechanical: pick one direction in the cycle to be the owner (Rc), and make every edge that closes the loop a Weak. If that direction is hard to choose, the lifetime question is probably a real design question hiding inside the data.

Arc<T> has the same thing

Arc<T> gives you the same pair on the thread-safe side: Arc::downgrade returns a std::sync::Weak<T> (different type, same shape) that you upgrade to an Option<Arc<T>>. Same rules, same idiom — atomic counters under the hood.

Reach for Weak the moment any node in your structure needs to point at something that also points back. The borrow checker can’t catch this leak; making the back-edge weak is the design that does.