Rust traits, impl blocks, and derive.

A Rust type gets methods from impl blocks, and from nowhere else. There are two kinds. An inherent impl, written impl Kit { … } with no trait name, adds methods that belong to Kit itself, as in Methods, receivers, and this. A trait impl, written impl Progress for Kit { … }, gives Kit the methods that the trait Progress lists. A type can have any number of both kinds.

A trait can also give a method a body, a provided method. Below, label is written once, in the trait, and calls percent, which each type must write. A Kit gets that label until impl Progress for Kit writes its own, as Interfaces, traits, and type classes showed.

When you call tugboat.left(), the compiler looks first at the inherent methods of Kit, then at the methods of the traits that Kit implements. The stepper shows which one ran. An inherent method’s frame is named after the type, main::Kit::left. A trait impl’s method is named after the position of its impl block, main::{impl#1}::percent. A provided method is named after the trait, with the type in angle brackets: main::Progress::label<main::Kit>.

A method comes from the type’s own impl, from a trait impl, or from a provided method in the trait.

#[derive(Debug, Clone, PartialEq)] above a struct asks the compiler to write three impl blocks, one per trait, as if you had written impl Clone for Kit { … } yourself. Each derived impl works field by field. Debug prints the type’s name and each field with that field’s own Debug, so {:?} shows Kit { pieces: 120, paint: Paint { tins: 6 } }. Clone clones each field. PartialEq compares each field with its own ==, in the order the fields are declared, and is true only when every field is equal.

Because the derived code calls each field’s impl, every field must have the trait. If Paint has no derive line, the compiler reports error[E0277]: `Paint` doesn’t implement `Debug` at the line paint: Paint, with help: consider annotating `Paint` with `#[derive(Debug)]`. Clone and == give their own errors at the same field.

The standard library lets you derive nine traits: Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, and Default. Display, which prints text for people with {}, cannot be derived; you write it by hand, as a later section shows. The stepper never stops inside derived code, because that code has no lines in your file.

derive writes one impl per trait, and each impl uses the same trait on every field, so every field must have it.

Variables showed that assigning a Copy value copies it, and the old binding stays usable. Copy has no method of its own. It is a marker: it tells the compiler that copying the bytes makes a complete second value. The copying itself is the job of Clone, and Copy is declared as trait Copy: Clone, which means every Copy type must also be Clone. #[derive(Debug, Copy)] alone reports error[E0277]: the trait bound `Glue: Clone` is not satisfied. Derive both: #[derive(Clone, Copy)].

Every field must be Copy as well. A String owns memory on the heap, and copying its bytes would give that memory two owners. A struct with brand: String and #[derive(Clone, Copy)] reports error[E0204]: the trait `Copy` may not be implemented for this type, with this field does not implement `Copy` under brand. Clone alone is still allowed: it clones the String.

Derive Copy for small values that behave like numbers, such as a size, an amount of glue, or a colour. A value that keeps state you change in place is a poor fit, as the production section shows.

Copy needs Clone, and every field must be Copy; derive Copy only for small, number-like values.

A derived PartialOrd or Ord compares the first field declared in the struct. Only when the first fields are equal does it compare the second, and so on, the way a dictionary orders words letter by letter. The order of the fields in a struct literal makes no difference. The order of the lines in the struct declaration decides, so swapping two field lines changes what sort() does.

For an enum, the variants compare in the order they are declared: the first variant is the smallest. Variants with fields compare by variant first, then by their fields.

Eq and Ord promise more than PartialEq and PartialOrd: every value equals itself, and any two values can be put in order. An f64 cannot promise this, because NaN is not equal to itself. A struct with an f64 field can derive PartialEq and PartialOrd, but #[derive(PartialEq, Eq)] reports error[E0277]: the trait bound `f64: Eq` is not satisfied. Hash and Default also go field by field: Hash feeds each field into the hash in order, and Default gives each field its own default, as Constructors and creating values showed.

A derived order compares fields in declaration order, and enum variants in declaration order.

A derived impl uses every field, in declaration order. When that is not what equal or smaller means for your type, write the impl yourself. Two cases are common: equality that should ignore a field, and an order by a different field. Below, two kits with the same code are equal however much of each is built, and shorter builds sort first. impl Eq for Kit {} has no methods: it only promises that this == is a full equality.

The comparison traits must agree with each other. If a == b, then a and b must have the same hash, and a.cmp(&b) must be Equal; cmp must give Equal only when == is true. partial_cmp should be Some(self.cmp(other)). Derive them all, or write them all by hand from the same fields. Equality and comparison shows what a HashMap does when Hash and == disagree.

Display, the trait behind {}, is always written by hand. Its method fmt receives a fmt::Formatter, and write!(f, …) works like format! but writes into f.

One limit applies to every impl you write: the orphan rule. impl Trait for Type compiles only when the trait or the type is defined in your crate, the program or library being compiled. impl fmt::Display for Vec<Kit> reports error[E0117]: only traits defined in the current crate can be implemented for types defined outside of the crate, because both Display and Vec come from the standard library. The fix is your own type around it: struct Shelf(Vec<Kit>), a struct with one unnamed field, read as shelf.0.

Write an impl by hand when the derived meaning is wrong; keep ==, Hash, and cmp in agreement; wrap a foreign type to give it a foreign trait.

Programs that compile still go wrong where derived and hand-written impls meet. Four mistakes are common.

A derived order changes with the fields. Someone adds name as the first field of Kit, because it reads better, and every sort() of kits now sorts by name. When an order matters, write Ord by hand, or sort with sort_by_key at the place that needs it, and test the order.

A hand-written == next to a derived Hash. Two kits with the same code are equal, but the derived Hash also hashes built, so they get different hashes, and a HashSet keeps both. Write Hash by hand from the same fields that == uses.

A derived PartialOrd next to a hand-written Ord. cmp compares hours, but <, >, and the derived partial_cmp compare every field. In this build, the standard library’s sort also compared with <, so the hand-written order was never used. Write partial_cmp as Some(self.cmp(other)).

Copy on a value with state. let mut first = kits[0]; first.done = true; changes a copy, and kits[0] stays not done. Without Copy, the compiler stops at the first line with error[E0507]: cannot move out of index of `Vec<Kit>`. Use kits[0].done = true, or let first = &mut kits[0];.

Keep a derived order’s field order on purpose, write Hash and PartialOrd from the same rule as == and cmp, and derive Copy only for values you never change in place.

A kit has a skill level and a number of pieces, with derived traits. Predict each line. max returns the larger of two values, using cmp.