Add union method to Array

I introduce a `union` 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. It is plan to introduce a `union!` method as well.

Tests and documentation are included.

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

[Fix GH-1747] [Feature #14097]

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

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

NEWS

@@ -39,6 +39,11 @@ sufficient information, see the ChangeLog file or Redmine
 
 * `Array`
 
+    * New methods:
+
+        * Added `Array#union` instance method.
+          [Feature #14097]
+
     * Aliased methods:
 
         * `Array#filter` is a new alias for `Array#select`.

array.c

@@ -4320,6 +4320,75 @@ rb_ary_or(VALUE ary1, VALUE ary2)
     return ary3;
 }
 
+/*
+ *  call-seq:
+ *     ary.union(other_ary1, other_ary2,...)   -> ary
+ *
+ *  Set Union --- Returns a new array by joining +other_ary+s with +self+,
+ *  excluding any duplicates and preserving the order from the given arrays.
+ *
+ *  It compares elements using their #hash and #eql? methods for efficiency.
+ *
+ *     [ "a", "b", "c" ].union( [ "c", "d", "a" ] )    #=> [ "a", "b", "c", "d" ]
+ *     [ "a" ].union( [ ["e", "b"], ["a", "c", "b"] ] )    #=> [ "a", "e", "b", "c" ]
+ *     [ "a" ].union #=> [ "a" ]
+ *
+ *  See also Array#|.
+ */
+
+static VALUE
+rb_ary_union_multi(int argc, VALUE *argv, VALUE ary)
+{
+    int i;
+    long j;
+    long sum;
+    VALUE hash, ary_union;
+
+    sum = RARRAY_LEN(ary);
+    for (i = 0; i < argc; i++){
+        argv[i] = to_ary(argv[i]);
+        sum += RARRAY_LEN(argv[i]);
+    }
+
+    if (sum <= SMALL_ARRAY_LEN) {
+        ary_union = rb_ary_new();
+
+        for (j = 0; j < RARRAY_LEN(ary); j++) {
+            VALUE elt = rb_ary_elt(ary, j);
+            if (rb_ary_includes_by_eql(ary_union, elt)) continue;
+            rb_ary_push(ary_union, elt);
+        }
+
+        for (i = 0; i < argc; i++) {
+            VALUE argv_i = argv[i];
+
+            for (j = 0; j < RARRAY_LEN(argv_i); j++) {
+                VALUE elt = rb_ary_elt(argv_i, j);
+                if (rb_ary_includes_by_eql(ary_union, elt)) continue;
+                rb_ary_push(ary_union, elt);
+            }
+        }
+        return ary_union;
+    }
+
+    hash = ary_make_hash(ary);
+
+    for (i = 0; i < argc; i++) {
+        VALUE argv_i = argv[i];
+
+        for (j = 0; j < RARRAY_LEN(argv_i); j++) {
+            VALUE elt = RARRAY_AREF(argv_i, j);
+            if (!st_update(RHASH_TBL_RAW(hash), (st_data_t)elt, ary_hash_orset, (st_data_t)elt)) {
+                RB_OBJ_WRITTEN(hash, Qundef, elt);
+            }
+        }
+    }
+
+    ary_union = rb_hash_values(hash);
+    ary_recycle_hash(hash);
+    return ary_union;
+}
+
 /*
  *  call-seq:
  *     ary.max                     -> obj
@@ -6296,6 +6365,7 @@ Init_Array(void)
     rb_define_method(rb_cArray, "first", rb_ary_first, -1);
     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, "<<", rb_ary_push, 1);
     rb_define_method(rb_cArray, "push", rb_ary_push_m, -1);
     rb_define_alias(rb_cArray,  "append", "push");

test/ruby/test_array.rb

@@ -1884,6 +1884,44 @@ class TestArray < Test::Unit::TestCase
     assert_equal((1..128).to_a, b)
   end
 
+  def test_union
+    assert_equal(@cls[],  @cls[].union(@cls[]))
+    assert_equal(@cls[1], @cls[1].union(@cls[]))
+    assert_equal(@cls[1], @cls[].union(@cls[1]))
+    assert_equal(@cls[1], @cls[].union(@cls[], @cls[1]))
+    assert_equal(@cls[1], @cls[1].union(@cls[1]))
+    assert_equal(@cls[1], @cls[1].union(@cls[1], @cls[1], @cls[1]))
+
+    assert_equal(@cls[1,2], @cls[1].union(@cls[2]))
+    assert_equal(@cls[1,2], @cls[1, 1].union(@cls[2, 2]))
+    assert_equal(@cls[1,2], @cls[1, 2].union(@cls[1, 2]))
+    assert_equal(@cls[1,2], @cls[1, 1].union(@cls[1, 1], @cls[1, 2], @cls[2, 1], @cls[2, 2, 2]))
+
+    a = %w(a b c)
+    b = %w(a b c d e)
+    c = a.union(b)
+    assert_equal(c, b)
+    assert_not_same(c, b)
+    assert_equal(%w(a b c), a)
+    assert_equal(%w(a b c d e), b)
+    assert(a.none?(&:frozen?))
+    assert(b.none?(&:frozen?))
+    assert(c.none?(&:frozen?))
+  end
+
+  def test_union_big_array
+    assert_equal(@cls[1,2], (@cls[1]*64).union(@cls[2]*64))
+    assert_equal(@cls[1,2,3], (@cls[1, 2]*64).union(@cls[1, 2]*64, @cls[3]*60))
+
+    a = (1..64).to_a
+    b = (1..128).to_a
+    c = a | b
+    assert_equal(c, b)
+    assert_not_same(c, b)
+    assert_equal((1..64).to_a, a)
+    assert_equal((1..128).to_a, b)
+  end
+
   def test_combination
     a = @cls[]
     assert_equal(1, a.combination(0).size)