docs, refactored

pczarn · pczarn · commit 745229be7c5d · 2015-02-21T23:45:41.000+01:00
diff --git a/src/libstd/collections/hash/map.rs b/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};
@@ -393,8 +393,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 = {
@@ -408,9 +408,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();
@@ -419,7 +421,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;
@@ -434,9 +436,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;
             }
         }
@@ -478,24 +477,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()))
     }
 }
 
@@ -773,7 +768,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);
@@ -935,8 +938,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,
@@ -1045,7 +1047,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.
@@ -1068,7 +1070,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.
@@ -1094,7 +1096,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
@@ -1114,10 +1116,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
@@ -1145,7 +1156,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)
     }
 }
 
@@ -1398,6 +1409,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);
diff --git a/src/libstd/collections/hash/table.rs b/src/libstd/collections/hash/table.rs
@@ -522,6 +522,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);
@@ -691,6 +692,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>,
@@ -700,6 +702,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 {
@@ -712,6 +715,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 {
@@ -728,6 +732,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 {
@@ -744,6 +749,7 @@ impl<K, V> PartialRawTable<K, V> {
         None
     }
 
+    /// Unwrap the table by zeroing uninitialized ranges.
     pub fn unwrap(self) -> RawTable<K, V> {
         unsafe {
             zero_memory(self.table.first_bucket_raw().hash, self.front_num);
@@ -759,6 +765,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) {

Original file line number	Diff line number	Diff line change
`@@ -522,6 +522,7 @@ impl<K, V> RawTable<K, V> {`
`522`	`522`	`}`
`523`	`523`	`}`
`524`	`524`
	`525`	`+ /// Grows a non-empty table in-place.`
`525`	`526`	`pub fn grow_inplace(&mut self, capacity: uint) -> bool {`
`526`	`527`	`assert!(capacity.is_power_of_two());`
`527`	`528`	`assert!(capacity >= self.capacity);`
`@@ -691,6 +692,7 @@ impl<K, V> Drop for RawTable<K, V> {`
`691`	`692`	`}`
`692`	`693`	`}`
`693`	`694`
	`695`	`+/// A partial table provides safe and cheap draining and incremental construction.`
`694`	`696`	`pub struct PartialRawTable<K, V> {`
`695`	`697`	`table: RawTable<K, V>,`
`696`	`698`	`front: RawBucket<K, V>,`
`@@ -700,6 +702,7 @@ pub struct PartialRawTable<K, V> {`
`700`	`702`	`}`
`701`	`703`
`702`	`704`	`impl<K, V> PartialRawTable<K, V> {`
	`705`	`+ /// Turn a table into a partial table. All buckets are already initialized.`
`703`	`706`	`pub fn new(table: RawTable<K, V>) -> PartialRawTable<K, V> {`
`704`	`707`	`unsafe {`
`705`	`708`	`PartialRawTable {`
`@@ -712,6 +715,7 @@ impl<K, V> PartialRawTable<K, V> {`
`712`	`715`	`}`
`713`	`716`	`}`
`714`	`717`
	`718`	`+ /// Initialize a bucket. Has no effect if there are no uninitialized buckets at the back.`
`715`	`719`	`pub fn push_back(&mut self, bucket: Option<(SafeHash, K, V)>) {`
`716`	`720`	`unsafe {`
`717`	`721`	`if self.back_num != 0 {`
`@@ -728,6 +732,7 @@ impl<K, V> PartialRawTable<K, V> {`
`728`	`732`	`}`
`729`	`733`	`}`
`730`	`734`
	`735`	`+ /// Takes out an initialized bucket. Returns None if all buckets are uninitialized.`
`731`	`736`	`pub fn take_front(&mut self) -> Option<(SafeHash, K, V)> {`
`732`	`737`	`unsafe {`
`733`	`738`	`while self.front.hash != self.back.hash {`
`@@ -744,6 +749,7 @@ impl<K, V> PartialRawTable<K, V> {`
`744`	`749`	`None`
`745`	`750`	`}`
`746`	`751`
	`752`	`+ /// Unwrap the table by zeroing uninitialized ranges.`
`747`	`753`	`pub fn unwrap(self) -> RawTable<K, V> {`
`748`	`754`	`unsafe {`
`749`	`755`	`zero_memory(self.table.first_bucket_raw().hash, self.front_num);`
`@@ -759,6 +765,7 @@ impl<K, V> PartialRawTable<K, V> {`
`759`	`765`	`}`
`760`	`766`	`}`
`761`	`767`
	`768`	`+/// Drops all initialized buckets in the partial table.`
`762`	`769`	`#[unsafe_destructor]`
`763`	`770`	`impl<K, V> Drop for PartialRawTable<K, V> {`
`764`	`771`	`fn drop(&mut self) {`