Associated Items
Associated Items are the items declared in traits or defined in implementations. They are called this because they are defined on an associate type — the type in the implementation. They are a subset of the kinds of items you can declare in a module. Specifically, there are associated functions (including methods), associated types, and associated constants.
Associated items are useful when the associated item logically is related to the
associating item. For example, the is_some
method on Option
is intrinsically
related to Options, so should be associated.
Every associated item kind comes in two varieties: definitions that contain the actual implementation and declarations that declare signatures for definitions.
It is the declarations that make up the contract of traits and what it available on generic types.
Associated functions and methods
Associated functions are functions associated with a type.
An associated function declaration declares a signature for an associated
function definition. It is written as a function item, except the
function body is replaced with a ;
.
The identifier is the name of the function. The generics, parameter list, return type, and where clause of the associated function must be the same as the associated function declarations's.
An associated function definition defines a function associated with another type. It is written the same as a function item.
An example of a common associated function is a new
function that returns
a value of the type the associated function is associated with.
struct Struct { field: i32 } impl Struct { fn new() -> Struct { Struct { field: 0i32 } } } fn main () { let _struct = Struct::new(); }
When the associated function is declared on a trait, the function can also be
called with a path that is a path to the trait appended by the name of the
trait. When this happens, it is substituted for <_ as Trait>::function_name
.
# #![allow(unused_variables)] #fn main() { trait Num { fn from_i32(n: i32) -> Self; } impl Num for f64 { fn from_i32(n: i32) -> f64 { n as f64 } } // These 4 are all equivalent in this case. let _: f64 = Num::from_i32(42); let _: f64 = <_ as Num>::from_i32(42); let _: f64 = <f64 as Num>::from_i32(42); let _: f64 = f64::from_i32(42); #}
Methods
Method :
FunctionQualifiersfn
IDENTIFIER Generics?
(
SelfParam (,
FunctionParam)*,
?)
FunctionReturnType? WhereClause?
BlockExpressionSelfParam :
(&
|&
Lifetime)?mut
?self
|mut
?self
(:
Type)?
Associated functions whose first parameter is named self
are called methods
and may be invoked using the method call operator, for example, x.foo()
, as
well as the usual function call notation.
If the type of the self
parameter is specified, it is limited to one of the
following types:
Self
&Self
&mut Self
Box<Self>
Rc<Self>
Arc<Self>
Pin<P>
whereP
is one of the above types exceptSelf
.
The Self
term can be replaced with the type being implemented.
# #![allow(unused_variables)] #fn main() { # use std::rc::Rc; # use std::sync::Arc; # use std::pin::Pin; struct Example; impl Example { fn by_value(self: Self) {} fn by_ref(self: &Self) {} fn by_ref_mut(self: &mut Self) {} fn by_box(self: Box<Self>) {} fn by_rc(self: Rc<Self>) {} fn by_arc(self: Arc<Self>) {} fn by_pin(self: Pin<&Self>) {} fn explicit_type(self: Arc<Example>) {} fn with_lifetime<'a>(self: &'a Self) {} } #}
Shorthand syntax can be used without specifying a type, which have the following equivalents:
Shorthand | Equivalent |
---|---|
self | self: Self |
&'lifetime self | self: &'lifetime Self |
&'lifetime mut self | self: &'lifetime mut Self |
Note: Lifetimes can be and usually are elided with this shorthand.
If the self
parameter is prefixed with mut
, it becomes a mutable variable,
similar to regular parameters using a mut
identifier pattern. For example:
# #![allow(unused_variables)] #fn main() { trait Changer: Sized { fn change(mut self) {} fn modify(mut self: Box<Self>) {} } #}
As an example of methods on a trait, consider the following:
# #![allow(unused_variables)] #fn main() { # type Surface = i32; # type BoundingBox = i32; trait Shape { fn draw(&self, surface: Surface); fn bounding_box(&self) -> BoundingBox; } #}
This defines a trait with two methods. All values that have implementations
of this trait while the trait is in scope can have their draw
and
bounding_box
methods called.
# #![allow(unused_variables)] #fn main() { # type Surface = i32; # type BoundingBox = i32; # trait Shape { # fn draw(&self, surface: Surface); # fn bounding_box(&self) -> BoundingBox; # } # struct Circle { // ... } impl Shape for Circle { // ... # fn draw(&self, _: Surface) {} # fn bounding_box(&self) -> BoundingBox { 0i32 } } # impl Circle { # fn new() -> Circle { Circle{} } # } # let circle_shape = Circle::new(); let bounding_box = circle_shape.bounding_box(); #}
Edition Differences: In the 2015 edition, it is possible to declare trait methods with anonymous parameters (e.g.
fn foo(u8)
). This is deprecated and an error as of the 2018 edition. All parameters must have an argument name.
Associated Types
Associated types are type aliases associated with another type. Associated types cannot be defined in inherent implementations nor can they be given a default implementation in traits.
An associated type declaration declares a signature for associated type
definitions. It is written as type
, then an identifier, and
finally an optional list of trait bounds.
The identifier is the name of the declared type alias. The optional trait bounds must be fulfilled by the implementations of the type alias.
An associated type definition defines a type alias on another type. It is
written as type
, then an identifier, then an =
, and finally a type.
If a type Item
has an associated type Assoc
from a trait Trait
, then
<Item as Trait>::Assoc
is a type that is an alias of the type specified in the
associated type definition. Furthermore, if Item
is a type parameter, then
Item::Assoc
can be used in type parameters.
trait AssociatedType { // Associated type declaration type Assoc; } struct Struct; struct OtherStruct; impl AssociatedType for Struct { // Associated type definition type Assoc = OtherStruct; } impl OtherStruct { fn new() -> OtherStruct { OtherStruct } } fn main() { // Usage of the associated type to refer to OtherStruct as <Struct as AssociatedType>::Assoc let _other_struct: OtherStruct = <Struct as AssociatedType>::Assoc::new(); }
Associated Types Container Example
Consider the following example of a Container
trait. Notice that the type is
available for use in the method signatures:
# #![allow(unused_variables)] #fn main() { trait Container { type E; fn empty() -> Self; fn insert(&mut self, elem: Self::E); } #}
In order for a type to implement this trait, it must not only provide
implementations for every method, but it must specify the type E
. Here's an
implementation of Container
for the standard library type Vec
:
# #![allow(unused_variables)] #fn main() { # trait Container { # type E; # fn empty() -> Self; # fn insert(&mut self, elem: Self::E); # } impl<T> Container for Vec<T> { type E = T; fn empty() -> Vec<T> { Vec::new() } fn insert(&mut self, x: T) { self.push(x); } } #}
Associated Constants
Associated constants are constants associated with a type.
An associated constant declaration declares a signature for associated
constant definitions. It is written as const
, then an identifier,
then :
, then a type, finished by a ;
.
The identifier is the name of the constant used in the path. The type is the type that the definition has to implement.
An associated constant definition defines a constant associated with a type. It is written the same as a constant item.
Associated Constants Examples
A basic example:
trait ConstantId { const ID: i32; } struct Struct; impl ConstantId for Struct { const ID: i32 = 1; } fn main() { assert_eq!(1, Struct::ID); }
Using default values:
trait ConstantIdDefault { const ID: i32 = 1; } struct Struct; struct OtherStruct; impl ConstantIdDefault for Struct {} impl ConstantIdDefault for OtherStruct { const ID: i32 = 5; } fn main() { assert_eq!(1, Struct::ID); assert_eq!(5, OtherStruct::ID); }