diff --git a/src/items/associated-items.md b/src/items/associated-items.md index 2908e6bcc..9223a7461 100644 --- a/src/items/associated-items.md +++ b/src/items/associated-items.md @@ -93,9 +93,37 @@ 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 the type -being implemented (or `Self`), or a reference or mutable reference to the -type, or a boxed value of the type being implemented (such as `Box`). +If the type of the `self` parameter is specified, it is limited to one of the +following types: + +- `Self` +- `&Self` +- `&mut Self` +- [`Box`] +- [`Rc`] +- [`Arc`] +- [`Pin

`] where `P` is one of the above types except `Self`. + +The `Self` term can be replaced with the type being implemented. + +```rust +# 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) {} + fn by_rc(self: Rc) {} + fn by_arc(self: Arc) {} + fn by_pin(self: Pin<&Self>) {} + fn explicit_type(self: Arc) {} + fn with_lifetime<'a>(self: &'a Self) {} +} +``` + Shorthand syntax can be used without specifying a type, which have the following equivalents: @@ -107,7 +135,17 @@ Shorthand | Equivalent > Note: Lifetimes can be and usually are elided with this shorthand. -Consider the following trait: +If the `self` parameter is prefixed with `mut`, it becomes a mutable variable, +similar to regular parameters using a `mut` [identifier pattern]. For example: + +```rust +trait Changer: Sized { + fn change(mut self) {} + fn modify(mut self: Box) {} +} +``` + +As an example of methods on a trait, consider the following: ```rust # type Surface = i32; @@ -294,11 +332,16 @@ fn main() { [_Lifetime_]: trait-bounds.html [_Type_]: types.html#type-expressions [_WhereClause_]: items/generics.html#where-clauses +[`Arc`]: special-types-and-traits.html#arct +[`Box`]: special-types-and-traits.html#boxt +[`Pin

`]: special-types-and-traits.html#pinp +[`Rc`]: special-types-and-traits.html#rct [trait]: items/traits.html [traits]: items/traits.html [type aliases]: items/type-aliases.html [inherent implementations]: items/implementations.html#inherent-implementations [identifier]: identifiers.html +[identifier pattern]: patterns.html#identifier-patterns [trait object]: types/trait-object.html [implementations]: items/implementations.html [type]: types.html#type-expressions diff --git a/src/special-types-and-traits.md b/src/special-types-and-traits.md index cefdc2ed2..6d803a0aa 100644 --- a/src/special-types-and-traits.md +++ b/src/special-types-and-traits.md @@ -16,6 +16,18 @@ defined types. * A trait may be implemented for `Box` in the same crate as `T`, which the [orphan rules] prevent for other generic types. +## `Rc` + +[Methods] can take [`Rc`] as a receiver. + +## `Arc` + +[Methods] can take [`Arc`] as a receiver. + +## `Pin

` + +[Methods] can take [`Pin

`] as a receiver. + ## `UnsafeCell` [`std::cell::UnsafeCell`] is used for [interior mutability]. It ensures that @@ -123,12 +135,15 @@ compile-time; that is, it's not a [dynamically sized type]. [Type parameters] are `Sized` by default. `Sized` is always implemented automatically by the compiler, not by [implementation items]. +[`Arc`]: ../std/sync/struct.Arc.html [`Box`]: ../std/boxed/struct.Box.html [`Clone`]: ../std/clone/trait.Clone.html [`Copy`]: ../std/marker/trait.Copy.html [`Deref`]: ../std/ops/trait.Deref.html [`DerefMut`]: ../std/ops/trait.DerefMut.html [`Drop`]: ../std/ops/trait.Drop.html +[`Pin

`]: ../std/pin/struct.Pin.html +[`Rc`]: ../std/rc/struct.Rc.html [`RefUnwindSafe`]: ../std/panic/trait.RefUnwindSafe.html [`Send`]: ../std/marker/trait.Send.html [`Sized`]: ../std/marker/trait.Sized.html diff --git a/src/variables.md b/src/variables.md index a751098ce..f6589e394 100644 --- a/src/variables.md +++ b/src/variables.md @@ -11,21 +11,10 @@ Local variables are immutable unless declared otherwise. For example: `let mut x = ...`. Function parameters are immutable unless declared with `mut`. The `mut` keyword -applies only to the following parameter. For example: `|mut x, y|` and +applies only to the following parameter. For example: `|mut x, y|` and `fn f(mut x: Box, y: Box)` declare one mutable variable `x` and one immutable variable `y`. -Methods that take either `self` or `Box` can optionally place them in a -mutable variable by prefixing them with `mut` (similar to regular arguments). -For example: - -```rust -trait Changer: Sized { - fn change(mut self) {} - fn modify(mut self: Box) {} -} -``` - Local variables are not initialized when allocated. Instead, the entire frame worth of local variables are allocated, on frame-entry, in an uninitialized state. Subsequent statements within a function may or may not initialize the