1. 1. Introduction
  2. 2. Getting Started
  3. 3. Tutorial: Guessing Game
  4. 4. Syntax and Semantics
    1. 4.1. Variable Bindings
    2. 4.2. Functions
    3. 4.3. Primitive Types
    4. 4.4. Comments
    5. 4.5. if
    6. 4.6. Loops
    7. 4.7. Vectors
    8. 4.8. Ownership
    9. 4.9. References and Borrowing
    10. 4.10. Lifetimes
    11. 4.11. Mutability
    12. 4.12. Structs
    13. 4.13. Enums
    14. 4.14. Match
    15. 4.15. Patterns
    16. 4.16. Method Syntax
    17. 4.17. Strings
    18. 4.18. Generics
    19. 4.19. Traits
    20. 4.20. Drop
    21. 4.21. if let
    22. 4.22. Trait Objects
    23. 4.23. Closures
    24. 4.24. Universal Function Call Syntax
    25. 4.25. Crates and Modules
    26. 4.26. `const` and `static`
    27. 4.27. Attributes
    28. 4.28. `type` aliases
    29. 4.29. Casting between types
    30. 4.30. Associated Types
    31. 4.31. Unsized Types
    32. 4.32. Operators and Overloading
    33. 4.33. Deref coercions
    34. 4.34. Macros
    35. 4.35. Raw Pointers
    36. 4.36. `unsafe`
  5. 5. Effective Rust
    1. 5.1. The Stack and the Heap
    2. 5.2. Testing
    3. 5.3. Conditional Compilation
    4. 5.4. Documentation
    5. 5.5. Iterators
    6. 5.6. Concurrency
    7. 5.7. Error Handling
    8. 5.8. Choosing your Guarantees
    9. 5.9. FFI
    10. 5.10. Borrow and AsRef
    11. 5.11. Release Channels
    12. 5.12. Using Rust without the standard library
  6. 6. Nightly Rust
    1. 6.1. Compiler Plugins
    2. 6.2. Inline Assembly
    3. 6.3. No stdlib
    4. 6.4. Intrinsics
    5. 6.5. Lang items
    6. 6.6. Advanced linking
    7. 6.7. Benchmark Tests
    8. 6.8. Box Syntax and Patterns
    9. 6.9. Slice Patterns
    10. 6.10. Associated Constants
    11. 6.11. Custom Allocators
  7. 7. Glossary
  8. 8. Syntax Index
  9. 9. Bibliography

Traits

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

Recall the impl keyword, used to call a function with method syntax:

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

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

Traits are similar, except that we first define a trait with a method signature, then implement the trait for a type. In this example, we implement the trait HasArea for Circle:

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)
    }
}Run

As you can see, the trait block looks very similar to the impl block, but we don’t define a body, only a type signature. When we impl a trait, we use impl Trait for Item, rather than only impl Item.

Self may be used in a type annotation to refer to an instance of the type implementing this trait passed as a parameter. Self, &Self or &mut Self may be used depending on the level of ownership required.

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

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

    fn is_larger(&self, &Self) -> bool;
}

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

    fn is_larger(&self, other: &Self) -> bool {
        self.area() > other.area()
    }
}Run

Trait bounds on generic functions

Traits are useful because they allow a type to make certain promises about its behavior. Generic functions can exploit this to constrain, or bound, the types they accept. Consider this function, which does not compile:

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

Rust complains:

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

Because T can be any type, we can’t be sure that it implements the area method. But we can add a trait bound to our generic T, ensuring that it does:

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

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 will 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);
}Run

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:

print_area(5);Run

We get a compile-time error:

error: the trait bound `_ : HasArea` is not satisfied [E0277]

Trait bounds on generic structs

Your generic structs can also benefit from trait bounds. All you need to do is append the bound when you declare type parameters. Here is a new type Rectangle<T> and its operation is_square():

struct Rectangle<T> {
    x: T,
    y: T,
    width: T,
    height: T,
}

impl<T: PartialEq> Rectangle<T> {
    fn is_square(&self) -> bool {
        self.width == self.height
    }
}

fn main() {
    let mut r = Rectangle {
        x: 0,
        y: 0,
        width: 47,
        height: 47,
    };

    assert!(r.is_square());

    r.height = 42;
    assert!(!r.is_square());
}Run

is_square() needs to check that the sides are equal, so the sides must be of a type that implements the core::cmp::PartialEq trait:

impl<T: PartialEq> Rectangle<T> { ... }Run

Now, a rectangle can be defined in terms of any type that can be compared for equality.

Here we defined a new struct Rectangle that accepts numbers of any precision—really, objects of pretty much any type—as long as they can be compared for equality. Could we do the same for our HasArea structs, Square and Circle? Yes, but they need multiplication, and to work with that we need to know more about operator traits.

Rules for implementing traits

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 for i32:

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

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

        *self as f64
    }
}

5.area();Run

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 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 trait which adds extra functionality to Files, for doing file I/O. By default, a File won’t have its methods:

let mut f = std::fs::File::create("foo.txt").expect("Couldn’t create foo.txt");
let buf = b"whatever"; // byte string literal. buf: &[u8; 8]
let result = f.write(buf);Run

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 the Write trait first:

use std::io::Write;

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

This will compile without error.

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

There’s one more restriction on implementing traits: either the trait or the type you’re implementing it for must be defined by you. Or more precisely, one of them must be defined in the same crate as the impl you're writing. For more on Rust's module and package system, see the chapter on crates and modules.

So, we could implement the HasArea type for i32, because we defined HasArea in our code. But if we tried to implement ToString, a trait provided by Rust, for i32, we could not, because neither the trait nor the type are defined in our crate.

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 foo<T: Clone>(x: T) {
    x.clone();
}Run

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

use std::fmt::Debug;

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

T now needs to be both Clone as well as Debug.

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:

use std::fmt::Debug;

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

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 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");
}Run

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

use std::fmt::Debug;

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

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

This flexibility can add clarity in complex situations.

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

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>(x: i32) -> T
        // this is using ConvertTo as if it were "ConvertTo<i64>"
        where i32: ConvertTo<T> {
    x.convert()
}Run

This shows off the additional feature of where clauses: they allow bounds on the left-hand side not only of type parameters T, but also of types (i32 in this case). In this example, i32 must implement ConvertTo<T>. Rather than defining what i32 is (since that's obvious), the where clause here constrains T.

Default methods

A default method can be added to a trait definition if it is already known how a typical implementor will define a method. For example, is_invalid() is defined as the opposite of is_valid():

trait Foo {
    fn is_valid(&self) -> bool;

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

Implementors of the Foo trait need to implement is_valid() but not is_invalid() due to the added default behavior. This default behavior can still be overridden as in:

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 // overrides the expected value of is_invalid()
    }
}

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

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

Inheritance

Sometimes, implementing a trait requires implementing another trait:

trait Foo {
    fn foo(&self);
}

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

Implementors of FooBar must also implement Foo, like this:

struct Baz;

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

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

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

error: the trait bound `main::Baz : main::Foo` is not satisfied [E0277]

Deriving

Implementing traits like Debug and Default repeatedly can become quite tedious. For that reason, Rust provides an attribute that allows you to let Rust automatically implement traits for you:

#[derive(Debug)]
struct Foo;

fn main() {
    println!("{:?}", Foo);
}Run

However, deriving is limited to a certain set of traits: