No mention of concatenation in std::string::String docs

[mrmonday]

In the documentation for std::string::String, there is no mention of concatenation - it's not obvious that the + operator is used for concatenation, nor that it is restricted to String + &str, and not, eg. String + String.

There should be an example showing how to concatenate/format the different string types, or, at the very least, a mention of the word 'concatenate', to allow easy searching.

[bluss]

Might be worth to mention all of +, format!(), [S].concat() and [S].join(sep)

[ollie27]

Should + really be documented? It just does the same as push_str so I don't know why you'd use it.

It would be useful to mention write! as a way to concatenate as well.

[bluss]

.push_str() is for mutate in place while a + &b consumes a and returns a new string, so it's convenient in many circumstances. Note that since only String + &str exists and that the string is consumed (its allocation simply reallocated), it's very hard to run into the quadratic concatenation trap of some languages.

[ollie27]

I understand that it can be convenient but all other methods that mutate Strings work in place so it seems really inconsistent to have a special one that doesn't.

[steveklabnik]

part of #29376