impl Trait for returning complex types with ease

Minimum Rust version: 1.26

impl Trait is the new way to specify unnamed but concrete types that implement a specific trait. There are two places you can put it: argument position, and return position.

trait Trait {}

// argument position
fn foo(arg: impl Trait) {
}

// return position
fn foo() -> impl Trait {
}

Argument Position

In argument position, this feature is quite simple. These two forms are almost the same:

trait Trait {}

fn foo<T: Trait>(arg: T) {
}

fn foo(arg: impl Trait) {
}

That is, it's a slightly shorter syntax for a generic type parameter. It means, "arg is an argument that takes any type that implements the Trait trait."

However, there's also an important technical difference between T: Trait and impl Trait here. When you write the former, you can specify the type of T at the call site with turbo-fish syntax as with foo::<usize>(1). In the case of impl Trait, if it is used anywhere in the function definition, then you can't use turbo-fish at all. Therefore, you should be mindful that changing both from and to impl Trait can constitute a breaking change for the users of your code.

Return Position

In return position, this feature is more interesting. It means "I am returning some type that implements the Trait trait, but I'm not going to tell you exactly what the type is." Before impl Trait, you could do this with trait objects:


# #![allow(unused_variables)]
#fn main() {
trait Trait {}

impl Trait for i32 {}

fn returns_a_trait_object() -> Box<dyn Trait> {
    Box::new(5)
}
#}

However, this has some overhead: the Box<T> means that there's a heap allocation here, and this will use dynamic dispatch. See the dyn Trait section for an explanation of this syntax. But we only ever return one possible thing here, the Box<i32>. This means that we're paying for dynamic dispatch, even though we don't use it!

With impl Trait, the code above could be written like this:


# #![allow(unused_variables)]
#fn main() {
trait Trait {}

impl Trait for i32 {}

fn returns_a_trait_object() -> impl Trait {
    5
}
#}

Here, we have no Box<T>, no trait object, and no dynamic dispatch. But we still can obscure the i32 return type.

With i32, this isn't super useful. But there's one major place in Rust where this is much more useful: closures.

impl Trait and closures

If you need to catch up on closures, check out their chapter in the book.

In Rust, closures have a unique, un-writable type. They do implement the Fn family of traits, however. This means that previously, the only way to return a closure from a function was to use a trait object:


# #![allow(unused_variables)]
#fn main() {
fn returns_closure() -> Box<dyn Fn(i32) -> i32> {
    Box::new(|x| x + 1)
}
#}

You couldn't write the type of the closure, only use the Fn trait. That means that the trait object is necessary. However, with impl Trait:


# #![allow(unused_variables)]
#fn main() {
fn returns_closure() -> impl Fn(i32) -> i32 {
    |x| x + 1
}
#}

We can now return closures by value, just like any other type!

More details

The above is all you need to know to get going with impl Trait, but for some more nitty-gritty details: type parameters and impl Trait in argument position are universals (universally quantified types). Meanwhile, impl Trait in return position are existentials (existentially quantified types). Okay, maybe that's a bit too jargon-heavy. Let's step back.

Consider this function:

fn foo<T: Trait>(x: T) {

When you call it, you set the type, T. "you" being the caller here. This signature says "I accept any type that implements Trait." ("any type" == universal in the jargon)

This version:

fn foo<T: Trait>() -> T {

is similar, but also different. You, the caller, provide the type you want, T, and then the function returns it. You can see this in Rust today with things like parse or collect:

let x: i32 = "5".parse()?;
let x: u64 = "5".parse()?;

Here, .parse has this signature:

pub fn parse<F>(&self) -> Result<F, <F as FromStr>::Err> where
    F: FromStr,

Same general idea, though with a result type and FromStr has an associated type... anyway, you can see how F is in the return position here. So you have the ability to choose.

With impl Trait, you're saying "hey, some type exists that implements this trait, but I'm not gonna tell you what it is." ("existential" in the jargon, "some type exists"). So now, the caller can't choose, and the function itself gets to choose. If we tried to define parse with Result<impl F,... as the return type, it wouldn't work.

Using impl Trait in more places

As previously mentioned, as a start, you will only be able to use impl Trait as the argument or return type of a free or inherent function. However, impl Trait can't be used inside implementations of traits, nor can it be used as the type of a let binding or inside a type alias. Some of these restrictions will eventually be lifted. For more information, see the tracking issue on impl Trait.