Merge pull request #337 from cuviper/append

Add `append` methods

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "indexmap"
 edition = "2021"
-version = "2.3.0"
+version = "2.4.0"
 documentation = "https://docs.rs/indexmap/"
 repository = "https://github.com/indexmap-rs/indexmap"
 license = "Apache-2.0 OR MIT"

README.md

@@ -14,6 +14,8 @@ allows lookup of entries by either hash table key or numerical index.
 
 Note: this crate was originally released under the name `ordermap`,
 but it was renamed to `indexmap` to better reflect its features.
+The [`ordermap`](https://crates.io/crates/ordermap) crate now exists
+as a wrapper over `indexmap` with stronger ordering properties.
 
 # Background
 

RELEASES.md

@@ -1,5 +1,10 @@
 # Releases
 
+## 2.4.0
+
+- Added methods `IndexMap::append` and `IndexSet::append`, moving all items from
+  one map or set into another, and leaving the original capacity for reuse.
+
 ## 2.3.0
 
 - Added trait `MutableEntryKey` for opt-in mutable access to map entry keys.

src/map.rs

@@ -520,6 +520,35 @@ where
     {
         Splice::new(self, range, replace_with.into_iter())
     }
+
+    /// Moves all key-value pairs from `other` into `self`, leaving `other` empty.
+    ///
+    /// This is equivalent to calling [`insert`][Self::insert] for each
+    /// key-value pair from `other` in order, which means that for keys that
+    /// already exist in `self`, their value is updated in the current position.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use indexmap::IndexMap;
+    ///
+    /// // Note: Key (3) is present in both maps.
+    /// let mut a = IndexMap::from([(3, "c"), (2, "b"), (1, "a")]);
+    /// let mut b = IndexMap::from([(3, "d"), (4, "e"), (5, "f")]);
+    /// let old_capacity = b.capacity();
+    ///
+    /// a.append(&mut b);
+    ///
+    /// assert_eq!(a.len(), 5);
+    /// assert_eq!(b.len(), 0);
+    /// assert_eq!(b.capacity(), old_capacity);
+    ///
+    /// assert!(a.keys().eq(&[3, 2, 1, 4, 5]));
+    /// assert_eq!(a[&3], "d"); // "c" was overwritten.
+    /// ```
+    pub fn append<S2>(&mut self, other: &mut IndexMap<K, V, S2>) {
+        self.extend(other.drain(..));
+    }
 }
 
 impl<K, V, S> IndexMap<K, V, S>

src/set.rs

@@ -501,6 +501,36 @@ where
     {
         Splice::new(self, range, replace_with.into_iter())
     }
+
+    /// Moves all values from `other` into `self`, leaving `other` empty.
+    ///
+    /// This is equivalent to calling [`insert`][Self::insert] for each value
+    /// from `other` in order, which means that values that already exist
+    /// in `self` are unchanged in their current position.
+    ///
+    /// See also [`union`][Self::union] to iterate the combined values by
+    /// reference, without modifying `self` or `other`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use indexmap::IndexSet;
+    ///
+    /// let mut a = IndexSet::from([3, 2, 1]);
+    /// let mut b = IndexSet::from([3, 4, 5]);
+    /// let old_capacity = b.capacity();
+    ///
+    /// a.append(&mut b);
+    ///
+    /// assert_eq!(a.len(), 5);
+    /// assert_eq!(b.len(), 0);
+    /// assert_eq!(b.capacity(), old_capacity);
+    ///
+    /// assert!(a.iter().eq(&[3, 2, 1, 4, 5]));
+    /// ```
+    pub fn append<S2>(&mut self, other: &mut IndexSet<T, S2>) {
+        self.map.append(&mut other.map);
+    }
 }
 
 impl<T, S> IndexSet<T, S>