Clarify behavior of HashSet::insert when there's existing key

[stepancheg]

Location

https://doc.rust-lang.org/std/collections/struct.HashSet.html#method.insert

Summary

HashSet::insert is underspecified.

It says:

If the set already contained this value, false is returned.

But when the set already contains a value, is existing value replaced with new, or new value just discarded?

It does not make difference for primitive types, but can have significant effect when inserting Arc for example.

[GuillaumeGomez]

In case the entry already exists, it uses mem::replace() as you can see here (HashSet comes from the hashbrown crate and is in fact a HashMap without a value). But indeed, updating the docs to mention would be nice. Want to send a PR?

[cuviper]

That mem::replace is only on the map value, which is () for a set. The key is not modified.