Item 6: Understand type conversions

In general, Rust does not perform automatic conversion between types. This includes integral types, even when the transformation is "safe":

        let x: u32 = 2;
        let y: u64 = x;
error[E0308]: mismatched types
  --> casts/src/main.rs:69:22
   |
69 |         let y: u64 = x;
   |                ---   ^ expected `u64`, found `u32`
   |                |
   |                expected due to this
   |
help: you can convert a `u32` to a `u64`
   |
69 |         let y: u64 = x.into();
   |                       +++++++

Rust type conversions fall into three categories:

  • manual: user-defined type conversions provided by implementing the From and Into traits
  • semi-automatic: explicit casts between values using the as keyword
  • automatic: implicit coercion into a new type.

The latter two don't apply to conversions of user defined types (with a couple of exceptions), so the majority of this Item will focus on manual conversion – which the compiler error message also pointed towards.

However, sections at the end of the Item discuss casting and coercion – including the exceptions where they can apply to a user-defined type.

User-Defined Type Conversions

As with other features of the language (Item 5) the ability to perform conversions between values of different user-defined types is encapsulated as a standard trait – or rather, as a set of related generic traits.

The four relevant traits that express the ability to convert values of a type are:

  • From<T>: Items of this type can be built from items of type T.
  • TryFrom<T>: Items of this type can sometimes be built from items of type T.
  • Into<T>: Items of this type can converted into items of type T.
  • TryInto<T>: Items of this type can sometimes be converted into items of type T.

Given the discussion in Item 1 about expressing things in the type system, it's no surprise to discover that the difference with the Try... variants is that the sole trait method returns a Result rather than a guaranteed new item. The Try... trait definitions also require an associated type that gives the type of the error E emitted for failure situations.

The first piece of advice is therefore to implement (just) the Try... trait if it's possible for a conversion to fail, in line with Item 4. The alternative is to ignore the possibility of error (e.g. with .unwrap()), but that needs to be a deliberate choice and in most cases it's best to leave that choice to the caller.

The type conversion traits have an obvious symmetry: if a type T can be transmuted into a type U, isn't that the same as it being possible to create an item of type U by transmutation from an item of type T?

This is indeed the case, and it leads to the second piece of advice: implement the From trait for conversions. The Rust standard library had to pick just one of the two possibilities, in order to prevent the system from spiralling around in dizzy circles1, and it came down on the side of automatically providing Into from a From implementation.

If you're consuming one of these two traits, as a trait bound on a new generic of your own, then the advice is reversed: use the Into trait for trait bounds. That way, the bound will be satisfied both by things that directly implement Into, and by things that only directly implement From.

This automatic conversion is highlighted by the documentation for From and Into, but it's worth reading the relevant part of the standard library code too, which is a blanket trait implementation:

impl<T, U> Into<U> for T
where
    U: From<T>,
{
    fn into(self) -> U {
        U::from(self)
    }
}

Translating a trait specification into words can help with understanding more complex trait bounds; in this case, it's fairly simple: "I can implement Into<U> for a type T whenever U already implements From<T>".

The standard library also includes various implementations of these conversion traits for standard library types. As you'd expect, there are From implementations for safe integral conversions (From<u32> for u64) and TryFrom implementations when the conversion isn't safe (TryFrom<u64> for u32).

There are also various other blanket trait implementations in addition to the Into version shown above, which you can find by searching for impl<T> From<T> for .... These are almost all for smart pointer types, allowing the smart pointer to be automatically constructed from an instance of the type that it holds, so that methods that accept smart pointer parameters can also be called with plain old items; more on this below and in Item 9.

The TryFrom trait also has a blanket implementation for any type that already implements the Into trait in the opposite direction – which automatically includes (as above) any type that implements From in the same direction. In other words, if you can infallibly convert a T into a U, you can also fallibly obtain a U from a T; as this conversion will always succeed, the associated error type is 2 the helpfully named Infallible.

There's also one very specific generic implementation of From that sticks out, the reflexive implementation:

impl<T> From<T> for T {
    fn from(t: T) -> T {
        t
    }
}

Translating into words, this just says that "given a T I can get a T". That's such an obvious "well, duh" that it's worth stopping to understand why this is useful.

Consider a simple newtype struct (Item 7) and a function that operates on it (ignoring that this function would be better expressed as a method):

#![allow(unused)]
fn main() {
/// Integer value from an IANA-controlled range.
#[derive(Clone, Copy, Debug)]
pub struct IanaAllocated(pub u64);

/// Indicate whether value is reserved.
pub fn is_iana_reserved(s: IanaAllocated) -> bool {
    s.0 == 0 || s.0 == 65535
}
}

This function can be invoked with instances of the struct

    let s = IanaAllocated(1);
    println!("{:?} reserved? {}", s, is_iana_reserved(s));
    // output: "IanaAllocated(1) reserved? false"

but even if From<u64> is implemented for the newtype wrapper

impl From<u64> for IanaAllocated {
    fn from(v: u64) -> Self {
        Self(v)
    }
}

the function can't be directly invoked for u64 values

error[E0308]: mismatched types
  --> casts/src/main.rs:82:29
   |
82 |         if is_iana_reserved(42) {
   |                             ^^ expected struct `IanaAllocated`, found integer

However, a generic version of the function that accepts (and explicitly converts) anything satisfying Into<IanaAllocated>:

    pub fn is_iana_reserved<T>(s: T) -> bool
    where
        T: Into<IanaAllocated>,
    {
        let s = s.into();
        s.0 == 0 || s.0 == 65535
    }

allows this use:

        if is_iana_reserved(42) {

With this trait bound in place, the reflexive trait implementation of From<T> makes more sense: it means that the generic function copes with items which are already IanaAllocated instances, no conversion needed.

This pattern also explains why (and how) Rust code sometimes appears to be doing implicit casts between types: the combination of From<T> implementations and Into<T> trait bounds leads to code that appears to magically convert at the call site (but which is still doing safe, explicit, conversions under the covers), This pattern becomes even more powerful when combined with reference types and their related conversion traits; more in Item 9.

Casts

Rust includes the as keyword to perform explicit casts between some pairs of types.

The pairs of types that can be converted in this way is a fairly limited set, and the only user-defined types it includes are "C-like" enums (those that have just an associated integer value). General integral conversions are included though, giving an alternative to into():

#![allow(unused)]
fn main() {
    let x: u32 = 9;
    let y = x as u64;
    let z: u64 = x.into();
}

The as version also allows lossy conversions3:

#![allow(unused)]
fn main() {
    let x: u32 = 9;
    let y = x as u16;
}

which would be rejected by the from / into versions:

error[E0277]: the trait bound `u16: From<u32>` is not satisfied
   --> casts/src/main.rs:124:20
    |
124 |     let y: u16 = x.into();
    |                    ^^^^ the trait `From<u32>` is not implemented for `u16`
    |
    = help: the following implementations were found:
              <u16 as From<NonZeroU16>>
              <u16 as From<bool>>
              <u16 as From<u8>>
              <f32 as From<i16>>
            and 71 others
    = note: required because of the requirements on the impl of `Into<u16>` for `u32`

For consistency and safety you should prefer from / into conversions to as casts, unless you understand and need the precise casting semantics (e.g for C interoperability).

Coercion

The explicit as casts described in the previous section are a superset of the implicit coercions that the compiler will silently perform: any coercion can be forced with an explicit as, but the converse is not true. In particular, the integral conversions performed in the previous section are not coercions, and so will always require as.

Most of the coercions involve silent conversions of pointer and reference types in ways that are sensible and convenient for the programmer, such as:

  • converting a mutable reference to a non-mutable references (so you can use a &mut T as the argument to a function that takes a &T)
  • converting a reference to a raw pointer (this isn't unsafe – the unsafety happens at the point where you're foolish enough to use a raw pointer)
  • converting a closure that happens not to capture any variables into a bare function pointer (Item 2)
  • converting an array to a slice
  • converting a concrete item to a trait object, for a trait that the concrete item implements
  • converting4 an item lifetime to a "shorter" one (Item 14).

There are only two coercions whose behaviour can be affected by user-defined types. The first of these is when a user-defined type implements the Deref or the DerefMut trait. These traits indicate that the user defined type is acting as a smart pointer of some sort (Item 9), and in this case the compiler will coerce a reference to the smart pointer item into being a reference to an item of the type that the smart pointer contains (indicated by its Target).

The second coercion of a user-defined type happens when a concrete item is converted to a trait object. This operation builds a fat pointer to the item; this pointer is fat because it includes both a pointer to the item's location in memory, together with a pointer to the vtable for the concrete type's implementation of the trait – see Item 9.


1: More properly known as the trait coherence rules.

2: For now – this is likely to be replaced with the ! "never" type in a future version of Rust.

3: Allowing lossy conversions in Rust was probably a mistake, and there have been discussions around trying to remove this behaviour.

4: Rust refers to these conversions as "subtyping", but it's quite different that the definition of "subtyping" used in object-oriented languages.