std: Stabilize custom hasher support in HashMap

[alexcrichton]

This commit implements the stabilization of the custom hasher support intended
for 1.7 but left out due to some last-minute questions that needed some
decisions. A summary of the actions done in this PR are:

Stable

• std::hash::BuildHasher
• BuildHasher::Hasher
• BuildHasher::build_hasher
• std::hash::BuildHasherDefault
• HashMap::with_hasher
• HashMap::with_capacity_and_hasher
• HashSet::with_hasher
• HashSet::with_capacity_and_hasher
• std::collections::hash_map::RandomState
• RandomState::new

Deprecated

• std::collections::hash_state
• std::collections::hash_state::HashState - this trait was also moved into
  std::hash with a reexport here to ensure that we can have a blanket impl to
  prevent immediate breakage on nightly. Note that this is unstable in both
  location.
• HashMap::with_hash_state - renamed
• HashMap::with_capacity_and_hash_state - renamed
• HashSet::with_hash_state - renamed
• HashSet::with_capacity_and_hash_state - renamed

Closes #27713

[rust-highfive]

r? @nikomatsakis

(rust_highfive has picked a reviewer for you, use r? to override)

[alexcrichton]

r? @aturon

cc @rust-lang/libs

nominating for a beta-backport

[Gankro]

CC @pczarn @carllerche @apasel422 @bluss @shepmaster

[shepmaster]

Everything here seems reasonable and as was discussed. 👍

[aturon]

Should we give the same warning about DoS here?

[aturon]

Ooops, github just had it collapsed, nevermind.

[aturon]

Can you remind me why we take &self here, given that you're describing the trait in terms of being state that's used to generate new hashers? We seem to force you to interior mutability here, presumably for good reason?

[shepmaster]

Each T::Hasher has to have the same initial state - otherwise hashing the same thing twice wouldn't have the same hash. When this function is called, it shouldn't be doing a whole lot.

For example a factory constructed with a random seed. You don't see the non-random seed in my code because it's piggybacking on the implementation provided by DefaultState

[aturon]

OK, I think the problem is just that the docs here are very misleading:

• "A trait representing stateful hashes ..."
• "Creates a new hasher based on the given state of this object"

Both of those strongly suggested to me that mutation is expected here.

[alexcrichton]

Oh actually the HashState trait is basically dead/to be ignored, the relevant documentation on the BuildHasher trait (the real one now) is:

/// A trait representing an object which maintains state to create new instances
/// of the `Hasher` trait.                                                      
///                                                                             
/// A `BuildHasher` is typically used as a factory for instances of `Hasher`    
/// which a `HashMap` can then use to hash keys independently.                  

Does that sound ok?

I'll clear out the old documentation in favor of just saying it's deprecated.

[aturon]

Those are the docs I was referencing :) Look above -- the BuildHasher trait method docs say "Creates a new hasher based on the given state of this object", which is what I was quoting. My point is just that these docs strongly suggest mutable state to me. Not a huge deal, but I found it pretty confusing.

[alexcrichton]

Ah ok I think I see what you're getting at now. Do you have a rewording in mind? I could try and wordsmith a bit as well and see what I can come up with

[aturon]

LGTM -- though I did leave one question about the actual API. I suspect I'm just failing to remember one of the design constraints here.

[alexcrichton]

@aturon I've updated with removing the old and misleading HashState documentation, and as @shepmaster mentioned the &self is because these are just hash factories as opposed to hashers themselves. The &self is required to work because hashers need to be created in the fn get(&self) function on a HashMap.

[sfackler]

This looks good to go, right?

[aturon]

@alexcrichton corrected the wrong docs problem :) I still find the docs super misleading, but we can fix in post if you prefer. That's my only complaint.

[alexcrichton]

I'm fine changing the docs, but I'm not really quite sure what to change them to? Do you have something in mind @aturon ?

[aturon]

Suggestion: nix this sentence.

[aturon]

Suggestion: shorten to Creates a new hasher

[aturon]

@alexcrichton Left some minimal suggestions. With that r=me.

[alexcrichton]

@bors: r=aturon 1fa0be2

[bors]

⌛️ Testing commit 1fa0be2 with merge a9e139b...

[bors]

☀️ Test successful - auto-linux-32-nopt-t, auto-linux-32-opt, auto-linux-64-debug-opt, auto-linux-64-nopt-t, auto-linux-64-opt, auto-linux-64-x-android-t, auto-linux-cross-opt, auto-linux-musl-64-opt, auto-mac-32-opt, auto-mac-64-nopt-t, auto-mac-64-opt, auto-win-gnu-32-nopt-t, auto-win-gnu-32-opt, auto-win-gnu-64-nopt-t, auto-win-gnu-64-opt, auto-win-msvc-32-opt, auto-win-msvc-64-opt

[alexcrichton]

Marking as accepted for beta as libs talked about this awhile ago