HashMap using &str keys is not a a realistic example

[kornelski]

The example in the docs uses HashMap of &str:

https://doc.rust-lang.org/std/collections/struct.HashMap.html#examples

but this gives bad example to users who copy the example without fully realizing consequences of using &str instead of String. Here's thread by a new user lead down a confusing path because of this example: https://users.rust-lang.org/t/how-to-pass-slice-of-structs-string-field/14586

I suggest using String instead, even if that means a bit more noise from to_owned().

[GuillaumeGomez]

I'm not 100% sure it's a good idea. The point is to show how to use it. It'd give a bad example if we used String instead of &str when it's not needed, don't you think?

[kornelski]

No, I think String is clearly better.

For advanced users it doesn't matter, as they'll see the HashMap API regardless of key type used.

But for novice users nudging towards String is much safer — it's more likely to be the right thing. The worst case is some overhead and need to call .to_string(), which is easier to figure out for novice users than whack-a-mole of lifetime annotations and borrow checker errors.

I've filed this issue because this example has actually mislead a new Rust user.

[GuillaumeGomez]

The issue is kinda the same: either we show users that they should use String all the time (even when unneeded) or we show an example that we'll let them think that they should always use &str instead of String. Complicated writing doc is...

[JoshLambda]

Choosing &str over String is a matter of always using idiomatic code in examples. (It is not a matter of overhead or optimization.)
Using String in this example would not be the idiomatic way to proceed. So, to use String and still have idiomatic code the example would have to be changed completely.

[kornelski]

I've left one example with &str, but changed it to &'static str. I think this way users won't get impression the sets work only with String, but also the extra lifetime will make it easier to find that it's a special case.

[JoshLambda]

I understand your intent and I commend you for trying to address this issue. But even if the user can be confused I would still think idiomatic code has the priority, simply because idiomatic code is to be expected in every examples.

In the same way, you wouldn't expect a (natural) language teaching book to give out some weird translations just for orthogonal reasons. In facts, the documentation is the main place where to learn idiomatic code, that's why it should be expected.

I understand this is probably not the best place to debate it though. I'm curious to see the outcome of it.

About your commits, wouldn't using &'static str only at one place make things more confusing? Wouldn't the reader ask himself : "Why did they use &'static str and not String"? Just wondering...

[kornelski]

idiomatic code is to be expected in every examples

Note that code packed in a single function, operating on string literals, is not representative of real-world Rust code. What is idiomatic for such a special case, is not idiomatic for Rust in general.

In Rust's own codebase: HashMap<String is in 56 files. HashMap<&'lifetime str is 8 files. HashMap<&str is only in these examples. So these examples are idiomatic examples of un-idiomatic Rust.

[matklad]

Looks like this is fixed now?