Add difference method to Array

I introduce a `difference` method equivalent to the `-` operator, but
which accept more than array as argument. This improved readability, and
it is also coherent with the `+` operator, which has a similar `concat`
method. The method doesn't modify the original object and return a new
object instead. I plan to introduce a `difference!` method as well.

Tests and documentation are included.

It solves partially https://bugs.ruby-lang.org/issues/14097

From: Ana María Martínez Gómez <ammartinez@suse.de>

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@64921 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 60 insertions, 0 deletions

diff --git a/array.c b/array.c
index 7aeec160f6..8a1eed762f 100644
--- a/array.c
+++ b/array.c
@@ -4190,6 +4190,8 @@ ary_recycle_hash(VALUE hash)
  *     [ 1, 1, 2, 2, 3, 3, 4, 5 ] - [ 1, 2, 4 ]  #=>  [ 3, 3, 5 ]
  *
  *  If you need set-like behavior, see the library class Set.
+ *
+ *  See Array#difference.
  */
 
 static VALUE
@@ -4222,6 +4224,63 @@ rb_ary_diff(VALUE ary1, VALUE ary2)
 
 /*
  *  call-seq:
+ *     ary.difference(other_ary1, other_ary2,...)   -> ary
+ *
+ *  Array Difference
+ *
+ *  Returns a new array that is a copy of +self+, removing any items
+ *  that also appear in any of the +other_ary+s. The order of +self+ is
+ *  preserved.
+ *
+ *  It compares elements using their #hash and #eql? methods for efficiency.
+ *
+ *     [ 1, 1, 2, 2, 3, 3, 4, 5 ].difference([ 1, 2, 4 ])       #=>  [ 3, 3, 5 ]
+ *     [ 1, 'c', :s, 'yep' ].difference([ 1 ], [ 'a', 'c' ])    #=> [:s, "yep"]
+ *
+ *  If you need set-like behavior, see the library class Set.
+ *
+ *  See Array#-.
+ */
+
+static VALUE
+rb_ary_difference_multi(int argc, VALUE *argv, VALUE ary)
+{
+    VALUE ary_diff;
+    long i, length;
+    volatile VALUE t0;
+    bool *is_hash = ALLOCV_N(bool, t0, argc);
+    ary_diff = rb_ary_new();
+    length = RARRAY_LEN(ary);
+
+    for (i = 0; i < argc; i++) {
+	argv[i] = to_ary(argv[i]);
+	is_hash[i] = (length > SMALL_ARRAY_LEN && RARRAY_LEN(argv[i]) > SMALL_ARRAY_LEN);
+	if (is_hash[i]) argv[i] = ary_make_hash(argv[i]);
+    }
+
+    for (i = 0; i < RARRAY_LEN(ary); i++) {
+	int j;
+	VALUE elt = rb_ary_elt(ary, i);
+	for (j = 0; j < argc; j++){
+	    if (is_hash[j]) {
+		if (st_lookup(rb_hash_tbl_raw(argv[j]), RARRAY_AREF(ary, i), 0))
+		    break;
+            }
+            else {
+		if (rb_ary_includes_by_eql(argv[j], elt)) break;
+	    }
+        }
+        if (j == argc) rb_ary_push(ary_diff, elt);
+    }
+
+    ALLOCV_END(t0);
+
+    return ary_diff;
+}
+
+
+/*
+ *  call-seq:
  *     ary & other_ary      -> new_ary
  *
  *  Set Intersection --- Returns a new array containing unique elements common to the
@@ -6363,6 +6422,7 @@ Init_Array(void)
     rb_define_method(rb_cArray, "last", rb_ary_last, -1);
     rb_define_method(rb_cArray, "concat", rb_ary_concat_multi, -1);
     rb_define_method(rb_cArray, "union", rb_ary_union_multi, -1);
+    rb_define_method(rb_cArray, "difference", rb_ary_difference_multi, -1);
     rb_define_method(rb_cArray, "<<", rb_ary_push, 1);
     rb_define_method(rb_cArray, "push", rb_ary_push_m, -1);
     rb_define_alias(rb_cArray,  "append", "push");