From 543a7c7e7d3431e8befb6f0ceaa1ceb98c3567da Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 30 Dec 2018 17:15:12 -0800 Subject: [PATCH 1/4] Document Rc/Arc method receivers. --- src/items/associated-items.md | 34 ++++++++++++++++++++++++++++++--- src/special-types-and-traits.md | 10 ++++++++++ src/variables.md | 10 ++++++---- 3 files changed, 47 insertions(+), 7 deletions(-) diff --git a/src/items/associated-items.md b/src/items/associated-items.md index 2908e6bcc..5edecacff 100644 --- a/src/items/associated-items.md +++ b/src/items/associated-items.md @@ -93,9 +93,34 @@ 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`] + +The `Self` portion of the type may be replaced with the type being +implemented. + +```rust +# use std::rc::Rc; +# use std::sync::Arc; +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 explicit_type(self: Arc) {} +} +``` + Shorthand syntax can be used without specifying a type, which have the following equivalents: @@ -294,6 +319,9 @@ 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 +[`Rc`]: special-types-and-traits.html#rct [trait]: items/traits.html [traits]: items/traits.html [type aliases]: items/type-aliases.html diff --git a/src/special-types-and-traits.md b/src/special-types-and-traits.md index cefdc2ed2..a57e4ad1c 100644 --- a/src/special-types-and-traits.md +++ b/src/special-types-and-traits.md @@ -16,6 +16,14 @@ 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. + ## `UnsafeCell` [`std::cell::UnsafeCell`] is used for [interior mutability]. It ensures that @@ -123,12 +131,14 @@ 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 +[`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..8bfc7ad96 100644 --- a/src/variables.md +++ b/src/variables.md @@ -11,13 +11,13 @@ 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: +[Methods] that take `self` or one of the supported `Self` types such as +`Box` can optionally place them in a mutable variable by prefixing them +with `mut` (similar to regular arguments). For example: ```rust trait Changer: Sized { @@ -52,3 +52,5 @@ fn initialization_example() { // uninit_after_if; // err: use of possibly uninitialized `uninit_after_if` } ``` + +[Methods]: items/associated-items.html#methods From 0147934d2a2c4db3e39b78131b4da0adf79cffd0 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 30 Dec 2018 19:22:30 -0800 Subject: [PATCH 2/4] Address review comments. --- src/items/associated-items.md | 9 +++++++-- src/special-types-and-traits.md | 5 +++++ src/variables.md | 13 ------------- 3 files changed, 12 insertions(+), 15 deletions(-) diff --git a/src/items/associated-items.md b/src/items/associated-items.md index 5edecacff..09ca69d63 100644 --- a/src/items/associated-items.md +++ b/src/items/associated-items.md @@ -102,13 +102,15 @@ following types: - [`Box`] - [`Rc`] - [`Arc`] +- [`Pin

`] where `P` is one of the above types except `Self`. -The `Self` portion of the type may be replaced with the type being -implemented. +As an alternate way of writing the type, the `Self` term may instead be +written 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) {} @@ -117,7 +119,9 @@ impl Example { 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) {} } ``` @@ -321,6 +325,7 @@ fn main() { [_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 diff --git a/src/special-types-and-traits.md b/src/special-types-and-traits.md index a57e4ad1c..6d803a0aa 100644 --- a/src/special-types-and-traits.md +++ b/src/special-types-and-traits.md @@ -24,6 +24,10 @@ defined types. [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 @@ -138,6 +142,7 @@ compiler, not by [implementation items]. [`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 diff --git a/src/variables.md b/src/variables.md index 8bfc7ad96..f6589e394 100644 --- a/src/variables.md +++ b/src/variables.md @@ -15,17 +15,6 @@ 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 `self` or one of the supported `Self` types such as -`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 @@ -52,5 +41,3 @@ fn initialization_example() { // uninit_after_if; // err: use of possibly uninitialized `uninit_after_if` } ``` - -[Methods]: items/associated-items.html#methods From 74d61db75eb5cb70ef6693ae3146232449bcee5c Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 30 Dec 2018 19:45:46 -0800 Subject: [PATCH 3/4] Restore description of `mut` on self. --- src/items/associated-items.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/src/items/associated-items.md b/src/items/associated-items.md index 09ca69d63..d52d23814 100644 --- a/src/items/associated-items.md +++ b/src/items/associated-items.md @@ -136,7 +136,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; @@ -332,6 +342,7 @@ fn main() { [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 From 1ec7c0495f44bfc6697e1c5f414b4f8c5b25dfc4 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 10 Jan 2019 11:16:30 -0800 Subject: [PATCH 4/4] Take 32 on trying to avoid an awkward sentence. --- src/items/associated-items.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/items/associated-items.md b/src/items/associated-items.md index d52d23814..9223a7461 100644 --- a/src/items/associated-items.md +++ b/src/items/associated-items.md @@ -104,8 +104,7 @@ following types: - [`Arc`] - [`Pin

`] where `P` is one of the above types except `Self`. -As an alternate way of writing the type, the `Self` term may instead be -written with the type being implemented. +The `Self` term can be replaced with the type being implemented. ```rust # use std::rc::Rc;