diff --git a/src/items/associated-items.md b/src/items/associated-items.md index c1f82f62ec05b..eba9507c7fdfe 100644 --- a/src/items/associated-items.md +++ b/src/items/associated-items.md @@ -98,24 +98,28 @@ 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: +If the type of the `self` parameter is specified, it is limited to semantic +types generated by the following grammar (where `'lt` denotes some arbitrary +lifetime): -- `Self` -- `&Self` -- `&mut Self` -- [`Box`] -- [`Rc`] -- [`Arc`] -- [`Pin

`] where `P` is one of the above types except `Self`. +```text +P = &'lt S | &'lt mut S | Box | Rc | Arc | Pin

+S = Self | P +``` -The `Self` term can be replaced with the type being implemented. +The `Self` terminal in this grammar is the semantic `Self` type and can be +replaced with the type being implemented, including type aliases or associated +type projections for the type. ```rust # use std::rc::Rc; # use std::sync::Arc; # use std::pin::Pin; +// Examples of methods implemented on struct `Example`. struct Example; +type Alias = Example; +trait Trait { type Output; } +impl Trait for Example { type Output = Example; } impl Example { fn by_value(self: Self) {} fn by_ref(self: &Self) {} @@ -126,6 +130,8 @@ impl Example { fn by_pin(self: Pin<&Self>) {} fn explicit_type(self: Arc) {} fn with_lifetime<'a>(self: &'a Self) {} + fn nested<'a>(self: &mut &'a Arc>>) {} + fn via_projection(self: ::Output) {} } ``` @@ -360,4 +366,4 @@ fn main() { [function item]: ../types/function-item.md [method call operator]: ../expressions/method-call-expr.md [path]: ../paths.md -[regular function parameters]: functions.md#attributes-on-function-parameters +[regular function parameters]: functions.md#attributes-on-function-parameters diff --git a/src/items/traits.md b/src/items/traits.md index 5427dbe652e06..1a65c9239b6ad 100644 --- a/src/items/traits.md +++ b/src/items/traits.md @@ -95,6 +95,98 @@ Object safe traits can be the base trait of a [trait object]. A trait is * It must not have any associated constants. * All supertraits must also be object safe. +When there isn't a `Self: Sized` bound on a method, the type of a method +receiver must be one of the following types: + +* `&Self` +* `&mut Self` +* [`Box`] +* [`Rc`] +* [`Arc`] +* [`Pin

`] where `P` is one of the types above + +```rust +# use std::rc::Rc; +# use std::sync::Arc; +# use std::pin::Pin; +// Examples of object safe methods. +trait TraitMethods { + fn by_ref(self: &Self) {} + fn by_ref_mut(self: &mut Self) {} + fn by_box(self: Box) {} + fn by_rc(self: Rc) {} + fn by_arc(self: Arc) {} + fn by_pin(self: Pin<&Self>) {} + fn with_lifetime<'a>(self: &'a Self) {} + fn nested_pin(self: Pin>) {} +} +# struct S; +# impl TraitMethods for S {} +# let t: Box = Box::new(S); +``` + +```rust,compile_fail +// This trait is object-safe, but these methods cannot be dispatched on a trait object. +trait NonDispatchable { + // Non-methods cannot be dispatched. + fn foo() where Self: Sized {} + // Self type isn't known until runtime. + fn returns(&self) -> Self where Self: Sized; + // `other` may be a different concrete type of the receiver. + fn param(&self, other: Self) where Self: Sized {} + // Generics are not compatible with vtables. + fn typed(&self, x: T) where Self: Sized {} +} + +struct S; +impl NonDispatchable for S { + fn returns(&self) -> Self where Self: Sized { S } +} +let obj: Box = Box::new(S); +obj.returns(); // ERROR: cannot call with Self return +obj.param(S); // ERROR: cannot call with Self parameter +obj.typed(1); // ERROR: cannot call with generic type +``` + +```rust,compile_fail +# use std::rc::Rc; +// Examples of non-object safe traits. +trait NotObjectSafe { + const CONST: i32 = 1; // ERROR: cannot have associated const + + fn foo() {} // ERROR: associated function without Sized + fn returns(&self) -> Self; // ERROR: Self in return type + fn typed(&self, x: T) {} // ERROR: has generic type parameters + fn nested(self: Rc>) {} // ERROR: nested receiver not yet supported +} + +struct S; +impl NotObjectSafe for S { + fn returns(&self) -> Self { S } +} +let obj: Box = Box::new(S); // ERROR +``` + +```rust,compile_fail +// Self: Sized traits are not object-safe. +trait TraitWithSize where Self: Sized {} + +struct S; +impl TraitWithSize for S {} +let obj: Box = Box::new(S); // ERROR +``` + +```rust,compile_fail +// Not object safe if `Self` is a type argument. +trait Super {} +trait WithSelf: Super where Self: Sized {} + +struct S; +impl Super for S {} +impl WithSelf for S {} +let obj: Box = Box::new(S); // ERROR: cannot use `Self` type parameter +``` + ## Supertraits **Supertraits** are traits that are required to be implemented for a type to @@ -268,3 +360,7 @@ fn main() { [trait implementation]: implementations.md#trait-implementations [`Send`]: ../special-types-and-traits.md#send [`Sync`]: ../special-types-and-traits.md#sync +[`Arc`]: ../special-types-and-traits.md#arct +[`Box`]: ../special-types-and-traits.md#boxt +[`Pin

`]: ../special-types-and-traits.md#pinp +[`Rc`]: ../special-types-and-traits.md#rct