Deref coercions

The standard library provides a special trait, Deref. It’s normally used to overload *, the dereference operator:

use std::ops::Deref;

struct DerefExample<T> {
    value: T,
}

impl<T> Deref for DerefExample<T> {
    type Target = T;

    fn deref(&self) -> &T {
        &self.value
    }
}

fn main() {
    let x = DerefExample { value: 'a' };
    assert_eq!('a', *x);
}

This is useful for writing custom pointer types. However, there’s a language feature related to Deref: ‘deref coercions’. Here’s the rule: If you have a type U, and it implements Deref<Target=T>, values of &U will automatically coerce to a &T. Here’s an example:

# #![allow(unused_variables)]
#fn main() {
fn foo(s: &str) {
    // Borrow a string for a second.
}

// String implements Deref<Target=str>.
let owned = "Hello".to_string();

// Therefore, this works:
foo(&owned);
#}

Using an ampersand in front of a value takes a reference to it. So owned is a String, &owned is an &String, and since impl Deref<Target=str> for String, &String will deref to &str, which foo() takes.

That’s it. This rule is one of the only places in which Rust does an automatic conversion for you, but it adds a lot of flexibility. For example, the Rc<T> type implements Deref<Target=T>, so this works:

# #![allow(unused_variables)]
#fn main() {
use std::rc::Rc;

fn foo(s: &str) {
    // Borrow a string for a second.
}

// String implements Deref<Target=str>.
let owned = "Hello".to_string();
let counted = Rc::new(owned);

// Therefore, this works:
foo(&counted);
#}

All we’ve done is wrap our String in an Rc<T>. But we can now pass the Rc<String> around anywhere we’d have a String. The signature of foo didn’t change, but works just as well with either type. This example has two conversions: &Rc<String> to &String and then &String to &str. Rust will do this as many times as possible until the types match.

Another very common implementation provided by the standard library is:

# #![allow(unused_variables)]
#fn main() {
fn foo(s: &[i32]) {
    // Borrow a slice for a second.
}

// Vec<T> implements Deref<Target=[T]>.
let owned = vec![1, 2, 3];

foo(&owned);
#}

Vectors can Deref to a slice.

Deref and method calls

Deref will also kick in when calling a method. Consider the following example.

# #![allow(unused_variables)]
#fn main() {
struct Foo;

impl Foo {
    fn foo(&self) { println!("Foo"); }
}

let f = &&Foo;

f.foo();
#}

Even though f is a &&Foo and foo takes &self, this works. That’s because these things are the same:

f.foo();
(&f).foo();
(&&f).foo();
(&&&&&&&&f).foo();

A value of type &&&&&&&&&&&&&&&&Foo can still have methods defined on Foo called, because the compiler will insert as many * operations as necessary to get it right. And since it’s inserting *s, that uses Deref.