Auto merge of #201 - cuviper:safe-drain, r=Amanieu

Make `RawTable::drain` safe

The documentation indicated a safety question of the lifetime, but there
is a lifetime parameter on `RawDrain` to ensure that. Also, the similar
`par_drain` is already a safe method.

I also adjusted the safety comments on `drain_iter_from`/`into_iter_from`.
The safety contract for these methods is really about the validity of
the given `RawIter` for this `RawTable`. Once that's established, the
lifetime is no longer a concern, since `RawDrain<'_, T>` has a borrow
and `RawIntoIter<T>` is a consuming owner.

src/map.rs

@@ -548,11 +548,8 @@ impl<K, V, S> HashMap<K, V, S> {
     /// ```
     #[cfg_attr(feature = "inline-more", inline)]
     pub fn drain(&mut self) -> Drain<'_, K, V> {
-        // Here we tie the lifetime of self to the iter.
-        unsafe {
-            Drain {
-                inner: self.table.drain(),
-            }
+        Drain {
+            inner: self.table.drain(),
         }
     }
 

src/raw/mod.rs

@@ -1062,25 +1062,21 @@ impl<T> RawTable<T> {
 
     /// Returns an iterator which removes all elements from the table without
     /// freeing the memory.
-    ///
-    /// It is up to the caller to ensure that the `RawTable` outlives the `RawDrain`.
-    /// Because we cannot make the `next` method unsafe on the `RawDrain`,
-    /// we have to make the `drain` method unsafe.
     #[cfg_attr(feature = "inline-more", inline)]
-    pub unsafe fn drain(&mut self) -> RawDrain<'_, T> {
-        let iter = self.iter();
-        self.drain_iter_from(iter)
+    pub fn drain(&mut self) -> RawDrain<'_, T> {
+        unsafe {
+            let iter = self.iter();
+            self.drain_iter_from(iter)
+        }
     }
 
     /// Returns an iterator which removes all elements from the table without
     /// freeing the memory.
     ///
-    /// It is up to the caller to ensure that the `RawTable` outlives the `RawDrain`.
-    /// Because we cannot make the `next` method unsafe on the `RawDrain`,
-    /// we have to make the `drain` method unsafe.
-    ///
     /// Iteration starts at the provided iterator's current location.
-    /// You must ensure that the iterator covers all items that remain in the table.
+    ///
+    /// It is up to the caller to ensure that the iterator is valid for this
+    /// `RawTable` and covers all items that remain in the table.
     #[cfg_attr(feature = "inline-more", inline)]
     pub unsafe fn drain_iter_from(&mut self, iter: RawIter<T>) -> RawDrain<'_, T> {
         debug_assert_eq!(iter.len(), self.len());
@@ -1094,12 +1090,10 @@ impl<T> RawTable<T> {
 
     /// Returns an iterator which consumes all elements from the table.
     ///
-    /// It is up to the caller to ensure that the `RawTable` outlives the `RawIntoIter`.
-    /// Because we cannot make the `next` method unsafe on the `RawIntoIter`,
-    /// we have to make the `into_iter_from` method unsafe.
-    ///
     /// Iteration starts at the provided iterator's current location.
-    /// You must ensure that the iterator covers all items that remain in the table.
+    ///
+    /// It is up to the caller to ensure that the iterator is valid for this
+    /// `RawTable` and covers all items that remain in the table.
     pub unsafe fn into_iter_from(self, iter: RawIter<T>) -> RawIntoIter<T> {
         debug_assert_eq!(iter.len(), self.len());