Guide: strings

[steveklabnik]

I decided to change it up a little today and hack out the beginning of the String guide. Strings are different enough in Rust that I think they deserve a specific guide, especially for those who are used to managed languages.

I decided to start with Strings because they get asked about a lot in IRC, and also based on discussions like this one on reddit: http://www.reddit.com/r/rust/comments/2ac390/generic_string_literals/

I blatantly stole bits from our other documentation on Strings. It's a little sparse at current, but I wanted to start somewhere.

I am not exactly sure what should go in "Best Practices," and would like the feedback from the team on this. Specifically due to comments like this one: http://www.reddit.com/r/rust/comments/2ac390/generic_string_literals/citmxb5

[lilyball]

Technically incorrect. It's a sequence of unicode scalar values. Notably, U+D800 is a codepoint, but it's not a scalar value.

For reference, we already talk about unicode scalar values in the documentation for std::char.

[steveklabnik]

This needs to be changed in the std::str documentation, then.

[lilyball]

Probably true. I haven't actually read that in a while. But let's focus on making a good strings guide, then we can go back and fix up the API documentation as appropriate.

[steveklabnik]

Of course, I only make mention of it to document where I gained the wrong impression from, and to make sure that I change that as well.

[MatejLach]

@kud1ing

Seriously? It's an introductory sentence that's meant to get the reader into the text. It doesn't have to "add" anything really. I also takes nothing away.
I really hate how every single sentence in technical docs supposedly has to be "technical".
We humans are not robots, when one reads a Guide, it should read continuously and smoothly, whereas when I am reading a reference, I am expecting dry, technical information.
A Guide is meant to introduce you into a topic, not be super dry.
Really, check how many people actually red any exclusively-technical docs in any amount of details.

There are many books on programming in various languages that cover topics one can get from the official docs, but people still buy the expensive books, because they're less dry. It's a good think that @steveklabnik wants to make the Guides like a book, there's also the Manual for reference.

Or would we prefer something like the following as our only point of reference:
http://golang.org/ref/spec
Docs like the above link are great for getting a quick glimpse at how to use something, but not to really read about it.

[nielsle]

Perhaps the chapter could focus more on helping the reader to choose the right string type in a given situation. That is the difficult part. (Perhaps add some text add the beginning of the chapter about slices)

It could be nice to have text about concatenating strings, splitting strings and formatting strings.

[nielsle]

Perhaps you should mention here that a slice is not growable.

[steveklabnik]

@nielsle that's my intention for the 'best practices' section.

[steveklabnik]

I've addressed the easy comments, gonna give some thought to the harder ones.

[kud1ing]

@MatejLach: I am believer in "perfection is finally attained not when there is no longer anything to add, but when there is no longer anything to take away". To me this especially applies to documentation, when i am actually busy doing something else other than reading documentation. I am not against collegial writing style, but i always wonder "if this was missing, what would be the reasons to add it? who would say: i want this because ... ?"

[steveklabnik]

I've squashed all those commits together, and added a best practice about comparing strings. What do we think?

[lilyball]

I'm still not happy with the phrasing here, "it has the usual associated lifetime". The goal of this sentence is to convey the idea that the lifetime can be omitted in a lot of cases, right? Omitting the lifetime is of course not limited to just function arguments, you can also say let x: &str = "foo".

Is there some other guide that uses a similar phrasing here that you're trying to reference? If not, I'd suggest perhaps something like

The &str type can be written without an explicit lifetime in many cases, such as in function arguments. In these cases the lifetime will be inferred:

although I feel like it would be good to explicitly correlate this with the inferred lifetimes of arbitrary &T refs.

[steveklabnik]

I like that wording. No connection to anything else, just my own words. I'll change it to that after i'm done rebuilding...