Rustacean

Use a Newtype to Implement Foreign Traits

3 min read

Use a Newtype to Implement Foreign Traits

Wrap a foreign type in a local single-field struct when you need to implement a foreign trait that the orphan rule forbids implementing directly.

What it is

The orphan rule says you must own the trait or own the type in a trait impl. When both are foreign, create a local wrapper type and implement the foreign trait for that local wrapper. This is the newtype pattern used specifically as a coherence escape hatch. The wrapper has a distinct type identity with no inherent runtime overhead in normal optimized code. It also gives you a place to define domain-specific formatting, validation, or behavior.

How it works

Define struct Wrapper(ForeignType); in your crate. Because Wrapper is local, impl ForeignTrait for Wrapper is legal. Inside the impl, delegate to the inner value deliberately. The wrapper does not automatically behave like the inner type; expose only the methods that support your abstraction. Avoid replacing the wrapper with a type alias, because aliases do not create a new local type. The compiler treats the tuple struct as a distinct nominal type, so coherence sees CsvRow as local even though its field is Vec<String>. With #[repr(transparent)], a single-field wrapper can also make layout promises for FFI or unsafe abstractions, but representation is not needed merely to satisfy the orphan rule. Derive standard traits on the wrapper only when the derived semantics match the wrapper’s domain meaning. Forwarding is an API design decision: every forwarded method becomes part of what the wrapper promises.

Example

use std::fmt;
 
struct CsvRow(Vec<String>);
 
impl fmt::Display for CsvRow {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.0.join(","))
    }
}
 
impl CsvRow {
    fn len(&self) -> usize {
        self.0.len()
    }
}
 
fn main() {
    let row = CsvRow(vec!["a".into(), "b".into(), "c".into()]);
    assert_eq!(row.to_string(), "a,b,c");
    assert_eq!(row.len(), 3);
}

Common errors

Using a type alias instead of a wrapper still fails:

error[E0117]: only traits defined in the current crate can be implemented for types defined outside of the crate

type CsvRow = Vec<String>; is only another name for Vec<String>, not a local type. Define struct CsvRow(Vec<String>); and implement the foreign trait for CsvRow. Another common issue is losing access to convenient inner methods after wrapping. Add focused inherent methods, AsRef, From, or iterator impls when they preserve the wrapper’s meaning; avoid blanket Deref as a shortcut unless pointer-like behavior is truly intended.

Best practice

  • ✅ Use a local tuple struct wrapper when both the target trait and target type are foreign.
  • ✅ Keep the inner field private unless the wrapper is intentionally transparent.
  • ✅ Forward only the operations that belong to the wrapper’s abstraction.
  • ✅ Prefer inherent methods or trait impls over exposing .0 everywhere.
  • ✅ Link the wrapper’s purpose to Coherence and the Orphan Rule in docs so future maintainers do not remove it.

Pitfalls

  • ⚠️ A type alias does not satisfy the orphan rule; see Using Type Aliases as Newtypes.
  • ⚠️ Implementing Deref just to recover every inner method can erase the abstraction; see Deref Polymorphism Antipattern.
  • ⚠️ Public wrapper fields let callers bypass invariants.
  • ⚠️ Newtypes require intentional forwarding, which is a feature when the wrapper means something different from the inner type.

See also

Coherence and the Orphan Rule · Traits · Newtype Pattern · Type Aliases · Using Type Aliases as Newtypes · Deref Polymorphism Antipattern · Fully Qualified Syntax · Generics, Traits & Lifetimes

Sources

Graph View

Backlinks