Provide more explanation for Deref in String docs #43721

natboehm · 2017-08-07T18:43:47Z

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, 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

rust-highfive · 2017-08-07T18:43:52Z

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @steveklabnik (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

kennytm · 2017-08-07T19:48:37Z

src/liballoc/string.rs

+///
+/// What would work in this case is changing the line
+/// `example_func(&example_string);` to 
+/// `example_func(example_string.to_str());`. This works because we're doing


I think the idiomatic solution is call it like this:

example_func(&*example_string);

You dereference a String into a str, and then reference the str back to a &str.

I do think that &* is slightly more idiomatic, but it's also harder to understand. I think showing both is probably a good idea, because people will see &* in the wild.

Cool, I'll make the change. I like the idea of having both options in there, thanks!

kennytm · 2017-08-07T19:49:09Z

src/liballoc/string.rs

+/// ```
+///
+/// What would work in this case is changing the line
+/// `example_func(&example_string);` to 


This line has a trailing whitespace making CI to reject the commit.

[00:03:44] tidy error: /checkout/src/liballoc/string.rs:187: trailing whitespace [00:03:45] some tidy checks failed

steveklabnik

Sorry, one last tiny nit! r=me after this is fixed

steveklabnik · 2017-08-08T19:33:49Z

src/liballoc/string.rs

 ///
+/// In certain cases Rust doesn't have enough information to make this
+/// conversion, known as deref coercion. In the following example a string


this should be

`Deref`

since it's the name of a trait

steveklabnik · 2017-08-08T20:57:47Z

@bors: r+ rollup

bors · 2017-08-08T20:57:47Z

📌 Commit fac6ce7 has been approved by steveklabnik

@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

Rollup of 18 pull requests - Successful merges: #43176, #43632, #43650, #43712, #43715, #43721, #43739, #43741, #43744, #43747, #43752, #43760, #43773, #43779, #43783, #43791, #43793, #43795 - Failed merges:

@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

natboehm added 2 commits August 4, 2017 12:25

Update String Deref to explain why using &String does not always work

b298a58

Update explanation of deref coercion

2a62b91

rust-highfive assigned steveklabnik Aug 7, 2017

kennytm reviewed Aug 7, 2017

View reviewed changes

arielb1 added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Aug 8, 2017

Update solution to add using &* as well as as_str()

40f5b30

steveklabnik reviewed Aug 8, 2017

View reviewed changes

Fix trait name Deref

fac6ce7

GuillaumeGomez mentioned this pull request Aug 11, 2017

Rollup of 18 pull requests #43800

Merged

MaloJaffre mentioned this pull request Aug 11, 2017

Rollup of 19 pull requests #43802

Closed

bors merged commit fac6ce7 into rust-lang:master Aug 11, 2017

natboehm deleted the patch-1 branch August 11, 2017 14:23

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Provide more explanation for Deref in String docs #43721

Provide more explanation for Deref in String docs #43721

natboehm commented Aug 7, 2017

rust-highfive commented Aug 7, 2017

kennytm Aug 7, 2017

steveklabnik Aug 8, 2017 •

edited

Loading

natboehm Aug 8, 2017

kennytm Aug 7, 2017

steveklabnik left a comment

steveklabnik Aug 8, 2017

steveklabnik commented Aug 8, 2017

bors commented Aug 8, 2017

Provide more explanation for Deref in String docs #43721

Provide more explanation for Deref in String docs #43721

Conversation

natboehm commented Aug 7, 2017

rust-highfive commented Aug 7, 2017

kennytm Aug 7, 2017

Choose a reason for hiding this comment

steveklabnik Aug 8, 2017 • edited Loading

Choose a reason for hiding this comment

natboehm Aug 8, 2017

Choose a reason for hiding this comment

kennytm Aug 7, 2017

Choose a reason for hiding this comment

steveklabnik left a comment

Choose a reason for hiding this comment

steveklabnik Aug 8, 2017

Choose a reason for hiding this comment

steveklabnik commented Aug 8, 2017

bors commented Aug 8, 2017

steveklabnik Aug 8, 2017 •

edited

Loading