Trait Deref

pub trait Deref {
    type Target: ?Sized;

    // Required method
    fn deref(&self) -> &Self::Target;
}

Used for immutable dereferencing operations, like *v.

In addition to being used for explicit dereferencing operations with the (unary) * operator in immutable contexts, Deref is also used implicitly by the compiler in many circumstances. This mechanism is called “Deref coercion”. In mutable contexts, DerefMut is used and mutable deref coercion similarly occurs.

Warning: Deref coercion is a powerful language feature which has far-reaching implications for every type that implements Deref. The compiler will silently insert calls to Deref::deref. For this reason, one should be careful about implementing Deref and only do so when deref coercion is desirable. See below for advice on when this is typically desirable or undesirable.

Types that implement Deref or DerefMut are often called “smart pointers” and the mechanism of deref coercion has been specifically designed to facilitate the pointer-like behaviour that name suggests. Often, the purpose of a “smart pointer” type is to change the ownership semantics of a contained value (for example, Rc or Cow) or the storage semantics of a contained value (for example, Box).

Deref coercion

If T implements Deref<Target = U>, and v is a value of type T, then:

• In immutable contexts, *v (where T is neither a reference nor a raw pointer) is equivalent to *Deref::deref(&v).
• Values of type &T are coerced to values of type &U
• T implicitly implements all the methods of the type U which take the &self receiver.

For more details, visit the chapter in The Rust Programming Language as well as the reference sections on the dereference operator, method resolution, and type coercions.

When to implement Deref or DerefMut

The same advice applies to both deref traits. In general, deref traits should be implemented if:

1. a value of the type transparently behaves like a value of the target type;
2. the implementation of the deref function is cheap; and
3. users of the type will not be surprised by any deref coercion behaviour.

In general, deref traits should not be implemented if:

1. the deref implementations could fail unexpectedly; or
2. the type has methods that are likely to collid