Provide an iterator over OccupiedEntry

Allows iterating `LinkedHashMap` entries with the option to remove visited
entries during iteration.

Author: carllerche

src/lib.rs

@@ -230,6 +230,43 @@ impl<K: Hash + Eq, V, S: BuildHasher> LinkedHashMap<K, V, S> {
         })
     }
 
+    /// Returns an iterator visiting all entries in order insertion.
+    /// Iterator element type is `OccupiedEntry<K, V, S>`. Allows for removal
+    /// as well as replacing the entry.
+    ///
+    /// # Examples
+    /// ```
+    /// use linked_hash_map::LinkedHashMap;
+    ///
+    /// let mut map = LinkedHashMap::new();
+    /// map.insert("a", 10);
+    /// map.insert("c", 30);
+    /// map.insert("b", 20);
+    ///
+    /// {
+    ///     let mut iter = map.entries();
+    ///     let mut entry = iter.next().unwrap();
+    ///     assert_eq!(&"a", entry.key());
+    ///     *entry.get_mut() = 17;
+    /// }
+    ///
+    /// assert_eq!(&17, map.get(&"a").unwrap());
+    /// ```
+    pub fn entries(&mut self) -> Entries<K, V, S> {
+        let head = if ! self.head.is_null() {
+            unsafe { (*self.head).prev }
+        } else {
+            ptr::null_mut()
+        };
+        Entries {
+            map: self,
+            head: head,
+            tail: self.head,
+            remaining: self.len(),
+            marker: marker::PhantomData,
+        }
+    }
+
     /// Inserts a key-value pair into the map. If the key already existed, the old value is
     /// returned.
     ///
@@ -785,14 +822,28 @@ pub struct IterMut<'a, K: 'a, V: 'a> {
     marker: marker::PhantomData<(&'a K, &'a mut V)>,
 }
 
+/// An insertion-order iterator over a `LinkedHashMap`'s entries represented as
+/// an `OccupiedEntry`.
+pub struct Entries<'a, K: 'a, V: 'a, S: 'a> {
+    map: *mut LinkedHashMap<K, V, S>,
+    head: *mut LinkedHashMapEntry<K, V>,
+    tail: *mut LinkedHashMapEntry<K, V>,
+    remaining: usize,
+    marker: marker::PhantomData<(&'a K, &'a mut V, &'a S)>,
+}
+
 unsafe impl<'a, K, V> Send for Iter<'a, K, V> where K: Send, V: Send {}
 
 unsafe impl<'a, K, V> Send for IterMut<'a, K, V> where K: Send, V: Send {}
 
+unsafe impl<'a, K, V, S> Send for Entries<'a, K, V, S> where K: Send, V: Send, S: Send {}
+
 unsafe impl<'a, K, V> Sync for Iter<'a, K, V> where K: Sync, V: Sync {}
 
 unsafe impl<'a, K, V> Sync for IterMut<'a, K, V> where K: Sync, V: Sync {}
 
+unsafe impl<'a, K, V, S> Sync for Entries<'a, K, V, S> where K: Sync, V: Sync, S: Sync {}
+
 impl<'a, K, V> Clone for Iter<'a, K, V> {
     fn clone(&self) -> Self { Iter { ..*self } }
 }
@@ -839,6 +890,32 @@ impl<'a, K, V> Iterator for IterMut<'a, K, V> {
     }
 }
 
+impl<'a, K, V, S: HashState> Iterator for Entries<'a, K, V, S> {
+    type Item = OccupiedEntry<'a, K, V, S>;
+
+    fn next(&mut self) -> Option<OccupiedEntry<'a, K, V, S>> {
+        if self.head == self.tail {
+            None
+        } else {
+            self.remaining -= 1;
+            unsafe {
+                let r = Some(OccupiedEntry {
+                    map: self.map,
+                    entry: self.head,
+                    marker: marker::PhantomData,
+                });
+
+                self.head = (*self.head).prev;
+                r
+            }
+        }
+    }
+
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        (self.remaining, Some(self.remaining))
+    }
+}
+
 impl<'a, K, V> DoubleEndedIterator for Iter<'a, K, V> {
     fn next_back(&mut self) -> Option<(&'a K, &'a V)> {
         if self.head == self.tail {

tests/test.rs

@@ -67,6 +67,21 @@ fn test_entry_insert_vacant() {
     }
 }
 
+#[test]
+fn test_entries_replacing() {
+    let mut map = LinkedHashMap::new();
+    map.insert("a", 10);
+
+    {
+        let mut iter = map.entries();
+        let mut entry = iter.next().unwrap();
+        assert_eq!(entry.insert(20), 10);
+        assert!(iter.next().is_none());
+    }
+
+    assert_eq!(map["a"], 20);
+}
+
 #[test]
 fn test_debug() {
     let mut map = LinkedHashMap::new();