The `Deref` Trait and Deref Coercion

20 min read

The Deref trait is the mechanism that lets a smart pointer behave like the value it points to. It is also the quiet machinery behind one of the first “magic” things a TypeScript developer notices in Rust: why a &String works where a &str is expected, and why you almost never have to write * to call a method on a Box.

Quick Overview

In JavaScript and TypeScript there is no concept of dereferencing — a variable that holds an object is the reference, and obj.method() always reaches the object directly. Rust separates a value from a pointer to that value, so it needs a rule for “follow the pointer.” The Deref trait defines that rule, and the compiler uses it to perform deref coercion: automatically converting &Wrapper into &Inner (and &Inner into &InnerInner, as deep as needed) at method-call and argument-passing sites.

For a working TypeScript developer, the payoff is concrete: Deref is why Box<T>, Rc<T>, String, and Vec<T> all let you call the inner type’s methods directly, and why passing &my_string to a fn(&str) “just works.”

TypeScript/JavaScript Example

TypeScript has no dereference operator and no user-definable “act like the thing I wrap” hook. The closest everyday experiences are: (1) accessing a wrapped value works transparently because there is no wrapper to see through, and (2) string primitives auto-box to String objects so you can call methods on them.

1
// In TypeScript a "wrapper" has to expose the inner API by hand —
2
// there is no language hook that says "treat me as my inner value."
3
class Username {
4
  constructor(private readonly value: string) {}
5

6
  // You must manually re-expose every method you want callers to use...
7
  get length(): number {
8
    return this.value.length;
9
  }
10
  toUpperCase(): string {
11
    return this.value.toUpperCase();
12
  }
13
  // ...or expose the raw string and make callers reach in:
14
  unwrap(): string {
15
    return this.value;
16
  }
17
}
18

19
function logLine(label: string, value: string): void {
20
  console.log(`${label}: ${value}`);
21
}
22

23
const user = new Username("ada_lovelace");
24

25
// A `Username` is NOT a `string`, so this is a type error in TS:
26
// logLine("user", user);          // Argument of type 'Username' is not assignable to 'string'
27
logLine("user", user.unwrap()); // you must unwrap explicitly
28
console.log(user.length); // 12 — only works because we hand-wrote a getter
29
console.log(user.toUpperCase()); // works only because we re-implemented it
30

31
// Separately: JS string *primitives* auto-box to String objects,
32
// which is the one place JS does something "deref-like" for you.
33
const s = "hello";
34
console.log(s.toUpperCase()); // HELLO — the primitive is boxed transiently

Key points:

A Username wrapper has to manually forward every method, or force callers to unwrap().
There is no way to say “a Username can be used anywhere a string is expected.”
The only built-in “transparent” behavior is primitive auto-boxing ("hello".toUpperCase()), and you cannot extend it to your own types.

Rust Equivalent

Rust lets your wrapper opt into “act like my inner value” by implementing Deref. After that, the inner type’s methods are callable directly, and a &Wrapper coerces into a &Inner at call sites — no manual forwarding, no unwrap().

1
use std::ops::Deref;
2

3
/// A newtype guaranteeing the wrapped string is non-empty and trimmed.
4
#[derive(Debug, Clone)]
5
struct Username(String);
6

7
impl Username {
8
    fn new(raw: &str) -> Result<Username, String> {
9
        let trimmed = raw.trim();
10
        if trimmed.is_empty() {
11
            Err("username must not be empty".to_string())
12
        } else {
13
            Ok(Username(trimmed.to_string()))
14
        }
15
    }
16
}
17

18
// Deref to `str` exposes the entire string-slice API for free.
19
impl Deref for Username {
20
    type Target = str;
21
    fn deref(&self) -> &str {
22
        &self.0
23
    }
24
}
25

26
fn log_line(label: &str, value: &str) {
27
    println!("{label}: {value}");
28
}
29

30
fn main() {
31
    let user = Username::new("  ada_lovelace  ").expect("valid");
32

33
    log_line("user", &user); // &Username coerces to &str — no unwrap
34
    println!("len   = {}", user.len()); // str::len, straight through
35
    println!("upper = {}", user.to_uppercase()); // str::to_uppercase, straight through
36
    println!("ada?  = {}", user.starts_with("ada"));
37
}

Output:

1
user: ada_lovelace
2
len   = 12
3
upper = ADA_LOVELACE
4
ada?  = true

The single impl Deref replaces all the hand-written forwarding the TypeScript version needed. The validating constructor still guarantees the invariant; Deref only governs read access to the inner str.

Note: Implementing Deref to expose an inner API is acceptable for thin newtype wrappers like this, but it is not a general inheritance mechanism — see Common Pitfalls and Best Practices. Use it deliberately.

Detailed Explanation

What `Deref` actually is

Deref is a trait from std::ops with one associated type and one method:

1
// (Definition from the standard library, shown for reference.)
2
pub trait Deref {
3
    type Target: ?Sized;
4
    fn deref(&self) -> &Self::Target;
5
}

Target is the type you “become” when dereferenced.
deref(&self) -> &Target returns a reference to the inner value (never a moved/owned value — that is important for the borrow checker).

When you write *value and value is not a plain reference, the compiler rewrites it as *(value.deref()). That is: call deref() to get a &Target, then apply the built-in * to that reference. So *boxed_string means *(boxed_string.deref()).

Deref coercion: the automatic part

The genuinely useful behavior is deref coercion. In two specific situations the compiler will automatically insert .deref() calls — as many as needed — to make types line up:

Argument passing / reference site: if you have a &T and a function wants &U, and T: Deref<Target = U> (transitively), the compiler inserts the coercion.
Method receiver resolution: when you call value.method(), the compiler tries value, then *value, then **value, and so on, following Deref impls, until it finds a type that has method.

This is why all of the following work without a single explicit *:

1
use std::rc::Rc;
2

3
fn main() {
4
    // Box<T> implements Deref<Target = T>, so String's methods are reachable.
5
    let boxed = Box::new(String::from("hello"));
6
    println!("len via box = {}", boxed.len()); // String::len through Box
7
    println!("upper = {}", boxed.to_uppercase()); // String::to_uppercase through Box
8

9
    // Rc<T> also implements Deref (read-only).
10
    let shared = Rc::new(vec![10, 20, 30]);
11
    println!("first = {:?}", shared.first()); // <[i32]>::first through Rc -> Vec -> slice
12
    println!("sum = {}", shared.iter().sum::<i32>());
13

14
    // Three different smart pointers, all coerce to &str for one &str function:
15
    fn shout(s: &str) -> String {
16
        s.to_uppercase()
17
    }
18
    let a = String::from("box");
19
    let b = Box::new(String::from("rc"));
20
    let c = Rc::new(String::from("string"));
21
    println!("{} {} {}", shout(&a), shout(&b), shout(&c));
22
}

Output:

1
len via box = 5
2
upper = HELLO
3
first = Some(10)
4
sum = 60
5
BOX RC STRING

Notice the shared.first() case chains coercions: Rc<Vec<i32>> → Vec<i32> → [i32] (a slice), and first lives on the slice. The compiler walks the whole Deref chain for you.

Why `&String` works where `&str` is expected

This is the canonical example, and it is pure deref coercion. The standard library implements impl Deref for String { type Target = str; ... }. So when you call a fn greet(name: &str) with a &String, the compiler sees the mismatch, finds String: Deref<Target = str>, and inserts the coercion automatically.

1
fn greet(name: &str) {
2
    println!("Hello, {name}!");
3
}
4

5
fn main() {
6
    let owned: String = String::from("Ada");
7

8
    greet(&owned); // &String -> &str, coercion inserted by the compiler
9
    greet("Grace"); // a literal is already &str
10

11
    // Box<String> -> &String -> &str (two coercions in a row):
12
    let boxed: Box<String> = Box::new(String::from("Linus"));
13
    greet(&boxed);
14

15
    // The hand-written equivalents the compiler is sparing you:
16
    greet(owned.as_str()); // explicit &str
17
    greet(&owned[..]); // explicit full-range slice
18
}

Output:

1
Hello, Ada!
2
Hello, Grace!
3
Hello, Linus!
4
Hello, Ada!
5
Hello, Ada!

Tip: Prefer &str over &String for function parameters because of this coercion. A fn(&str) accepts string literals, &String, &Box<String>, and slices; a fn(&String) accepts only an owned String behind a reference. This is covered more in ../03-functions/README.md.

`DerefMut`: the mutable counterpart

Deref gives &Target. To get &mut Target (for mutation through the wrapper, or to mutate behind a Box), implement DerefMut:

1
use std::ops::{Deref, DerefMut};
2

3
struct MyBox<T>(T);
4

5
impl<T> MyBox<T> {
6
    fn new(x: T) -> MyBox<T> {
7
        MyBox(x)
8
    }
9
}
10

11
impl<T> Deref for MyBox<T> {
12
    type Target = T;
13
    fn deref(&self) -> &T {
14
        &self.0
15
    }
16
}
17

18
impl<T> DerefMut for MyBox<T> {
19
    fn deref_mut(&mut self) -> &mut T {
20
        &mut self.0
21
    }
22
}
23

24
fn main() {
25
    let b = MyBox::new(5);
26
    println!("*b = {}", *b); // Deref: *(b.deref())
27

28
    let mut words = MyBox::new(vec!["a", "b"]);
29
    words.push("c"); // DerefMut coercion: (*words).push("c")
30
    println!("len = {}", words.len()); // Deref coercion: (*words).len()
31
    println!("{:?}", *words);
32
}

Output:

1
*b = 5
2
len = 3
3
["a", "b", "c"]

DerefMut requires Deref as a supertrait (you must have both), and coercion of mutable references (&mut T → &mut U) follows the same rules through DerefMut.

How `Box` deref differs slightly

Box<T> participates in deref coercion exactly like the examples above, so boxed.method() and greet(&boxed) work. Box<T> has one extra power the others lack: because the compiler knows a Box is the unique owner, dereferencing an owned box (let inner = *boxed;) can move the value out of the heap. That is a special compiler rule for Box, not something Deref itself provides — deref() only ever returns a &Target. The owning-move behavior is covered in box.md; here, focus on the shared-reference coercion that all smart pointers share.

Key Differences

Concept	TypeScript / JavaScript	Rust with `Deref`
Dereferencing	No concept; a variable is the reference	`value` follows the pointer (sugar for `value.deref()`)
“Act like inner value”	Manual method forwarding or `.unwrap()`	One `impl Deref` exposes the inner API
`&String` vs `&str`	n/a (one `string` type)	Coercion makes `&String` usable as `&str`
Auto-conversion at call site	Only primitive auto-boxing, not extensible	Deref coercion, user-extensible per type
Mutable access	Always available on the object	Separate `DerefMut` trait, opt-in
Method lookup	Single prototype chain	Compiler walks the `Deref` chain (`value`, `value`, `*value`, …)
Where it triggers	n/a	Method receivers and `&`/`&mut` argument sites only

The mental shift: in TypeScript “transparency” is the default and you can’t customize it. In Rust, transparency is opt-in (impl Deref), explicit about read vs. write (Deref vs DerefMut), and applies only in the two well-defined coercion situations — never to operators like ==, never to generic trait bounds.

Where the `&String`/`&str` analogy breaks down

Unlike TypeScript’s single string, Rust deliberately has two types: String (owned, growable, heap) and str / &str (a borrowed view). Deref<Target = str> is the bridge that makes them interoperate smoothly, but they remain distinct types. You cannot, for example, push to a &str (it is a read-only view), and a function returning &str is promising not to allocate. The coercion smooths the ergonomics; it does not erase the distinction the way TypeScript’s single type does.

Common Pitfalls

Pitfall 1: Expecting deref coercion to satisfy a generic trait bound

Coercion happens for references at call sites and method receivers — not for generic type parameters. A Box<String> does not implement a trait just because String does.

1
trait Greet {
2
    fn greet(&self) -> String;
3
}
4

5
impl Greet for String {
6
    fn greet(&self) -> String {
7
        format!("hi {self}")
8
    }
9
}
10

11
fn run<T: Greet>(t: T) -> String {
12
    t.greet()
13
}
14

15
fn main() {
16
    let boxed = Box::new(String::from("ada"));
17
    println!("{}", run(boxed)); // does not compile (error[E0277]: Box<String>: Greet not satisfied)
18
}

The real compiler error:

1
error[E0277]: the trait bound `Box<String>: Greet` is not satisfied
2
  --> src/main.rs:19:24
3
   |
4
19 |     println!("{}", run(boxed));
5
   |                    --- ^^^^^ the trait `Greet` is not implemented for `Box<String>`
6
   |                    |
7
   |                    required by a bound introduced by this call
8
   |
9
note: required by a bound in `run`
10
  --> src/main.rs:11:11
11
   |
12
11 | fn run<T: Greet>(t: T) -> String {
13
   |           ^^^^^ required by this bound in `run`
14
help: consider dereferencing here
15
   |
16
19 |     println!("{}", run(*boxed));
17
   |                        +

The fix is in the help text: dereference explicitly (run(*boxed)) so you pass a real String. Deref coercion will not do this for you across a generic bound.

Pitfall 2: Mutating through a wrapper that only implements `Deref`

If you implement Deref but forget DerefMut, you get read access but not write access through the wrapper.

1
use std::ops::Deref;
2

3
struct Wrapper(Vec<i32>);
4

5
impl Deref for Wrapper {
6
    type Target = Vec<i32>;
7
    fn deref(&self) -> &Vec<i32> {
8
        &self.0
9
    }
10
}
11

12
fn main() {
13
    let mut w = Wrapper(vec![1, 2, 3]);
14
    println!("len = {}", w.len()); // ok: Deref gives &Vec
15
    w.push(4); // does not compile (error[E0596]: needs DerefMut)
16
    println!("{:?}", *w);
17
}

The real compiler error (trimmed):

1
error[E0596]: cannot borrow data in dereference of `Wrapper` as mutable
2
  --> src/main.rs:15:5
3
   |
4
15 |     w.push(4);                     // needs DerefMut, which is not implemented
5
   |     ^ cannot borrow as mutable
6
   |
7
   = help: trait `DerefMut` is required to modify through a dereference, but it is not implemented for `Wrapper`

The error message names the exact fix: implement DerefMut for Wrapper.

Pitfall 3: Assuming operators like `==` use deref coercion

Deref coercion applies to method calls and reference arguments — not to binary operators. == is governed by the PartialEq trait, which is not subject to coercion.

1
use std::ops::Deref;
2

3
struct MyBox<T>(T);
4

5
impl<T> Deref for MyBox<T> {
6
    type Target = T;
7
    fn deref(&self) -> &T {
8
        &self.0
9
    }
10
}
11

12
fn main() {
13
    let b = MyBox(String::from("hi"));
14
    let same = b == String::from("hi"); // does not compile (error[E0369])
15
    println!("{same}");
16
}

The real compiler error:

1
error[E0369]: binary operation `==` cannot be applied to type `MyBox<String>`
2
  --> src/main.rs:10:18
3
   |
4
10 |     let same = b == String::from("hi");
5
   |                - ^^ ------------------ String
6
   |                |
7
   |                MyBox<String>
8
   |
9
note: an implementation of `PartialEq<String>` might be missing for `MyBox<String>`

To compare, dereference explicitly (*b == String::from("hi")) or derive/implement PartialEq on the wrapper.

Pitfall 4: Using `Deref` as a substitute for inheritance

It is tempting, coming from class-based TypeScript, to give a “subclass-like” struct a Deref to a “base” struct so the base’s methods leak through. The Rust community considers this an anti-pattern: it confuses method resolution, surprises readers (self_type.some_method() may belong to the target), and breaks down because traits are not inherited via Deref. Deref is for smart pointers and thin newtypes whose Target genuinely “is” the value — not for modeling “is-a” relationships. Prefer composition with explicit delegation, or traits, instead.

Best Practices

Implement Deref only for smart-pointer-like types and thin newtypes. Good targets: a guard that wraps one value, a validated newtype that should behave like its inner str/slice. Bad target: a domain struct you want to “inherit” from another.
Choose the most useful Target. For a string newtype, Deref<Target = str> (not String) exposes the slice API and coerces further to &str. For a Vec newtype, Deref<Target = [T]> gives the slice API while hiding mutating Vec methods.
Implement DerefMut only when mutation through the wrapper is genuinely intended, and remember it requires Deref as a supertrait.
Prefer &str and &[T] parameters over &String/&Vec<T>. Deref coercion makes the slice forms strictly more flexible callers-side. (See ../03-functions/README.md.)
Never return an owned value from deref. The signature is &self -> &Target; trying to compute and return a fresh value each call is a sign you want a method or a From/Into conversion instead.
Reach for AsRef<T> / Into<T> for explicit conversions. If you only need a one-off conversion (not transparent pointer-like behavior), AsRef/From/Into express intent more honestly than Deref.

Real-World Example

A common production pattern is a bounded stack: a collection with its own push/pop policy that nonetheless wants to offer the full read-only slice API (len, iter, first, contains, …) without re-implementing each method. Deref<Target = [T]> delivers exactly that — the wrapper controls mutation, while reads flow through to the slice.

1
use std::ops::Deref;
2

3
/// A stack with a fixed capacity. It owns its `push`/`pop` policy, but
4
/// `Deref`s to `[T]` so every read-only slice method is available for free.
5
struct BoundedStack<T> {
6
    items: Vec<T>,
7
    capacity: usize,
8
}
9

10
impl<T> BoundedStack<T> {
11
    fn new(capacity: usize) -> Self {
12
        BoundedStack { items: Vec::new(), capacity }
13
    }
14

15
    /// Push, or hand the rejected item back if the stack is full.
16
    fn push(&mut self, item: T) -> Result<(), T> {
17
        if self.items.len() == self.capacity {
18
            Err(item)
19
        } else {
20
            self.items.push(item);
21
            Ok(())
22
        }
23
    }
24

25
    fn pop(&mut self) -> Option<T> {
26
        self.items.pop()
27
    }
28
}
29

30
// Deref to a slice: the whole read-only `[T]` API, for free.
31
impl<T> Deref for BoundedStack<T> {
32
    type Target = [T];
33
    fn deref(&self) -> &[T] {
34
        &self.items
35
    }
36
}
37

38
fn main() {
39
    let mut stack: BoundedStack<i32> = BoundedStack::new(2);
40
    println!("push 1: {:?}", stack.push(1));
41
    println!("push 2: {:?}", stack.push(2));
42
    println!("push 3: {:?}", stack.push(3)); // full -> Err(3)
43

44
    // Everything below comes from `[T]` via deref coercion:
45
    println!("len      = {}", stack.len());
46
    println!("is_empty = {}", stack.is_empty());
47
    println!("first    = {:?}", stack.first());
48
    println!("contains = {}", stack.contains(&2));
49
    let total: i32 = stack.iter().sum();
50
    println!("sum      = {total}");
51

52
    println!("pop = {:?}", stack.pop());
53
    println!("len = {}", stack.len());
54
}

Output:

1
push 1: Ok(())
2
push 2: Ok(())
3
push 3: Err(3)
4
len      = 2
5
is_empty = false
6
first    = Some(1)
7
contains = true
8
sum      = 3
9
pop = Some(2)
10
len = 1

The BoundedStack exposes a deliberately small mutating surface (push enforces the capacity, pop is the only other writer) while inheriting the entire read API of a slice. Because the Target is [T] rather than Vec<T>, callers cannot bypass the policy by calling Vec::push through the wrapper — the slice type has no such method.

Exercises

Exercise 1: A sentence newtype that acts like a `str`

Difficulty: Beginner

Objective: Implement Deref so a wrapper type can be used wherever a &str is expected and can call str methods directly.

Instructions: Define struct Sentence(String). Implement Deref<Target = str> for it. Then write a free function fn word_count(s: &str) -> usize and call it by passing &sentence (relying on deref coercion). Also call to_uppercase() and len() directly on the Sentence value.

1
use std::ops::Deref;
2

3
struct Sentence(String);
4

5
impl Deref for Sentence {
6
    type Target = str;
7
    fn deref(&self) -> &str {
8
        /* ??? */
9
    }
10
}
11

12
fn word_count(s: &str) -> usize {
13
    // TODO: count whitespace-separated words
14
}
15

16
fn main() {
17
    let s = Sentence(String::from("the quick brown fox"));
18
    println!("words = {}", word_count(&s)); // expect 4
19
    println!("upper = {}", s.to_uppercase());
20
    println!("len   = {}", s.len());
21
}

Solution

1
use std::ops::Deref;
2

3
struct Sentence(String);
4

5
impl Deref for Sentence {
6
    type Target = str;
7
    fn deref(&self) -> &str {
8
        &self.0
9
    }
10
}
11

12
fn word_count(s: &str) -> usize {
13
    s.split_whitespace().count()
14
}
15

16
fn main() {
17
    let s = Sentence(String::from("the quick brown fox"));
18
    // Deref coercion: &Sentence -> &str
19
    println!("words = {}", word_count(&s));
20
    // str methods straight through the wrapper:
21
    println!("upper = {}", s.to_uppercase());
22
    println!("len   = {}", s.len());
23
}

Output:

1
words = 4
2
upper = THE QUICK BROWN FOX
3
len   = 19

The single impl Deref is all it takes: &Sentence coerces to &str for word_count, and to_uppercase/len resolve onto the str target via method-receiver deref.

Exercise 2: A read-counting smart pointer with `Deref` and `DerefMut`

Difficulty: Intermediate

Objective: Build a real smart pointer that observes how often its inner value is read, demonstrating both Deref and DerefMut.

Instructions: Define struct Logged<T> holding the value and a read counter. Implement Deref so each call to deref bumps the counter, and DerefMut so the value can be mutated. Use std::cell::Cell<u32> for the counter so you can mutate it from &self (see cell.md). Add a read_count(&self) -> u32 method. Show that calling .len(), .first(), and .iter() on a wrapped Vec each count as a read, and that *counter += 1 works via DerefMut.

Solution

1
use std::cell::Cell;
2
use std::ops::{Deref, DerefMut};
3

4
struct Logged<T> {
5
    value: T,
6
    reads: Cell<u32>,
7
}
8

9
impl<T> Logged<T> {
10
    fn new(value: T) -> Self {
11
        Logged { value, reads: Cell::new(0) }
12
    }
13
    fn read_count(&self) -> u32 {
14
        self.reads.get()
15
    }
16
}
17

18
impl<T> Deref for Logged<T> {
19
    type Target = T;
20
    fn deref(&self) -> &T {
21
        self.reads.set(self.reads.get() + 1); // Cell lets us mutate from &self
22
        &self.value
23
    }
24
}
25

26
impl<T> DerefMut for Logged<T> {
27
    fn deref_mut(&mut self) -> &mut T {
28
        &mut self.value
29
    }
30
}
31

32
fn main() {
33
    let logged = Logged::new(vec![1, 2, 3]);
34
    println!("len   = {}", logged.len()); // deref #1
35
    println!("first = {:?}", logged.first()); // deref #2
36
    let _sum: i32 = logged.iter().sum(); // deref #3
37
    println!("reads = {}", logged.read_count());
38

39
    let mut counter = Logged::new(0u32);
40
    *counter += 1; // DerefMut
41
    *counter += 1; // DerefMut
42
    println!("counter = {}", *counter);
43
}

Output:

1
len   = 3
2
first = Some(1)
3
reads = 3
4
counter = 2

Each method call on logged goes through deref once, so the counter lands on 3. DerefMut is what makes *counter += 1 legal — without it you would hit error[E0594]/E0596. Using Cell for the counter is the idiomatic way to mutate bookkeeping state from the &self signature deref requires.

Exercise 3: A guard that deref-coerces to its protected value

Difficulty: Intermediate / Advanced

Objective: Model the “RAII guard” shape (like MutexGuard or Ref) where a wrapper grants temporary access to an inner value via Deref/DerefMut and runs cleanup on drop.

Instructions: Define struct Resource { name: String, data: Vec<i32> }. Define struct Guard<'a>(&'a mut Resource) that borrows it. Implement Deref<Target = Resource> and DerefMut for Guard so callers can read and mutate the Resource through the guard. Implement Drop for Guard to print "released <name>". In main, acquire a guard, push to data through it (guard.data.push(...) works via DerefMut), read data.len(), then let the guard drop and observe the cleanup message.

Solution

1
use std::ops::{Deref, DerefMut};
2

3
struct Resource {
4
    name: String,
5
    data: Vec<i32>,
6
}
7

8
struct Guard<'a>(&'a mut Resource);
9

10
impl<'a> Deref for Guard<'a> {
11
    type Target = Resource;
12
    fn deref(&self) -> &Resource {
13
        self.0
14
    }
15
}
16

17
impl<'a> DerefMut for Guard<'a> {
18
    fn deref_mut(&mut self) -> &mut Resource {
19
        self.0
20
    }
21
}
22

23
impl<'a> Drop for Guard<'a> {
24
    fn drop(&mut self) {
25
        println!("released {}", self.0.name);
26
    }
27
}
28

29
impl Resource {
30
    fn acquire(&mut self) -> Guard<'_> {
31
        println!("acquired {}", self.name);
32
        Guard(self)
33
    }
34
}
35

36
fn main() {
37
    let mut resource = Resource {
38
        name: "db-pool".to_string(),
39
        data: vec![1, 2],
40
    };
41

42
    {
43
        let mut guard = resource.acquire();
44
        // DerefMut: reach Resource.data through the guard and mutate it.
45
        guard.data.push(3);
46
        guard.data.push(4);
47
        // Deref: read through the guard.
48
        println!("len while held = {}", guard.data.len());
49
    } // guard drops here -> "released db-pool"
50

51
    println!("final data = {:?}", resource.data);
52
}

Output:

1
acquired db-pool
2
len while held = 4
3
released db-pool
4
final data = [1, 2, 3, 4]

This is the exact shape of std::sync::MutexGuard and std::cell::RefMut: a short-lived handle that Derefs to the protected value and cleans up in Drop. The lifetime 'a ties the guard to the borrow of Resource, so the borrow checker guarantees the guard cannot outlive what it protects. Compare this with the guards returned by RefCell::borrow_mut and Mutex::lock in refcell-mutex.md.

The `Deref` Trait and Deref Coercion

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

What `Deref` actually is

Deref coercion: the automatic part

Why `&String` works where `&str` is expected

`DerefMut`: the mutable counterpart

How `Box` deref differs slightly

Key Differences

Where the `&String`/`&str` analogy breaks down

Common Pitfalls

Pitfall 1: Expecting deref coercion to satisfy a generic trait bound

Pitfall 2: Mutating through a wrapper that only implements `Deref`

Pitfall 3: Assuming operators like `==` use deref coercion

Pitfall 4: Using `Deref` as a substitute for inheritance

Best Practices

Real-World Example

Further Reading

Official documentation

Exercises

Exercise 1: A sentence newtype that acts like a `str`

Exercise 2: A read-counting smart pointer with `Deref` and `DerefMut`

Exercise 3: A guard that deref-coerces to its protected value

The Deref Trait and Deref Coercion

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

What Deref actually is

Deref coercion: the automatic part

Why &String works where &str is expected

DerefMut: the mutable counterpart

How Box deref differs slightly

Key Differences

Where the &String/&str analogy breaks down

Common Pitfalls

Pitfall 1: Expecting deref coercion to satisfy a generic trait bound

Pitfall 2: Mutating through a wrapper that only implements Deref

Pitfall 3: Assuming operators like == use deref coercion

Pitfall 4: Using Deref as a substitute for inheritance

Best Practices

Real-World Example

Further Reading

Official documentation

Related topics in this guide

Exercises

Exercise 1: A sentence newtype that acts like a str

Exercise 2: A read-counting smart pointer with Deref and DerefMut

Exercise 3: A guard that deref-coerces to its protected value

The `Deref` Trait and Deref Coercion

What `Deref` actually is

Why `&String` works where `&str` is expected

`DerefMut`: the mutable counterpart

How `Box` deref differs slightly

Where the `&String`/`&str` analogy breaks down

Pitfall 2: Mutating through a wrapper that only implements `Deref`

Pitfall 3: Assuming operators like `==` use deref coercion

Pitfall 4: Using `Deref` as a substitute for inheritance

Exercise 1: A sentence newtype that acts like a `str`

Exercise 2: A read-counting smart pointer with `Deref` and `DerefMut`