Rust Reference ยท Concepts
Rust orphan and coherence rules
Reference for Rust coherence: the orphan rule, overlapping impls, blanket impls, the newtype workaround, fundamental types and why you cannot implement foreign traits for foreign types.
Coherence is the guarantee that for any type and trait there is at most one implementation the compiler can pick. Without it, two crates could implement the same trait for the same type differently and the program's behavior would depend on which crate was linked. Rust enforces coherence with two checks: the orphan rule and the overlap check.
The orphan rule says: you may write impl Trait for Type only if the trait or the type (roughly) is defined in your own crate. Implementing a foreign trait for a foreign type is an error, because neither you nor the other crates own the pair.
// Allowed: local trait, foreign type. trait Describe { fn describe(&self) -> String; } impl Describe for i32 { fn describe(&self) -> String { format!("int {self}") } }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
The rules
An impl<P1..=Pn> Trait<T1..=Tn> for T0 is accepted when at least one of T0..=Tn is a local type, and no uncovered type parameters appear before it. In plain terms:
| Impl | Allowed? | Why |
|---|---|---|
impl LocalTrait for i32 |
yes | the trait is local |
impl Display for Local |
yes | Local is local |
impl From<Local> for String |
yes | Local appears as a trait parameter |
impl Display for Vec<i32> |
no | neither is local |
impl<T> Display for T |
no | uncovered T stands for any (possibly foreign) type |
impl<T> LocalTrait for T |
yes | blanket impl of a local trait |
impl<T> From<T> for Local<T> |
yes | Local<T> is local and T is covered by it |
Some pointer types are fundamental: &T, &mut T, Box<T> and Pin<T> count as local when T is local. So impl Display for Box<Local> is not blocked by the orphan rule.
Overlap
Even local impls must not overlap: two impls that could apply to the same type. A blanket impl<T: Display> Describe for T conflicts with impl Describe for i32, because i32 is Display. Rust does not yet support specialization on stable, so you pick one design.
The compiler is also conservative about the future: an upstream crate may add a trait impl in a later version, so you cannot assume Vec<Local> will never implement a foreign trait on its own unless the language rules guarantee it. This is why blanket impls over foreign traits are so restricted.
Usage notes
- Newtype pattern: wrap the foreign type in a tuple struct, implement what you need on it, and optionally forward methods with
DereforAsRef. - Extension traits: define your own trait with methods and implement it for the foreign type (
trait StrExt { ... } impl StrExt for str). This is how crates add methods tostrorIterator. - Adding an impl is semver-sensitive. Adding a blanket impl, or a trait impl for an existing public type, can break downstream code; library authors treat it as a breaking change unless it is covered by the rules.
- Library tip: implement the standard traits (
Debug,Clone,Display,From,Default) for your public types so users never need a workaround. #[derive]produces local impls and therefore always satisfies the orphan rule for your own types.- Error E0117 reports a violated orphan rule; E0119 reports conflicting (overlapping) impls; E0210 reports an uncovered type parameter.