10. Associated Items¶

Syntax

AssociatedItem ::=
    OuterAttributeOrDoc* (AssociatedItemWithVisibility | TerminatedMacroInvocation)

AssociatedItemWithVisibility ::=
    VisibilityModifier? (
        ConstantDeclaration
      | FunctionDeclaration
      | TypeAliasDeclaration
    )

Legality Rules

10:1 An associated item is an item that appears within an implementation or a trait.

10:2 An associated constant is a constant that appears as an associated item.

10:3 An associated function is a function that appears as an associated item.

10:4 An associated type is a type alias that appears as an associated item.

10:5 An associated type shall not be used in the path expression of a struct expression.

10:6 An associated type with a TypeBoundList shall appear only as an associated trait type.

10:7 A generic associated type is an associated type with generic parameters.

10:8 A lifetime parameter of a generic associated type requires a bound of the form T: 'lifetime, where T is a type parameter or Self and 'lifetime is the lifetime parameter, when

• 10:9 The generic associated type is used in an associated function of the same trait, and

• 10:10 The corresponding lifetime argument in the use is not the 'static lifetime and has either an explicit bound or an implicit bound that constrains the type parameter, and

• 10:11 The intersection of all such uses is not empty.

10:12 An associated implementation constant is an associated constant that appears within an implementation.

10:13 An associated implementation constant shall have a constant initializer.

10:14 An associated implementation function is an associated function that appears within an implementation.

10:15 An associated implementation function shall have a function body.

10:16 An associated implementation type is an associated type that appears within an implementation.

10:17 An associated implementation type shall have an initialization type.

10:18 An associated trait item is an associated item that appears within a trait.

10:19 An associated trait implementation item is an associated item that appears within a trait implementation.

10:20 An associated trait constant is an associated constant that appears within a trait.

10:21 An associated trait function is an associated function that appears within a trait.

10:22 An associated trait function shall not be subject to keyword const.

10:23 Every occurrence of an impl trait type in the return type of an associated trait function is equivalent to referring to a new anonymous associated trait type of the implemented trait.

10:24 An associated trait type is an associated type that appears within a trait.

10:25 An associated trait type shall not have an initialization type.

10:26 An associated trait type has an implicit core::marker::Sized bound.

10:27 An associated trait type of the form

trait T {
    type X: Bound;
}

10:28 is equivalent to a where clause of the following form:

trait T where Self::X: Bound {
    type X;
}

10:29 An associated trait implementation function is an associated function that appears within a trait implementation.

10:30 Every occurrence of an impl trait type in the return type of an associated trait implementation function is equivalent to referring to the corresponding associated trait type of the corresponding associated trait function.

10:31 A method is an associated function with a self parameter.

10:32 The type of a self parameter shall be one of the following:

• 10:33 A type specification resolving to the implementing type of the related implementation, or

• 10:34 &T where T is one of the types listed in this enumeration, or

• 10:35 &mut T where T is one of the types listed in this enumeration, or

• 10:36 core::pin::Pin<T> where T is one of the the types listed in this enumeration.

10:37 The visibility modifier of an associated trait item or associated trait implementation item is rejected, but may still be consumed by macros.

Examples

trait Greeter {
    const MAX_GREETINGS: i32;

    fn greet(self, message: &str);
}

struct Implementor {
    delivered_greetings: i32
}

impl Greeter for Implementor {
    const MAX_GREETINGS: i32 = 42;

    fn greet(mut self, message: &str) {
        if self.delivered_greetings < Self::MAX_GREETINGS {
            self.delivered_greetings += 1;
            println!("{}", message);
        }
    }
}

10:38 Generic associated type with lifetime bound.

trait LendingIterator {
    type Item<'x> where Self: 'x;

    fn next<'a>(&'a mut self) -> Self::Item<'a>;
}