diff --git a/src/doc/trpl/strings.md b/src/doc/trpl/strings.md index c354fd09edd8..55154036286d 100644 --- a/src/doc/trpl/strings.md +++ b/src/doc/trpl/strings.md @@ -49,6 +49,20 @@ fn main() { } ``` +This coercion does not happen for functions that accept one of `&str`’s traits +instead of `&str`. For example, [`TcpStream::connect`][connect] has a parameter +of type `ToSocketAddrs`. A `&str` is okay but a `String` must be explicitly +converted using `&*`. + +```rust,no_run +use std::net::TcpStream; + +TcpStream::connect("192.168.0.1:3000"); // &str parameter + +let addr_string = "192.168.0.1:3000".to_string(); +TcpStream::connect(&*addr_string); // convert addr_string to &str +``` + Viewing a `String` as a `&str` is cheap, but converting the `&str` to a `String` involves allocating memory. No reason to do that unless you have to! @@ -127,3 +141,4 @@ This is because `&String` can automatically coerce to a `&str`. This is a feature called ‘[`Deref` coercions][dc]’. [dc]: deref-coercions.html +[connect]: ../std/net/struct.TcpStream.html#method.connect