Traits — The basics

trait Describe {
    fn describe(&self) -> String;
}

struct Dog { name: String }
struct Car { model: String }

impl Describe for Dog {
    fn describe(&self) -> String { format!("the dog {}", self.name) }
}

impl Describe for Car {
    fn describe(&self) -> String { format!("a {}", self.model) }
}

fn introduce(x: &impl Describe) {
    println!("Here is {}", x.describe());
}

trait Shape {
    // Method to implement: only the signature
    fn area(&self) -> f64;

    // Method that modifies
    fn scale(&mut self, factor: f64);

    // Associated function (no self): a common constructor
    fn unit() -> Self where Self: Sized;

    // Associated constant
    const SIDES: u32;

    // Default method (section 4)
    fn description(&self) -> String {
        format!("shape with {} sides, area {:.2}", Self::SIDES, self.area())
    }
}

struct Square { side: f64 }

impl Shape for Square {
    fn area(&self) -> f64 { self.side * self.side }
    fn scale(&mut self, factor: f64) { self.side *= factor; }
    fn unit() -> Self { Square { side: 1.0 } }
    const SIDES: u32 = 4;
    // description is not written: the default version applies
}

fn main() {
    let mut c = Square::unit();
    c.scale(3.0);
    println!("{}", c.description());   // shape with 4 sides, area 9.00
}

impl Square {
    fn diagonal(&self) -> f64 { self.side * 2f64.sqrt() }   // method specific to Square
}

impl Shape for Square {
    // only the items declared by the trait: area, scale, unit, SIDES
    // (and possibly description, to replace the default version)
}

You cannot add an extra method inside an impl Trait for Type: it goes in impl Type.

trait Summary {
    fn author(&self) -> String;

    fn summary(&self) -> String {
        format!("(Read more from {}…)", self.author())
    }
}

struct Tweet { user: String, text: String }

impl Summary for Tweet {
    fn author(&self) -> String { format!("@{}", self.user) }
    // summary is provided
}

The trait asks for the minimum (author) and builds the rest. This is the principle of Iterator: you write next, you get map, filter, sum and 70 other methods.

struct Article { title: String, author: String }

impl Summary for Article {
    fn author(&self) -> String { self.author.clone() }
    fn summary(&self) -> String {                      // replaces the default version
        format!("{}, by {}", self.title, self.author)
    }
}

An implementation that replaces the default method cannot call the default version (there is no super). To reuse it, put it in a free function that both call.

// 1. impl Trait
fn notify_v1(x: &impl Summary) {
    println!("{}", x.summary());
}

// 2. Generic with a bound
fn notify_v2<T: Summary>(x: &T) {
    println!("{}", x.summary());
}

// 3. where
fn notify_v3<T>(x: &T)
where
    T: Summary,
{
    println!("{}", x.summary());
}

// 4. Trait object: a single compiled copy, choice at runtime
fn notify_v4(x: &dyn Summary) {
    println!("{}", x.summary());
}

The first three are equivalent (generics, see generics). The fourth is dynamic (see box-dynamiques).

use std::fmt::Display;

fn show_summary(x: &(impl Summary + Display)) {
    println!("{x}: {}", x.summary());
}

fn show_summary2<T: Summary + Display>(x: &T) {
    println!("{x}: {}", x.summary());
}

fn create() -> impl Summary {
    Tweet { user: "rust".into(), text: "1.0".into() }
}

impl Summary as a return type hides the concrete type, but it must be unique:

// fn create(short: bool) -> impl Summary {
//     if short { Tweet { .. } } else { Article { .. } }    // ERROR: two different types
// }

fn create_dyn(short: bool) -> Box<dyn Summary> {
    if short {
        Box::new(Tweet { user: "a".into(), text: "b".into() })
    } else {
        Box::new(Article { title: "t".into(), author: "a".into() })
    }
}

trait Zero {
    fn zero() -> Self;
}

impl Zero for u32 { fn zero() -> Self { 0 } }

fn fill<T: Zero>(n: usize) -> Vec<T> {
    (0..n).map(|_| T::zero()).collect()        // T::f(): associated function of the generic type
}

let v: Vec<u32> = fill(3);

mod shapes {
    pub trait Area { fn area(&self) -> f64; }
    impl Area for f64 { fn area(&self) -> f64 { self * self } }
}

fn main() {
    let x = 2.0_f64;
    // x.area();                 // ERROR: no method named `area` found
    use shapes::Area;            // the trait must be in scope
    x.area();
}

#[derive(Debug, Clone, PartialEq, Default)]
struct Point { x: i32, y: i32 }

use std::fmt;

struct Credentials { user: String, password: String }

impl fmt::Debug for Credentials {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Credentials")
            .field("user", &self.user)
            .field("password", &"***")
            .finish()
    }
}

A #[derive(Debug)] would print the password in the logs at the first {:?} or the first dbg!.

use std::fmt;

struct Price { cents: i64 }

impl fmt::Display for Price {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}.{:02} €", self.cents / 100, self.cents % 100)
    }
}

let p = Price { cents: 1250 };
println!("{p}");                 // 12.50 €
let text = p.to_string();        // provided by Display

struct Code(&'static str);

impl fmt::Display for Code {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.pad(self.0)               // pad applies the requested width and alignment
    }
}

println!("[{:>8}]", Code("abc"));  // [     abc]

write!(f, ...) ignores {:>8}; f.pad(...) respects it.

struct Celsius(f64);
struct Fahrenheit(f64);

impl From<Celsius> for Fahrenheit {
    fn from(c: Celsius) -> Self { Fahrenheit(c.0 * 9.0 / 5.0 + 32.0) }
}

let f = Fahrenheit::from(Celsius(100.0));
let f: Fahrenheit = Celsius(100.0).into();     // Into comes for free

You always implement From, never Into: the standard library provides Into automatically for every From.

struct Age(u8);

impl TryFrom<i32> for Age {
    type Error = String;
    fn try_from(v: i32) -> Result<Self, Self::Error> {
        if (0..=150).contains(&v) {
            Ok(Age(v as u8))
        } else {
            Err(format!("impossible age: {v}"))
        }
    }
}

let a = Age::try_from(30);
let b: Result<Age, _> = 200_i32.try_into();   // the suffix says which conversion to use

use std::str::FromStr;

#[derive(Debug)]
enum Color { Red, Green, Blue }

impl FromStr for Color {
    type Err = String;
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s.trim().to_lowercase().as_str() {
            "red" => Ok(Color::Red),
            "green" => Ok(Color::Green),
            "blue" => Ok(Color::Blue),
            other => Err(format!("unknown color: {other}")),
        }
    }
}

let c: Color = "Red".parse().unwrap();
let d = "purple".parse::<Color>();            // Err

FromStr (text → value) and Display (value → text) form a pair: a type that has both can be written out and read back.

use std::hash::{Hash, Hasher};

struct User { id: u32, name: String }

impl PartialEq for User {
    fn eq(&self, other: &Self) -> bool { self.id == other.id }
}
impl Eq for User {}

impl Hash for User {
    fn hash<H: Hasher>(&self, h: &mut H) { self.id.hash(h); }   // consistent with eq
}

Mandatory rule: if a == b, then hash(a) == hash(b). A Hash that included name while eq does not compare it would silently break HashMaps.

use std::cmp::Ordering;

#[derive(PartialEq, Eq)]
struct Task { priority: u8, title: String }

impl Ord for Task {
    fn cmp(&self, other: &Self) -> Ordering {
        other.priority.cmp(&self.priority)                // priority descending
            .then_with(|| self.title.cmp(&other.title))    // then title ascending
    }
}

impl PartialOrd for Task {
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> { Some(self.cmp(other)) }
}

PartialOrd delegates to Ord to stay consistent: this is the standard form.

Often, a one-off sort is enough without implementing Ord: v.sort_by_key(|t| std::cmp::Reverse(t.priority)).

use std::fmt;

#[derive(Debug, Clone, PartialEq)]
struct Temperature(f64);

impl fmt::Display for Temperature {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { write!(f, "{:.1} °C", self.0) }
}

impl From<f64> for Temperature {
    fn from(v: f64) -> Self { Temperature(v) }
}

impl Default for Temperature {
    fn default() -> Self { Temperature(20.0) }
}

trait Pilot { fn fly(&self) -> &'static str; }
trait Wizard { fn fly(&self) -> &'static str; }

struct Human;

impl Pilot for Human { fn fly(&self) -> &'static str { "takeoff" } }
impl Wizard for Human { fn fly(&self) -> &'static str { "broom" } }
impl Human { fn fly(&self) -> &'static str { "flapping arms" } }

fn main() {
    let h = Human;
    h.fly();                         // the type's own method wins: "flapping arms"
    Pilot::fly(&h);                  // "takeoff"
    Wizard::fly(&h);                 // "broom"
    <Human as Pilot>::fly(&h);       // full form
}

For an associated function without self, only the full form works: <Human as Pilot>::name().

use std::fmt;

struct List(Vec<i32>);

impl fmt::Display for List {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let texts: Vec<String> = self.0.iter().map(|x| x.to_string()).collect();
        write!(f, "[{}]", texts.join(" | "))
    }
}

trait TextExt {
    fn is_blank(&self) -> bool;
    fn truncate_chars(&self, n: usize) -> String;
}

impl TextExt for str {
    fn is_blank(&self) -> bool {
        self.trim().is_empty()
    }
    fn truncate_chars(&self, n: usize) -> String {
        self.chars().take(n).collect()
    }
}

fn main() {
    "   ".is_blank();                     // true
    "hello".truncate_chars(3);            // "hel"
    String::from("abc").truncate_chars(1); // also works on String (Deref to str)
}

The trait is local: the orphan rule is respected. Naming convention: TypeNameExt. itertools::Itertools adds dozens of methods to all iterators this way.

// 1. One function per type: duplication
fn gross_book(price: f64) -> f64 { price * 1.055 }
fn gross_game(price: f64) -> f64 { price * 1.20 }

// 2. An enum: closed set, one match
enum Item { Book(f64), Game(f64) }
impl Item {
    fn gross(&self) -> f64 {
        match self {
            Item::Book(p) => p * 1.055,
            Item::Game(p) => p * 1.20,
        }
    }
}

// 3. A trait with an associated constant and a default method: open set
trait Taxable {
    const RATE: f64;
    fn net_price(&self) -> f64;
    fn gross(&self) -> f64 { self.net_price() * (1.0 + Self::RATE) }
}

struct Book(f64);
struct Game(f64);
impl Taxable for Book { const RATE: f64 = 0.055; fn net_price(&self) -> f64 { self.0 } }
impl Taxable for Game { const RATE: f64 = 0.20; fn net_price(&self) -> f64 { self.0 } }

fn total<T: Taxable>(items: &[T]) -> f64 {
    items.iter().map(|a| a.gross()).sum()
}

trait T {
    fn required(&self) -> u32;
    fn with_default(&self) -> u32 { self.required() * 2 }
    fn associated() -> Self where Self: Sized;
    const N: u32;
}
impl T for MyType { .. }

fn f(x: &impl T)              fn f<X: T>(x: &X)          fn f<X>(x: &X) where X: T
fn f(x: &dyn T)               fn f() -> impl T           fn f() -> Box<dyn T>
X::associated()               <MyType as T>::associated()  T::method(&x)

impl fmt::Display for X       impl From<A> for B         impl TryFrom<A> for B
impl FromStr for X            impl PartialEq for X       impl Ord + PartialOrd
trait StrExt { .. } impl StrExt for str { .. }            // extension trait