docs, refactored

Author: pczarn

src/libstd/collections/hash/map.rs

@@ -21,7 +21,7 @@ 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 option::Option::{self, Some, None};
@@ -392,8 +392,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 +407,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 +420,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 +435,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;
             }
         }
@@ -477,24 +476,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)
+                            -> Option<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)
+                                -> Option<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()))
     }
 }
 
@@ -772,7 +767,15 @@ impl<K, V, S> HashMap<K, V, S>
 
             // Shrink the table. Naive algorithm for resizing:
             while let Some((h, k, v)) = old_table.take_front() {
-                self.insert_hashed_nocheck(h, k, v);
+                match search_hashed(&mut self.table, hash, |key| *key == k) {
+                    InternalEntry::Vacant(entry) => {
+                        entry.insert(hash, k, v);
+                    }
+                    InternalEntry::Occupied(mut entry) => {
+                        entry.insert(v);
+                    }
+                    InternalEntry::TableIsEmpty => unreachable!()
+                }
             }
 
             debug_assert_eq!(self.table.size(), old_size);
@@ -934,8 +937,7 @@ impl<K, V, S> HashMap<K, V, S>
         // Gotta resize now.
         self.reserve(1);
 
-        let hash = self.make_hash(&key);
-        match search_hashed(&mut self.table, hash, |k| *k == key) {
+        match self.search_mut(&key) {
             InternalEntry::Occupied(state) => Occupied(state),
             InternalEntry::Vacant(bucket) => Vacant(VacantEntry {
                 elem: bucket,
@@ -1044,7 +1046,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 +1069,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 +1095,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 +1115,19 @@ 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)
+
+        match self.search_mut(&key) {
+            InternalEntry::Vacant(entry) => {
+                entry.insert(hash, key, value);
+                return None;
+            }
+            InternalEntry::Occupied(mut entry) => {
+                return Some(entry.insert(value));
+            }
+            InternalEntry::TableIsEmpty => unreachable!()
+        }
     }
 
     /// Removes a key from the map, returning the value at the key if the key
@@ -1144,7 +1155,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 +1408,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);

src/libstd/collections/hash/table.rs

@@ -503,6 +503,7 @@ impl<K, V> RawTable<K, V> {
         }
     }
 
+    /// Grows a non-empty table in-place.
     pub fn grow_inplace(&mut self, capacity: uint) -> bool {
         assert!(capacity.is_power_of_two());
         assert!(capacity >= self.capacity);
@@ -672,6 +673,7 @@ impl<K, V> Drop for RawTable<K, V> {
     }
 }
 
+/// A partial table provides safe and cheap draining and incremental construction.
 pub struct PartialRawTable<K, V> {
     table: RawTable<K, V>,
     front: RawBucket<K, V>,
@@ -681,6 +683,7 @@ pub struct PartialRawTable<K, V> {
 }
 
 impl<K, V> PartialRawTable<K, V> {
+    /// Turn a table into a partial table. All buckets are already initialized.
     pub fn new(table: RawTable<K, V>) -> PartialRawTable<K, V> {
         unsafe {
             PartialRawTable {
@@ -693,6 +696,7 @@ impl<K, V> PartialRawTable<K, V> {
         }
     }
 
+    /// Initialize a bucket. Has no effect if there are no uninitialized buckets at the back.
     pub fn push_back(&mut self, bucket: Option<(SafeHash, K, V)>) {
         unsafe {
             if self.back_num != 0 {
@@ -709,6 +713,7 @@ impl<K, V> PartialRawTable<K, V> {
         }
     }
 
+    /// Takes out an initialized bucket. Returns None if all buckets are uninitialized.
     pub fn take_front(&mut self) -> Option<(SafeHash, K, V)> {
         unsafe {
             while self.front.hash != self.back.hash {
@@ -725,6 +730,7 @@ impl<K, V> PartialRawTable<K, V> {
         None
     }
 
+    /// Unwrap the table by zeroing uninitialized ranges.
     pub fn unwrap(self) -> RawTable<K, V> {
         unsafe {
             ptr::write_bytes(self.table.first_bucket_raw().hash, self.front_num);
@@ -740,6 +746,7 @@ impl<K, V> PartialRawTable<K, V> {
     }
 }
 
+/// Drops all initialized buckets in the partial table.
 #[unsafe_destructor]
 impl<K, V> Drop for PartialRawTable<K, V> {
     fn drop(&mut self) {