Add subtract to IterableExtensions

CHANGELOG.md

@@ -1,5 +1,6 @@
 ## 1.19.0-wip
 
+- Adds `subtract` to `IterableExtension`.
 - Adds `shuffled` to `IterableExtension`.
 - Shuffle `IterableExtension.sample` results.
 

lib/src/iterable_extensions.dart

@@ -601,6 +601,31 @@ extension IterableExtension<T> on Iterable<T> {
       yield slice;
     }
   }
+
+  /// Returns an iterable of the elements in this iterable that are not present
+  /// in [other].
+  ///
+  /// It's aware about occurrence count and excludes elements only the number of
+  /// times they occurred in [other] but it's indifferent about order of items
+  /// in [other].
+  ///
+  /// It assumes the iterable items have consistent `==` and `hashCode`.
+  Iterable<T> subtract(Iterable<T> other) sync* {
+    var elementsCount = <T, int>{};
+    for (var element in other) {
+      elementsCount[element] = (elementsCount[element] ?? 0) + 1;
+    }
+    for (var element in this) {
+      var count = elementsCount[element];
+      if (count == null) {
+        yield element;
+      } else if (count == 1) {
+        elementsCount.remove(element);
+      } else {
+        elementsCount[element] = count - 1;
+      }
+    }
+  }
 }
 
 /// Extensions that apply to iterables with a nullable element type.

test/extensions_test.dart

@@ -1262,6 +1262,23 @@ void main() {
         expect(l3.toList(), [4, 5]);
       });
     });
+    group('.subtract', () {
+      test('empty', () {
+        expect(iterable(<int>[]).subtract([]), []);
+      });
+      test('returns the same list when it shares nothing with the other', () {
+        expect(iterable([1, 2, 3, 4]).subtract([5]), [1, 2, 3, 4]);
+      });
+      test('removes two element', () {
+        expect(iterable([1, 2, 3, 4]).subtract([2, 3]), [1, 4]);
+      });
+      test('removes only one of the occurrence', () {
+        expect(iterable([1, 2, 2, 3]).subtract([2]), [1, 2, 3]);
+      });
+      test('removes only two of the occurrences', () {
+        expect(iterable([1, 2, 2, 3]).subtract([2, 0, 2]), [1, 3]);
+      });
+    });
   });
 
   group('Comparator', () {