std::borrow::Borrow should have big fat warnings all over it

[chris-morgan]

There are hidden assumptions around Borrow that don’t appear to be included in any of the documentation that I can find. Most notably, HashMap’s use of Borrow requires that K and Q (where K: Borrow<Q>) hash the same; if they don’t, your HashMap will be mysteriously broken when you try indexing it by Q.

I’d suggest making Borrow an unsafe trait, but unsafe doesn’t mean _{blah blah mumble mumble memory safety mumble} 😛

Anyway, we need some serious warnings on at least the Borrow documentation. Something including things like “if you are implementing Borrow and both Self and Borrowed implement Hash, they must produce the same result, for HashMap’s sake.”

[Gankra]

From the trait:

Borrow is very similar to, but different than, AsRef. See the book (link) for more.

From the book:

We can see how they’re kind of the same: they both deal with owned and borrowed versions of some type. However, they’re a bit different.

Choose Borrow when you want to abstract over different kinds of borrowing, or when you’re building a datastructure that treats owned and borrowed values in equivalent ways, such as hashing and comparison.

However I agree it could be more prominent.