Adjust receiver lookup to match the actual impl

As a part of this, remove the reference to coerce_inner and replace it
with a proper description of unsized coercions. That description will
have to be updated later when more of the unsized work stabilizes.

Closes #62.

Author: Alexis Hunt

src/expressions/method-call-expr.md

@@ -14,38 +14,68 @@ let log_pi = pi.unwrap_or(1.0).log(2.72);
 # assert!(1.14 < log_pi && log_pi < 1.15)
 ```
 
-When resolving method calls on an expression of type `A`, Rust will use the
-following order, only looking at methods that are [visible]. If the type of `A`
-is a type parameter or `Self` in a trait definitition then steps 2-4 first
-consider traits from bounds on the type paramter, then the traits that are in
-scope. For other types, only the traits that are in scope are considered.
-
-1. Inherent methods, with receiver of type `A`, `&A`, `&mut A`.
-1. Trait methods with receiver of type `A`.
-1. Trait methods with receiver of type `&A`.
-1. Trait methods with receiver of type `&mut A`.
-1. If it's possible, Rust will then repeat steps 1-5 with
-  `<A as std::ops::Deref>::Target`, and insert a dereference operator.
-1. If `A` is now an [array] type, then repeat steps 1-4 with the corresponding
-  slice type.
-
-Note: In steps 1-4, the receiver is used, not the type of `Self` nor the
-type of `A`. For example:
-
-```rust,ignore
-// `Self` is `&A`, receiver is `&A`.
-impl<'a> Trait for &'a A {
-    fn method(self) {}
+When resolving method calls on an expression of type `A`, Rust looks up methods
+both on the type itself and the traits in implements. Additionally, unlike with
+non-method function calls, the `self` parameter is special and may be
+automatically dereferenced in order to resolve it. Rust uses the following
+process to resolve method calls.
+
+First, Rust will attempt to build a list of candidate receiver types. It obtains
+these by repeatedly [dereferencing][dereference] the type, adding each type
+encountered to the list, then finally attempting an [unsized coercion] at the
+end, and adding the result type if that is successful. Then, for each candidate
+`T`, Rust adds `&T` and `&mut T` to the list immediately afterward.
+
+So, for instance, if `A` is `Box<[i32;2]>`, then the candidate types will be
+`Box<[i32;2]>`, `&Box<[i32;2]>`, `&mut Box<[i32;2]>`, `[i32; 2]` (by
+dereferencing), `&[i32; 2]`, `&mut [i32; 2]`, `[i32]` (by unsized coercion),
+`&[i32]`, and finally `&mut [i32]`.
+
+Then, for each candidate type `T`, Rust will search for a [visible] method with
+a receiver of that type in the following places:
+
+1. `T`'s inherent methods (methods implemented directly on `T`).
+1. Any of the methods provided by a trait implemented by `T`. If `T` is
+   a type parameter (including the `Self` parameter of a trait), then only
+   methods from the trait constraints on `T` are available for lookup. If `T` is
+   not, then methods from any in-scope trait are available.
+
+Note that the lookup is done for each type in order, which can occasionally lead
+to surprising results. The below code will print "In trait impl!", because
+`&self` methods are looked up first, the trait method is found before the
+struct's `&mut self` method is found.
+
+```rust
+struct Foo {}
+
+trait Bar {
+  fn bar(&self);
+}
+
+impl Foo {
+  fn bar(&mut self) {
+    println!("In struct impl!")
+  }
 }
-// If `A` is `&B`, then `Self` is `B` and the receiver is `A`.
-impl B {
-    fn method(&self) {}
+
+impl Bar for Foo {
+  fn bar(&self) {
+    println!("In trait impl!")
+  }
+}
+
+fn main() {
+  let mut f = Foo{};
+  f.bar();
 }
 ```
 
-Another note: this process does not use the mutability or lifetime of the
-receiver, or whether `unsafe` methods can currently be called to resolve
-methods. These constraints instead lead to compiler errors.
+If this results in multiple possible candidates, then it is an error, and the
+receiver must be [converted][disambiguate call] to an appropriate receiver type
+to make the method call.
+
+The lookup process does not take into account the mutability or lifetime of the
+receiver, or whether a method is `unsafe`. Once a method is looked up.
 
 If a step is reached where there is more than one possible method, such as where
 generic methods or traits are considered the same, then it is a compiler
@@ -64,4 +94,5 @@ and function invocation.
 [visible]: visibility-and-privacy.html
 [array]: types.html#array-and-slice-types
 [trait objects]: types.html#trait-objects
-[disambiguating function call syntax]: expressions/call-expr.html#disambiguating-function-calls
+[disambiguate call]: expressions/call-expr.html#disambiguating-function-calls
+[dereference]: expressions/operator-expr.html#the-dereference-operator

src/type-coercions.md

@@ -38,6 +38,9 @@ sites are:
   }
   ```
 
+  For method calls, the receiver (`self` parameter) can only take advantage
+  of [unsized coercions](#unsafe-coercions).
+
 * Instantiations of struct or variant fields
 
   For example, `42` is coerced to have type `i8` in the following:
@@ -130,20 +133,28 @@ Coercion is allowed between the following types:
 
 * `&mut T` to `&mut U` if `T` implements `DerefMut<Target = U>`.
 
-* TyCtor(`T`) to TyCtor(coerce_inner(`T`)), where TyCtor(`T`) is one of
+* TyCtor(`T`) to TyCtor(`U`), where TyCtor(`T`) is one of
     - `&T`
     - `&mut T`
     - `*const T`
     - `*mut T`
     - `Box<T>`
 
-    and where
-    - coerce_inner(`[T, ..n]`) = `[T]`
-    - coerce_inner(`T`) = `U` where `T` is a concrete type which implements the
-    trait `U`.
+    and where `T` can obtained from `U` by [unsized coercion](#unsized-coercion).
 
     <!--In the future, coerce_inner will be recursively extended to tuples and
     structs. In addition, coercions from sub-traits to super-traits will be
     added. See [RFC 401] for more details.-->
 
 * Non capturing closures to `fn` pointers
+
+### Unsized Coercions
+
+The following coercions are called `unsized coercions`, since they
+relate to converting sized types to unsized types, and are permitted in a few
+cases where other coercions are not, as described above. They can still happen anywhere else a coercion can occur.
+
+* `[T; n]` to `[T]`.
+
+* `T` to `U`, when `U` is a trait object type and either `T` implements `U` or
+  `T` is a trait object for a subtrait of `U`.