Remove implicit shrinking from hash_map.

[pczarn]

Part of enforcing capacity-related conventions, for #18424, the collections reform.

Implements fn shrink_to_fit for HashMap.
The reserve method now takes as an argument the extra space to reserve.

[huonw]

Preferably the reserve method change would be a in separate commit with a [breaking-change] marker.

[pczarn]

Done. It's a little unintuitive that a breaking-change probably won't break any code.

[Gankra]

I would just drop "the range" here

[Gankra]

All the actual implementation logic looks good to me. Just some doc nits, and some issues about the precision we can assume for resize in testing.

[Gankra]

Oh! Hashset's capacity stuff is probably all wrong now. Probably best to fix that up in this PR too? (should just be doc, maybe test changes)

[Gankra]

This all looks basically good to me now. Just need a real reviewer to take a look. Might want to update some tests to reflect newer semantics but it's not a big deal. Also might want to wait for @aturon to make a proclamation about how we want to map capacity() to internal vs usable capacity.

r? @huonw

[huonw]

It's a little unintuitive that a breaking-change probably won't break any code.

This is breaking code: it will not stop things from compiling, but it is dramatically changing semantics and could, e.g. cause code that previously worked fine to run out of memory (map.reserve(x) becomes equivalent to map.reserve(map.len() + x) in the old code).

[huonw]

Does this handle arithmetic overflow correctly?

[aturon]

@gankro

Also might want to wait for @aturon to make a proclamation about how we want to map capacity() to internal vs usable capacity.

Usable capacity, for sure. Everything else is an implementation detail that should be hidden. If we ever want to be able to use capacity and reserve generically in the future, this is the right way to go IMO.

[pczarn]

Updated with usable capacity

[Gankra]

Whoops, this slipped through the cracks. I believe all of my issues were addressed. @huonw anything outstanding for you?

[huonw]

Is the required property just min_capacity(usable_capacity(x)) <= x? Because this is always true for positive x: integer division is floored, not just some unspecified rounding, i.e. (cap / 11) * 11 <= cap always.

(I'm just raising this because that property means this comment is slightly confusing to me, as it is either redundant or talking about something else entirely.)

[pczarn]

Done. Hopefully I got capacity equality right.