Rollup merge of #43721 - natboehm:patch-1, r=steveklabnik

Provide more explanation for Deref in String docs

While working on a different project I encountered a point of confusion where using `&String` to dereference a `String` into `&str` did not compile. I found the explanation of [String Deref](https://doc.rust-lang.org/std/string/struct.String.html#deref), thought that it matched what I was trying to do, and was confused as to why my program did not compile when the docs stated that it would work with 'any function which takes a `&str`'. At the bottom it is mentioned that this will 'generally' work, unless `String` is needed, but I found this statement confusing based on the previous claim of 'any'. Looking further into the docs I was able to find the function `as_str()` that works instead.

I thought it might be helpful to mention here deref coercion, an instance in which using `&String` does not work, to explain why it does not work, then direct users to a different option that should work in this instance. A user casually skimming the page will likely come to this explanation first, then find `as_str()` later, but be no the wiser as to what potentially went wrong.

r? @steveklabnik

1 files changed, 32 insertions, 2 deletions

diff --git a/src/liballoc/string.rs b/src/liballoc/string.rs
index 622cc68964b..322b137e99f 100644
--- a/src/liballoc/string.rs
+++ b/src/liballoc/string.rs
@@ -144,7 +144,7 @@ use boxed::Box;
 /// # Deref
 ///
 /// `String`s implement [`Deref`]`<Target=str>`, and so inherit all of [`str`]'s
-/// methods. In addition, this means that you can pass a `String` to any
+/// methods. In addition, this means that you can pass a `String` to a
 /// function which takes a [`&str`] by using an ampersand (`&`):
 ///
 /// ```
@@ -160,8 +160,38 @@ use boxed::Box;
 ///
 /// This will create a [`&str`] from the `String` and pass it in. This
 /// conversion is very inexpensive, and so generally, functions will accept
-/// [`&str`]s as arguments unless they need a `String` for some specific reason.
+/// [`&str`]s as arguments unless they need a `String` for some specific
+/// reason.
 ///
+/// In certain cases Rust doesn't have enough information to make this
+/// conversion, known as `Deref` coercion. In the following example a string
+/// slice `&'a str` implements the trait `TraitExample`, and the function
+/// `example_func` takes anything that implements the trait. In this case Rust
+/// would need to make two implicit conversions, which Rust doesn't have the
+/// means to do. For that reason, the following example will not compile.
+///
+/// ```compile_fail,E0277
+/// trait TraitExample {}
+///
+/// impl<'a> TraitExample for &'a str {}
+///
+/// fn example_func<A: TraitExample>(example_arg: A) {}
+///
+/// fn main() {
+///     let example_string = String::from("example_string");
+///     example_func(&example_string);
+/// }
+/// ```
+///
+/// There are two options that would work instead. The first would be to
+/// change the line `example_func(&example_string);` to
+/// `example_func(example_string.as_str());`, using the method `as_str()`
+/// to explicitly extract the string slice containing the string. The second
+/// way changes `example_func(&example_string);` to
+/// `example_func(&*example_string);`. In this case we are dereferencing a
+/// `String` to a `str`, then referencing the `str` back to `&str`. The
+/// second way is more idiomatic, however both work to do the conversion
+/// explicitly rather than relying on the implicit conversion.
 ///
 /// # Representation
 ///