std: Stabilize the std::hash module

This commit aims to prepare the `std::hash` module for alpha by formalizing its
current interface whileholding off on adding `#[stable]` to the new APIs.  The
current usage with the `HashMap` and `HashSet` types is also reconciled by
separating out composable parts of the design. The primary goal of this slight
redesign is to separate the concepts of a hasher's state from a hashing
algorithm itself.

The primary change of this commit is to separate the `Hasher` trait into a
`Hasher` and a `HashState` trait. Conceptually the old `Hasher` trait was
actually just a factory for various states, but hashing had very little control
over how these states were used. Additionally the old `Hasher` trait was
actually fairly unrelated to hashing.

This commit redesigns the existing `Hasher` trait to match what the notion of a
`Hasher` normally implies with the following definition:

    trait Hasher {
        type Output;
        fn reset(&mut self);
        fn finish(&self) -> Output;
    }

This `Hasher` trait emphasizes that hashing algorithms may produce outputs other
than a `u64`, so the output type is made generic. Other than that, however, very
little is assumed about a particular hasher. It is left up to implementors to
provide specific methods or trait implementations to feed data into a hasher.

The corresponding `Hash` trait becomes:

    trait Hash<H: Hasher> {
        fn hash(&self, &mut H);
    }

The old default of `SipState` was removed from this trait as it's not something
that we're willing to stabilize until the end of time, but the type parameter is
always required to implement `Hasher`. Note that the type parameter `H` remains
on the trait to enable multidispatch for specialization of hashing for
particular hashers.

Note that `Writer` is not mentioned in either of `Hash` or `Hasher`, it is
simply used as part `derive` and the implementations for all primitive types.

With these definitions, the old `Hasher` trait is realized as a new `HashState`
trait in the `collections::hash_state` module as an unstable addition for
now. The current definition looks like:

    trait HashState {
        type Hasher: Hasher;
        fn hasher(&self) -> Hasher;
    }

The purpose of this trait is to emphasize that the one piece of functionality
for implementors is that new instances of `Hasher` can be created.  This
conceptually represents the two keys from which more instances of a
`SipHasher` can be created, and a `HashState` is what's stored in a
`HashMap`, not a `Hasher`.

Implementors of custom hash algorithms should implement the `Hasher` trait, and
only hash algorithms intended for use in hash maps need to implement or worry
about the `HashState` trait.

The entire module and `HashState` infrastructure remains `#[unstable]` due to it
being recently redesigned, but some other stability decision made for the
`std::hash` module are:

* The `Writer` trait remains `#[experimental]` as it's intended to be replaced
  with an `io::Writer` (more details soon).
* The top-level `hash` function is `#[unstable]` as it is intended to be generic
  over the hashing algorithm instead of hardwired to `SipHasher`
* The inner `sip` module is now private as its one export, `SipHasher` is
  reexported in the `hash` module.

And finally, a few changes were made to the default parameters on `HashMap`.

* The `RandomSipHasher` default type parameter was renamed to `RandomState`.
  This renaming emphasizes that it is not a hasher, but rather just state to
  generate hashers. It also moves away from the name "sip" as it may not always
  be implemented as `SipHasher`. This type lives in the
  `std::collections::hash_map` module as `#[unstable]`

* The associated `Hasher` type of `RandomState` is creatively called...
  `Hasher`! This concrete structure lives next to `RandomState` as an
  implemenation of the "default hashing algorithm" used for a `HashMap`. Under
  the hood this is currently implemented as `SipHasher`, but it draws an
  explicit interface for now and allows us to modify the implementation over
  time if necessary.

There are many breaking changes outlined above, and as a result this commit is
a:

[breaking-change]

src/test/bench/core-set.rs

@@ -18,6 +18,7 @@ extern crate rand;
 use std::collections::BTreeSet;
 use std::collections::BitvSet;
 use std::collections::HashSet;
+use std::collections::hash_map::Hasher;
 use std::hash::Hash;
 use std::os;
 use std::time::Duration;
@@ -43,7 +44,7 @@ trait MutableSet<T> {
     fn contains(&self, k: &T) -> bool;
 }
 
-impl<T: Hash + Eq> MutableSet<T> for HashSet<T> {
+impl<T: Hash<Hasher> + Eq> MutableSet<T> for HashSet<T> {
     fn insert(&mut self, k: T) { self.insert(k); }
     fn remove(&mut self, k: &T) -> bool { self.remove(k) }
     fn contains(&self, k: &T) -> bool { self.contains(k) }

src/test/run-pass/deriving-hash.rs

@@ -8,9 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-
-use std::hash;
-use std::hash::Hash;
+use std::hash::{Hash, SipHasher};
 
 #[derive(Hash)]
 struct Person {
@@ -19,6 +17,10 @@ struct Person {
     phone: uint,
 }
 
+fn hash<T: Hash<SipHasher>>(t: &T) -> u64 {
+    std::hash::hash::<T, SipHasher>(t)
+}
+
 fn main() {
     let person1 = Person {
         id: 5,
@@ -30,6 +32,6 @@ fn main() {
         name: "Bob".to_string(),
         phone: 555_666_7777
     };
-    assert!(hash::hash(&person1) == hash::hash(&person1));
-    assert!(hash::hash(&person1) != hash::hash(&person2));
+    assert!(hash(&person1) == hash(&person1));
+    assert!(hash(&person1) != hash(&person2));
 }

src/test/run-pass/deriving-meta-multiple.rs

@@ -9,7 +9,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-use std::hash::hash;
+use std::hash::{Hash, SipHasher};
 
 // testing multiple separate deriving attributes
 #[derive(PartialEq)]
@@ -20,6 +20,8 @@ struct Foo {
     baz: int
 }
 
+fn hash<T: Hash<SipHasher>>(_t: &T) {}
+
 pub fn main() {
     let a = Foo {bar: 4, baz: -3};
 

src/test/run-pass/deriving-meta.rs

@@ -9,7 +9,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-use std::hash::hash;
+use std::hash::{Hash, SipHasher};
 
 #[derive(PartialEq, Clone, Hash)]
 struct Foo {
@@ -17,6 +17,8 @@ struct Foo {
     baz: int
 }
 
+fn hash<T: Hash<SipHasher>>(_t: &T) {}
+
 pub fn main() {
     let a = Foo {bar: 4, baz: -3};
 

src/test/run-pass/typeid-intrinsic.rs

@@ -14,7 +14,7 @@
 extern crate "typeid-intrinsic" as other1;
 extern crate "typeid-intrinsic2" as other2;
 
-use std::hash;
+use std::hash::{self, SipHasher};
 use std::intrinsics;
 use std::intrinsics::TypeId;
 
@@ -70,5 +70,6 @@ pub fn main() {
     // check it has a hash
     let (a, b) = (TypeId::of::<uint>(), TypeId::of::<uint>());
 
-    assert_eq!(hash::hash(&a), hash::hash(&b));
+    assert_eq!(hash::hash::<TypeId, SipHasher>(&a),
+               hash::hash::<TypeId, SipHasher>(&b));
 }