Traits

A trait is a language feature that tells the Rust compiler about functionality a type must provide.

Do you remember the impl`impl` keyword, used to call a function with method syntax?

fn main() { struct Circle { x: f64, y: f64, radius: f64, } impl Circle { fn area(&self) -> f64 { std::f64::consts::PI * (self.radius * self.radius) } } }
struct Circle {
    x: f64,
    y: f64,
    radius: f64,
}

impl Circle {
    fn area(&self) -> f64 {
        std::f64::consts::PI * (self.radius * self.radius)
    }
}

Traits are similar, except that we define a trait with just the method signature, then implement the trait for that struct. Like this:

fn main() { struct Circle { x: f64, y: f64, radius: f64, } trait HasArea { fn area(&self) -> f64; } impl HasArea for Circle { fn area(&self) -> f64 { std::f64::consts::PI * (self.radius * self.radius) } } }
struct Circle {
    x: f64,
    y: f64,
    radius: f64,
}

trait HasArea {
    fn area(&self) -> f64;
}

impl HasArea for Circle {
    fn area(&self) -> f64 {
        std::f64::consts::PI * (self.radius * self.radius)
    }
}

As you can see, the trait`traitblock looks very similar to theimplblock, but we don’t define a body, just a type signature. When weimpla trait, we useimpl Trait for Item, rather than justimpl Item`.

We can use traits to constrain our generics. Consider this function, which does not compile:

fn main() { fn print_area<T>(shape: T) { println!("This shape has an area of {}", shape.area()); } }
fn print_area<T>(shape: T) {
    println!("This shape has an area of {}", shape.area());
}

Rust complains:

error: no method named `area` found for type `T` in the current scope

Because T`Tcan be any type, we can’t be sure that it implements theareamethod. But we can add a ‘trait constraint’ to our genericT`, ensuring that it does:

fn main() { trait HasArea { fn area(&self) -> f64; } fn print_area<T: HasArea>(shape: T) { println!("This shape has an area of {}", shape.area()); } }
fn print_area<T: HasArea>(shape: T) {
    println!("This shape has an area of {}", shape.area());
}

The syntax <T: HasArea> means any type that implements the HasArea trait. Because traits define function type signatures, we can be sure that any type which implements HasArea`HasAreawill have an.area()` method.

Here’s an extended example of how this works:

trait HasArea { fn area(&self) -> f64; } struct Circle { x: f64, y: f64, radius: f64, } impl HasArea for Circle { fn area(&self) -> f64 { std::f64::consts::PI * (self.radius * self.radius) } } struct Square { x: f64, y: f64, side: f64, } impl HasArea for Square { fn area(&self) -> f64 { self.side * self.side } } fn print_area<T: HasArea>(shape: T) { println!("This shape has an area of {}", shape.area()); } fn main() { let c = Circle { x: 0.0f64, y: 0.0f64, radius: 1.0f64, }; let s = Square { x: 0.0f64, y: 0.0f64, side: 1.0f64, }; print_area(c); print_area(s); }
trait HasArea {
    fn area(&self) -> f64;
}

struct Circle {
    x: f64,
    y: f64,
    radius: f64,
}

impl HasArea for Circle {
    fn area(&self) -> f64 {
        std::f64::consts::PI * (self.radius * self.radius)
    }
}

struct Square {
    x: f64,
    y: f64,
    side: f64,
}

impl HasArea for Square {
    fn area(&self) -> f64 {
        self.side * self.side
    }
}

fn print_area<T: HasArea>(shape: T) {
    println!("This shape has an area of {}", shape.area());
}

fn main() {
    let c = Circle {
        x: 0.0f64,
        y: 0.0f64,
        radius: 1.0f64,
    };

    let s = Square {
        x: 0.0f64,
        y: 0.0f64,
        side: 1.0f64,
    };

    print_area(c);
    print_area(s);
}

This program outputs:

This shape has an area of 3.141593
This shape has an area of 1

As you can see, print_area is now generic, but also ensures that we have passed in the correct types. If we pass in an incorrect type:

fn main() { print_area(5); }
print_area(5);

We get a compile-time error:

error: the trait `HasArea` is not implemented for the type `_` [E0277]

So far, we’ve only added trait implementations to structs, but you can implement a trait for any type. So technically, we could implement HasArea`HasAreafor` for i32`i32`:

fn main() { trait HasArea { fn area(&self) -> f64; } impl HasArea for i32 { fn area(&self) -> f64 { println!("this is silly"); *self as f64 } } 5.area(); }
trait HasArea {
    fn area(&self) -> f64;
}

impl HasArea for i32 {
    fn area(&self) -> f64 {
        println!("this is silly");

        *self as f64
    }
}

5.area();

It is considered poor style to implement methods on such primitive types, even though it is possible.

This may seem like the Wild West, but there are two other restrictions around implementing traits that prevent this from getting out of hand. The first is that if the trait isn’t defined in your scope, it doesn’t apply. Here’s an example: the standard library provides a Write`Write` trait which adds extra functionality to File`Files, for doing file I/O. By default, aFile` won’t have its methods:

fn main() { let mut f = std::fs::File::open("foo.txt").ok().expect("Couldn’t open foo.txt"); let buf = b"whatever"; // byte string literal. buf: &[u8; 8] let result = f.write(buf); result.unwrap(); // ignore the error }
let mut f = std::fs::File::open("foo.txt").ok().expect("Couldn’t open foo.txt");
let buf = b"whatever"; // byte string literal. buf: &[u8; 8]
let result = f.write(buf);

Here’s the error:

error: type `std::fs::File` does not implement any method in scope named `write`
let result = f.write(buf);
               ^~~~~~~~~~

We need to use`usethe` the Write`Write` trait first:

fn main() { use std::io::Write; let mut f = std::fs::File::open("foo.txt").ok().expect("Couldn’t open foo.txt"); let buf = b"whatever"; let result = f.write(buf); result.unwrap(); // ignore the error }
use std::io::Write;

let mut f = std::fs::File::open("foo.txt").ok().expect("Couldn’t open foo.txt");
let buf = b"whatever";
let result = f.write(buf);

This will compile without error.

This means that even if someone does something bad like add methods to i32`i32, it won’t affect you, unless youuse` that trait.

There’s one more restriction on implementing traits: either the trait, or the type you’re writing the impl`implfor, must be defined by you. So, we could implement theHasAreatype for` type for i32`i32, becauseHasAreais in our code. But if we tried to implementToString, a trait provided by Rust, fori32`, we could not, because neither the trait nor the type are in our code.

One last thing about traits: generic functions with a trait bound use ‘monomorphization’ (mono: one, morph: form), so they are statically dispatched. What’s that mean? Check out the chapter on trait objects for more details.

Multiple trait bounds

You’ve seen that you can bound a generic type parameter with a trait:

fn main() { fn foo<T: Clone>(x: T) { x.clone(); } }
fn foo<T: Clone>(x: T) {
    x.clone();
}

If you need more than one bound, you can use +`+`:

fn main() { use std::fmt::Debug; fn foo<T: Clone + Debug>(x: T) { x.clone(); println!("{:?}", x); } }
use std::fmt::Debug;

fn foo<T: Clone + Debug>(x: T) {
    x.clone();
    println!("{:?}", x);
}

T`Tnow needs to be bothCloneas well asDebug`.

Where clause

Writing functions with only a few generic types and a small number of trait bounds isn’t too bad, but as the number increases, the syntax gets increasingly awkward:

fn main() { use std::fmt::Debug; fn foo<T: Clone, K: Clone + Debug>(x: T, y: K) { x.clone(); y.clone(); println!("{:?}", y); } }
use std::fmt::Debug;

fn foo<T: Clone, K: Clone + Debug>(x: T, y: K) {
    x.clone();
    y.clone();
    println!("{:?}", y);
}

The name of the function is on the far left, and the parameter list is on the far right. The bounds are getting in the way.

Rust has a solution, and it’s called a ‘where`where` clause’:

use std::fmt::Debug; fn foo<T: Clone, K: Clone + Debug>(x: T, y: K) { x.clone(); y.clone(); println!("{:?}", y); } fn bar<T, K>(x: T, y: K) where T: Clone, K: Clone + Debug { x.clone(); y.clone(); println!("{:?}", y); } fn main() { foo("Hello", "world"); bar("Hello", "world"); }
use std::fmt::Debug;

fn foo<T: Clone, K: Clone + Debug>(x: T, y: K) {
    x.clone();
    y.clone();
    println!("{:?}", y);
}

fn bar<T, K>(x: T, y: K) where T: Clone, K: Clone + Debug {
    x.clone();
    y.clone();
    println!("{:?}", y);
}

fn main() {
    foo("Hello", "world");
    bar("Hello", "world");
}

foo()`foo()uses the syntax we showed earlier, andbar()uses a` uses a where`whereclause. All you need to do is leave off the bounds when defining your type parameters, and then addwhere` after the parameter list. For longer lists, whitespace can be added:

fn main() { use std::fmt::Debug; fn bar<T, K>(x: T, y: K) where T: Clone, K: Clone + Debug { x.clone(); y.clone(); println!("{:?}", y); } }
use std::fmt::Debug;

fn bar<T, K>(x: T, y: K)
    where T: Clone,
          K: Clone + Debug {

    x.clone();
    y.clone();
    println!("{:?}", y);
}

This flexibility can add clarity in complex situations.

where`where` is also more powerful than the simpler syntax. For example:

fn main() { trait ConvertTo<Output> { fn convert(&self) -> Output; } impl ConvertTo<i64> for i32 { fn convert(&self) -> i64 { *self as i64 } } // can be called with T == i32 fn normal<T: ConvertTo<i64>>(x: &T) -> i64 { x.convert() } // can be called with T == i64 fn inverse<T>() -> T // this is using ConvertTo as if it were "ConvertFrom<i32>" where i32: ConvertTo<T> { 42.convert() } }
trait ConvertTo<Output> {
    fn convert(&self) -> Output;
}

impl ConvertTo<i64> for i32 {
    fn convert(&self) -> i64 { *self as i64 }
}

// can be called with T == i32
fn normal<T: ConvertTo<i64>>(x: &T) -> i64 {
    x.convert()
}

// can be called with T == i64
fn inverse<T>() -> T
        // this is using ConvertTo as if it were "ConvertFrom<i32>"
        where i32: ConvertTo<T> {
    42.convert()
}

This shows off the additional feature of where`whereclauses: they allow bounds where the left-hand side is an arbitrary type (i32in this case), not just a plain type parameter (likeT`).

Default methods

There’s one last feature of traits we should cover: default methods. It’s easiest just to show an example:

fn main() { trait Foo { fn is_valid(&self) -> bool; fn is_invalid(&self) -> bool { !self.is_valid() } } }
trait Foo {
    fn is_valid(&self) -> bool;

    fn is_invalid(&self) -> bool { !self.is_valid() }
}

Implementors of the Foo`Footrait need to implementis_valid(), but they don’t need to implementis_invalid()`. They’ll get this default behavior. They can override the default if they so choose:

fn main() { trait Foo { fn is_valid(&self) -> bool; fn is_invalid(&self) -> bool { !self.is_valid() } } struct UseDefault; impl Foo for UseDefault { fn is_valid(&self) -> bool { println!("Called UseDefault.is_valid."); true } } struct OverrideDefault; impl Foo for OverrideDefault { fn is_valid(&self) -> bool { println!("Called OverrideDefault.is_valid."); true } fn is_invalid(&self) -> bool { println!("Called OverrideDefault.is_invalid!"); true // this implementation is a self-contradiction! } } let default = UseDefault; assert!(!default.is_invalid()); // prints "Called UseDefault.is_valid." let over = OverrideDefault; assert!(over.is_invalid()); // prints "Called OverrideDefault.is_invalid!" }
struct UseDefault;

impl Foo for UseDefault {
    fn is_valid(&self) -> bool {
        println!("Called UseDefault.is_valid.");
        true
    }
}

struct OverrideDefault;

impl Foo for OverrideDefault {
    fn is_valid(&self) -> bool {
        println!("Called OverrideDefault.is_valid.");
        true
    }

    fn is_invalid(&self) -> bool {
        println!("Called OverrideDefault.is_invalid!");
        true // this implementation is a self-contradiction!
    }
}

let default = UseDefault;
assert!(!default.is_invalid()); // prints "Called UseDefault.is_valid."

let over = OverrideDefault;
assert!(over.is_invalid()); // prints "Called OverrideDefault.is_invalid!"

Inheritance

Sometimes, implementing a trait requires implementing another trait:

fn main() { trait Foo { fn foo(&self); } trait FooBar : Foo { fn foobar(&self); } }
trait Foo {
    fn foo(&self);
}

trait FooBar : Foo {
    fn foobar(&self);
}

Implementors of FooBar`FooBarmust also implementFoo`, like this:

fn main() { trait Foo { fn foo(&self); } trait FooBar : Foo { fn foobar(&self); } struct Baz; impl Foo for Baz { fn foo(&self) { println!("foo"); } } impl FooBar for Baz { fn foobar(&self) { println!("foobar"); } } }
struct Baz;

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

impl FooBar for Baz {
    fn foobar(&self) { println!("foobar"); }
}

If we forget to implement Foo`Foo`, Rust will tell us:

error: the trait `main::Foo` is not implemented for the type `main::Baz` [E0277]