11. Implementations

Syntax

Implementation ::=
    InherentImplementation
  | TraitImplementation

InherentImplementation ::=
    impl GenericParameterList? ImplementingType WhereClause? ImplementationBody

TraitImplementation ::=
    unsafe? impl GenericParameterList? !? ImplementedTrait for ImplementingType WhereClause? ImplementationBody

ImplementingType ::=
    TypeSpecification

ImplementedTrait ::=
    TypePath

ImplementationBody ::=
    {
      InnerAttributeOrDoc*
      AssociatedItem*
    }

Legality Rules

11:1 An implementation is an item that supplements an implementing type by extending its functionality.

11:2 An implementing type is the type that the associated items of an implementation are associated with.

11:3 Within an implementation, the type Self acts as a type alias for the implementing type.

11:4 An implementation body is a construct that encapsulates the associated items, inner attributes, and inner doc comments of an implementation.

11:5 An inherent implementation is an implementation that adds direct functionality.

11:6 Inherent implementations of the same implementing type shall be defined within the same crate.

11:7 A trait implementation is an implementation that adds functionality specified by a trait.

11:8 An unsafe trait implementation is a trait implementation subject to keyword unsafe.

11:9 An implemented trait is a trait whose functionality has been implemented by an implementing type.

11:10 The type path of a trait implementation shall resolve to a trait.

11:11 A trait implementation shall be an unsafe trait implementation if and only if it implements an unsafe trait.

11:12 Trait implementations are subject to implementation coherence and implementation conformance.

11:13 Inherent implementations of the same implementing type shall not define more than one associated item with the same name in the same namespace.

Examples

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

11:14 Circle is an implementing type.

struct Circle {
    radius: f64
}

11:15 The following is an inherent implementation:

impl Circle {
    fn set_radius(mut self, new_radius: f64) {
        self.radius = new_radius;
    }
}

11:16 The following is a trait implementation:

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

11.1. Implementation Coherence

Legality Rules

11.1:1 A trait implementation exhibits implementation coherence when it is valid and does not overlap with another trait implementation.

11.1:2 Two trait implementations of the same implemented trait overlap when the intersection of the implementing types is non-empty.

11.1:3 Given trait implementation impl<P1, P2, .., PN> Trait<T1, T2, .., TN> for T0, the trait implementation is considered valid when

11.1:8 A trait or type is fundamental when its implementation coherence rules are relaxed and the trait or type is always treated as if it was a local trait or a local type.

11.1:9 The following types are fundamental:

11.1:12 The following traits are fundamental:

11.1:17 A trait implementation shall be coherent.

11.2. Implementation Conformance

Legality Rules

11.2:1 A trait implementation exhibits implementation conformance when it satisfies the constraints of its implemented trait.

11.2:2 An associated trait constant is conformant with an associated constant of an implemented trait when

11.2:5 An associated trait function is conformant with an associated function of an implemented trait when

11.2:8 An associated type of a trait implementation is conformant with an associated type of an implemented trait when

11.2:11 A trait implementation is conformant with an implemented trait when:

11.2:15 A trait implementation shall be conformant.