Add relative_complement to sets/maps

Author: AljoschaMeyer

src/hash/map.rs

@@ -1131,6 +1131,32 @@ where
         out.union(self)
     }
 
+    /// Construct the relative complement between two maps by discarding keys
+    /// which occur in `other`.
+    ///
+    /// Time: O(m log n) where m is the size of the other map
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # #[macro_use] extern crate im;
+    /// # use im::ordmap::OrdMap;
+    /// # fn main() {
+    /// let map1 = ordmap!{1 => 1, 3 => 4};
+    /// let map2 = ordmap!{2 => 2, 3 => 5};
+    /// let expected = ordmap!{1 => 1, 2 => 2};
+    /// assert_eq!(expected, map1.relative_complement(map2));
+    /// # }
+    /// ```
+    #[inline]
+    #[must_use]
+    pub fn relative_complement(mut self, other: Self) -> Self {
+        for (key, _) in other {
+            let _ = self.remove(&key);
+        }
+        self
+    }
+
     /// Construct the intersection of two maps, keeping the values
     /// from the current map.
     ///

src/hash/set.rs

@@ -537,6 +537,31 @@ where
         self
     }
 
+    /// Construct the relative complement between two sets, that is the set
+    /// of values in `self` that do not occur in `other`.
+    ///
+    /// Time: O(m log n) where m is the size of the other set
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # #[macro_use] extern crate im;
+    /// # use im::ordset::OrdSet;
+    /// # fn main() {
+    /// let set1 = ordset!{1, 2};
+    /// let set2 = ordset!{2, 3};
+    /// let expected = ordset!{1};
+    /// assert_eq!(expected, set1.relative_complement(set2));
+    /// # }
+    /// ```
+    #[must_use]
+    pub fn relative_complement(mut self, other: Self) -> Self {
+        for value in other {
+            let _ = self.remove(&value);
+        }
+        self
+    }
+
     /// Construct the intersection of two sets.
     ///
     /// Time: O(n log n)

src/ord/map.rs

@@ -1095,6 +1095,32 @@ where
         out.union(self)
     }
 
+    /// Construct the relative complement between two maps by discarding keys
+    /// which occur in `other`.
+    ///
+    /// Time: O(m log n) where m is the size of the other map
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # #[macro_use] extern crate im;
+    /// # use im::ordmap::OrdMap;
+    /// # fn main() {
+    /// let map1 = ordmap!{1 => 1, 3 => 4};
+    /// let map2 = ordmap!{2 => 2, 3 => 5};
+    /// let expected = ordmap!{1 => 1, 2 => 2};
+    /// assert_eq!(expected, map1.relative_complement(map2));
+    /// # }
+    /// ```
+    #[inline]
+    #[must_use]
+    pub fn relative_complement(mut self, other: Self) -> Self {
+        for (key, _) in other {
+            let _ = self.remove(&key);
+        }
+        self
+    }
+
     /// Construct the intersection of two maps, keeping the values
     /// from the current map.
     ///

src/ord/set.rs

@@ -637,6 +637,31 @@ where
         self
     }
 
+    /// Construct the relative complement between two sets, that is the set
+    /// of values in `self` that do not occur in `other`.
+    ///
+    /// Time: O(m log n) where m is the size of the other set
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # #[macro_use] extern crate im;
+    /// # use im::ordset::OrdSet;
+    /// # fn main() {
+    /// let set1 = ordset!{1, 2};
+    /// let set2 = ordset!{2, 3};
+    /// let expected = ordset!{1};
+    /// assert_eq!(expected, set1.relative_complement(set2));
+    /// # }
+    /// ```
+    #[must_use]
+    pub fn relative_complement(mut self, other: Self) -> Self {
+        for value in other {
+            let _ = self.remove(&value);
+        }
+        self
+    }
+
     /// Construct the intersection of two sets.
     ///
     /// Time: O(n log n)