Docs, further cleanup.

Author: pczarn

src/libstd/collections/hash/map.rs

@@ -21,9 +21,9 @@ use fmt::{self, Debug};
 use hash::{Hash, SipHasher};
 use iter::{Iterator, ExactSizeIterator, IntoIterator, IteratorExt, FromIterator, Extend, Map};
 use marker::Sized;
-use mem::{self, replace};
+use mem::{self, swap, replace};
 use num::{Int, UnsignedInt};
-use ops::{Deref, DerefMut, Drop, FnMut, Index, IndexMut};
+use ops::{Drop, FnMut, Index, IndexMut};
 use option::Option::{self, Some, None};
 use rand::{self, Rng};
 use result::Result::{self, Ok, Err};
@@ -33,11 +33,9 @@ use super::table::{
     Bucket,
     EmptyBucket,
     FullBucket,
-    FullBucketImm,
     FullBucketMut,
     RawTable,
     SafeHash,
-    TableRef,
     PartialRawTable,
     Put,
 };
@@ -322,13 +320,12 @@ fn search_hashed<K, V, M, F>(table: M,
                              hash: SafeHash,
                              mut is_match: F)
                              -> InternalEntry<K, V, M> where
-    RawTable<K, V>: BorrowFrom<M>,
+    M: Borrow<RawTable<K, V>>,
     F: FnMut(&K) -> bool,
 {
     // Worst case, we'll find one empty bucket among `size + 1` buckets.
-    let table = TableRef(table);
-    let size = table.size();
-    let mut probe = match Bucket::new(table.0, hash) {
+    let size = table.borrow().size();
+    let mut probe = match Bucket::new(table, hash) {
         Some(probe) => probe,
         None => return InternalEntry::TableIsEmpty,
     };
@@ -392,8 +389,8 @@ fn pop_internal<K, V>(starting_bucket: FullBucketMut<K, V>) -> (K, V) {
 fn robin_hood<'a, K: 'a, V: 'a>(bucket: FullBucketMut<'a, K, V>,
                         mut ib: usize,
                         mut hash: SafeHash,
-                        mut k: K,
-                        mut v: V)
+                        mut key: K,
+                        mut val: V)
                         -> &'a mut V {
     let starting_index = bucket.index();
     let size = {
@@ -407,9 +404,11 @@ fn robin_hood<'a, K: 'a, V: 'a>(bucket: FullBucketMut<'a, K, V>,
     let idx_end = starting_index + size - bucket.displacement();
 
     loop {
-        let (old_hash, old_key, old_val) = {
+        {
             let (h_ref, k_ref, v_ref) = bucket.read_mut();
-            (replace(h_ref, hash), replace(k_ref, k), replace(v_ref, v))
+            swap(h_ref, &mut hash);
+            swap(k_ref, &mut key);
+            swap(v_ref, &mut val);
         };
         loop {
             let probe = bucket.into_next();
@@ -418,7 +417,7 @@ fn robin_hood<'a, K: 'a, V: 'a>(bucket: FullBucketMut<'a, K, V>,
             let full_bucket = match probe.peek() {
                 Empty(bucket) => {
                     // Found a hole!
-                    let b = bucket.put(old_hash, old_key, old_val);
+                    let b = bucket.put(hash, key, val);
                     // Now that it's stolen, just read the value's pointer
                     // right out of the table!
                     return b.into_table().into_mut_refs().1;
@@ -433,9 +432,6 @@ fn robin_hood<'a, K: 'a, V: 'a>(bucket: FullBucketMut<'a, K, V>,
             // Robin hood! Steal the spot.
             if ib < probe_ib {
                 ib = probe_ib;
-                hash = old_hash;
-                k = old_key;
-                v = old_val;
                 break;
             }
         }
@@ -444,20 +440,19 @@ fn robin_hood<'a, K: 'a, V: 'a>(bucket: FullBucketMut<'a, K, V>,
 
 // Performs insertion with relaxed requirements.
 // The caller should ensure that invariants of Robin Hood linear probing hold.
-fn insert_hashed_ordered<M: Put, K, V>(arg: M, h: SafeHash, k: K, v: V) -> M
-    where RawTable<K, V>: BorrowFromMut<M>
+fn insert_hashed_ordered<M: Put, K, V>(table: M, hash: SafeHash, key: K, val: V) -> M
+    where M: BorrowMut<RawTable<K, V>>
 {
-    let table = TableRef(arg);
-    let cap = table.capacity();
-    let mut buckets = Bucket::new(table.0, h).unwrap();
+    let cap = table.borrow().capacity();
+    let mut buckets = Bucket::new(table, hash).unwrap();
     let ib = buckets.index();
 
     while buckets.index() != ib + cap {
         // We don't need to compare hashes for value swap.
         // Not even DIBs for Robin Hood.
         buckets = match buckets.peek() {
             Empty(empty) => {
-                return empty.put(h, k, v).into_table();
+                return empty.put(hash, key, val).into_table();
             }
             Full(full) => full.into_bucket()
         };
@@ -477,24 +472,20 @@ impl<K, V, S> HashMap<K, V, S>
     /// Search for a key, yielding the index if it's found in the hashtable.
     /// If you already have the hash for the key lying around, use
     /// search_hashed.
-    fn search<'a, Q: ?Sized>(&'a self, q: &Q) -> Option<FullBucketImm<'a, K, V>>
+    fn search<'a, Q: ?Sized>(&'a self, q: &Q)
+                            -> InternalEntry<K, V, &'a RawTable<K, V>>
         where K: Borrow<Q>, Q: Eq + Hash
     {
         let hash = self.make_hash(q);
-        match search_hashed(&self.table, hash, |k| q.eq(k.borrow())) {
-            InternalEntry::Occupied(bucket) => Some(bucket.elem),
-            _ => None,
-        }
+        search_hashed(&self.table, hash, |k| q.eq(k.borrow()))
     }
 
-    fn search_mut<'a, Q: ?Sized>(&'a mut self, q: &Q) -> Option<FullBucketMut<'a, K, V>>
+    fn search_mut<'a, Q: ?Sized>(&'a mut self, q: &Q)
+                                -> InternalEntry<K, V, &'a mut RawTable<K, V>>
         where K: Borrow<Q>, Q: Eq + Hash
     {
         let hash = self.make_hash(q);
-        match search_hashed(&mut self.table, hash, |k| q.eq(k.borrow())) {
-            InternalEntry::Occupied(bucket) => Some(bucket.elem),
-            _ => None,
-        }
+        search_hashed(&mut self.table, hash, |k| q.eq(k.borrow()))
     }
 }
 
@@ -653,7 +644,7 @@ impl<K, V, S> HashMap<K, V, S>
         // Grow the table.
         let is_inplace = self.table.grow_inplace(new_capacity);
 
-        let mut destination = if is_inplace {
+        let destination = if is_inplace {
             // Resizing in-place.
             None
         } else {
@@ -933,14 +924,13 @@ impl<K, V, S> HashMap<K, V, S>
     pub fn entry(&mut self, key: K) -> Entry<K, V> {
         // Gotta resize now.
         self.reserve(1);
-
         let hash = self.make_hash(&key);
-        match search_hashed(&mut self.table, hash, |k| *k == key) {
+        match search_hashed(&mut self.table, hash, |k| key.eq(k.borrow())) {
             InternalEntry::Occupied(state) => Occupied(state),
             InternalEntry::Vacant(bucket) => Vacant(VacantEntry {
-                elem: bucket,
-                hash: hash,
                 key: key,
+                hash: hash,
+                elem: bucket,
             }),
             InternalEntry::TableIsEmpty => unreachable!()
         }
@@ -1044,7 +1034,7 @@ impl<K, V, S> HashMap<K, V, S>
     pub fn get<Q: ?Sized>(&self, k: &Q) -> Option<&V>
         where K: Borrow<Q>, Q: Hash + Eq
     {
-        self.search(k).map(|bucket| bucket.into_refs().1)
+        self.search(k).into_option().map(|bucket| bucket.into_refs().1)
     }
 
     /// Returns true if the map contains a value for the specified key.
@@ -1067,7 +1057,7 @@ impl<K, V, S> HashMap<K, V, S>
     pub fn contains_key<Q: ?Sized>(&self, k: &Q) -> bool
         where K: Borrow<Q>, Q: Hash + Eq
     {
-        self.search(k).is_some()
+        self.search(k).into_option().is_some()
     }
 
     /// Returns a mutable reference to the value corresponding to the key.
@@ -1093,7 +1083,7 @@ impl<K, V, S> HashMap<K, V, S>
     pub fn get_mut<Q: ?Sized>(&mut self, k: &Q) -> Option<&mut V>
         where K: Borrow<Q>, Q: Hash + Eq
     {
-        self.search_mut(k).map(|bucket| bucket.into_mut_refs().1)
+        self.search_mut(k).into_option().map(|bucket| bucket.into_mut_refs().1)
     }
 
     /// Inserts a key-value pair from the map. If the key already had a value
@@ -1113,10 +1103,10 @@ impl<K, V, S> HashMap<K, V, S>
     /// assert_eq!(map[37], "c");
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
-    pub fn insert(&mut self, k: K, v: V) -> Option<V> {
-        let hash = self.make_hash(&k);
+    pub fn insert(&mut self, key: K, value: V) -> Option<V> {
         self.reserve(1);
-        self.insert_hashed_nocheck(hash, k, v)
+        let hash = self.make_hash(&key);
+        self.insert_hashed_nocheck(hash, key, value)
     }
 
     /// Removes a key from the map, returning the value at the key if the key
@@ -1144,7 +1134,7 @@ impl<K, V, S> HashMap<K, V, S>
             return None
         }
 
-        self.search_mut(k).map(|bucket| pop_internal(bucket).1)
+        self.search_mut(k).into_option().map(|bucket| pop_internal(bucket).1)
     }
 }
 
@@ -1397,6 +1387,15 @@ enum InternalEntry<K, V, M> {
     TableIsEmpty,
 }
 
+impl<K, V, M> InternalEntry<K, V, M> {
+    fn into_option(self) -> Option<FullBucket<K, V, M>> {
+        match self {
+            InternalEntry::Occupied(bucket) => Some(bucket.elem),
+            _ => None,
+        }
+    }
+}
+
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<'a, K, V> Iterator for Iter<'a, K, V> {
     type Item = (&'a K, &'a V);
@@ -1547,7 +1546,7 @@ impl<'a, K, V> OccupiedEntry<'a, K, V> {
 
 #[unstable(feature = "std_misc",
            reason = "matches collection reform v2 specification, waiting for dust to settle")]
-impl<'a, K: 'a, V: 'a, M: 'a> OccupiedEntryState<K, V, M> where RawTable<K, V>: BorrowFromMut<M> {
+impl<'a, K: 'a, V: 'a, M: 'a> OccupiedEntryState<K, V, M> where M: BorrowMut<RawTable<K, V>> {
     /// Gets a mutable reference to the value in the entry.
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn get_mut(&mut self) -> &mut V {