std: Stabilize custom hasher support in HashMap

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:#️⃣:BuildHasher`
* `BuildHasher::Hasher`
* `BuildHasher::build_hasher`
* `std:#️⃣: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

src/libcore/hash/mod.rs

@@ -73,6 +73,7 @@
 
 use prelude::v1::*;
 
+use marker;
 use mem;
 
 #[stable(feature = "rust1", since = "1.0.0")]
@@ -190,6 +191,77 @@ pub trait Hasher {
     }
 }
 
+/// A `BuildHasher` is typically used as a factory for instances of `Hasher`
+/// which a `HashMap` can then use to hash keys independently.
+///
+/// Note that for each instance of `BuildHasher` the create hashers should be
+/// identical. That is if the same stream of bytes is fed into each hasher the
+/// same output will also be generated.
+#[stable(since = "1.7.0", feature = "build_hasher")]
+pub trait BuildHasher {
+    /// Type of the hasher that will be created.
+    #[stable(since = "1.7.0", feature = "build_hasher")]
+    type Hasher: Hasher;
+
+    /// Creates a new hasher.
+    #[stable(since = "1.7.0", feature = "build_hasher")]
+    fn build_hasher(&self) -> Self::Hasher;
+}
+
+/// A structure which implements `BuildHasher` for all `Hasher` types which also
+/// implement `Default`.
+///
+/// This struct is 0-sized and does not need construction.
+#[stable(since = "1.7.0", feature = "build_hasher")]
+pub struct BuildHasherDefault<H>(marker::PhantomData<H>);
+
+#[stable(since = "1.7.0", feature = "build_hasher")]
+impl<H: Default + Hasher> BuildHasher for BuildHasherDefault<H> {
+    type Hasher = H;
+
+    fn build_hasher(&self) -> H {
+        H::default()
+    }
+}
+
+#[stable(since = "1.7.0", feature = "build_hasher")]
+impl<H> Clone for BuildHasherDefault<H> {
+    fn clone(&self) -> BuildHasherDefault<H> {
+        BuildHasherDefault(marker::PhantomData)
+    }
+}
+
+#[stable(since = "1.7.0", feature = "build_hasher")]
+impl<H> Default for BuildHasherDefault<H> {
+    fn default() -> BuildHasherDefault<H> {
+        BuildHasherDefault(marker::PhantomData)
+    }
+}
+
+// The HashState trait is super deprecated, but it's here to have the blanket
+// impl that goes from HashState -> BuildHasher
+
+/// Deprecated, renamed to `BuildHasher`
+#[unstable(feature = "hashmap_hasher", reason = "hasher stuff is unclear",
+           issue = "27713")]
+#[rustc_deprecated(since = "1.7.0", reason = "support moved to std::hash and \
+                                              renamed to BuildHasher")]
+pub trait HashState {
+    /// Type of the hasher that will be created.
+    type Hasher: Hasher;
+
+    /// Creates a new hasher based on the given state of this object.
+    fn hasher(&self) -> Self::Hasher;
+}
+
+#[unstable(feature = "hashmap_hasher", reason = "hasher stuff is unclear",
+           issue = "27713")]
+#[allow(deprecated)]
+impl<T: HashState> BuildHasher for T {
+    type Hasher = T::Hasher;
+    fn build_hasher(&self) -> T::Hasher { self.hasher() }
+}
+
 //////////////////////////////////////////////////////////////////////////////
 
 mod impls {