Merge pull request #494 from ehuss/restricted-self-types

Document Rc/Arc method receivers.

Author: matthewjasper

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<Self>`).
+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>`] 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<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:
 
@@ -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<Self>) {}
+}
+```
+
+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<Self>`]: special-types-and-traits.html#arct
+[`Box<Self>`]: special-types-and-traits.html#boxt
+[`Pin<P>`]: special-types-and-traits.html#pinp
+[`Rc<Self>`]: 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

src/special-types-and-traits.md

@@ -16,6 +16,18 @@ defined types.
 * A trait may be implemented for `Box<T>` in the same crate as `T`, which the
   [orphan rules] prevent for other generic types.
 
+## `Rc<T>`
+
+[Methods] can take [`Rc<Self>`] as a receiver.
+
+## `Arc<T>`
+
+[Methods] can take [`Arc<Self>`] as a receiver.
+
+## `Pin<P>`
+
+[Methods] can take [`Pin<P>`] as a receiver.
+
 ## `UnsafeCell<T>`
 
 [`std::cell::UnsafeCell<T>`] 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<Self>`]: ../std/sync/struct.Arc.html
 [`Box<T>`]: ../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<P>`]: ../std/pin/struct.Pin.html
+[`Rc<Self>`]: ../std/rc/struct.Rc.html
 [`RefUnwindSafe`]: ../std/panic/trait.RefUnwindSafe.html
 [`Send`]: ../std/marker/trait.Send.html
 [`Sized`]: ../std/marker/trait.Sized.html

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<i32>, y: Box<i32>)` declare one mutable variable `x` and one
 immutable variable `y`.
 
-Methods that take either `self` or `Box<Self>` 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<Self>) {}
-}
-```
-
 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