Add a doctest for the std::string::as_string method.

[jbranchaud]

No description provided.

[jbranchaud]

Sure thing!

[jbranchaud]

@steveklabnik Is "Examples" supposed to be the standard convention? I am noticing the occurrence of "Example" a number of places throughout the API docs. If so, I can try to update some of these other offending instances in a separate PR as well.

[steveklabnik]

We haven't officially made a convention because I haven't had the chance to write up the RFC, but you're correct that they're scattered. I wouldn't mind a PR updating them to all say "Examples," even if we eventually decide on a different convention, it's easier to change if they're all the same.

[jbranchaud]

Updated.

[bluss]

Intrusive comment! :-)

I'm worried about "Doctest". Providing examples in documentation is great, it's a good goal. Testing functions through it is not -- there are much better ways to do that using the testing infrastructure.

So they should be useful examples first. The reason they are tested is just to make sure they continue to be up to date and correct.

With this in mind, the example in the PR is not very instructive to the reader of the documentation.

[bluss]

I should be constructive too, It's hard to find a good example truly, what do you think about this?

use std::string::as_string;

fn stringconsumer(s: &String) {
    assert_eq!(s, &"foo");
}

stringconsumer(&*as_string("foo"));

[jbranchaud]

Updated based on feedback from @bluss.

@bluss Thanks for your suggestion and for providing an example, I've incorporated your feedback.

[steveklabnik]

Taking a &String is almost never what we want, can we make this a String and

[steveklabnik]

r=me with the updated example changes

[jbranchaud]

Updated.

[steveklabnik]

Thank you so much!

[bluss]

Friends, the example misses the point of as_string: it allows creating a &String using no allocation at all. It's a special case, half-obsoleted by BorrowFrom solutions in the HashMap instead, but that's the usecase of as_string.

The reason any example is contrieved is that there are no use cases I can think of, but what it used to be was that a certain interface needed &String, and this was a way to supply it without allocation. Creating a plain allocated String is easy using other means.