Add Array#subtract

Author: TylerRick

lib/core/facets/array/subtract.rb

@@ -0,0 +1,37 @@
+class Array
+  # Returns a new array that is a copy of the original array, removing the _first_ item in self that
+  # also appears in other. The order is preserved from the original array.
+  #
+  # For each element of `other`, deletes the _first_ item from self that is equal to element (using
+  # `delete_at`, not `delete`).
+  #
+  # This is similar to `Array#-` and `Array#difference`, except that instead of removing _all_
+  # matches, it only removes as many occurrences as you actually _ask_ it to subtract:
+  #
+  #    > [1, 1, 2].subtract [1]
+  #   => [1, 2]
+  #
+  #    > [1, 1, 2].subtract [1, 1]
+  #   => [2]
+  #
+  #    > [1, 1, 2] - [1]
+  #   => [2]
+  #
+  #    > [1, 1, 2].difference [1]
+  #   => [2]
+  #
+  def subtract(other)
+    dup.subtract!(other)
+  end
+
+  # Removes the _first_ item in self that also appears in other.
+  #
+  # This is the in-place version of subtract.
+  #
+  def subtract!(other)
+    other.each do |el|
+      delete_at(index(el))
+    end
+    self
+  end
+end

test/core/array/test_subtract.rb

@@ -0,0 +1,29 @@
+covers 'facets/array/subtract'
+
+test_case Array do
+  method :subtract do
+    test do
+      a                         = [1,1,2,3]
+      a.subtract(  [1]).assert == [  1,2,3]
+      a.difference([1]).assert == [    2,3]
+      (a -         [1]).assert == [    2,3]
+      a.assert                 == [1,1,2,3]
+    end
+
+    test do
+      a                          = [1,1,2,3]
+      a.subtract([1, 1]).assert == [    2,3]
+      (a -          [1]).assert == [    2,3]
+      a.assert                  == [1,1,2,3]
+    end
+  end
+
+  method :subtract! do
+    test do
+      a                        = [1,1,2,3]
+      a.subtract!([1]).assert == [  1,2,3]
+      a.assert                == [  1,2,3]
+    end
+  end
+end
+