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

1 files changed, 70 insertions, 0 deletions

diff --git a/array.c b/array.c
index 3c36bb66e6..ae3cc49e26 100644
--- a/array.c
+++ b/array.c
@@ -4322,6 +4322,75 @@ rb_ary_or(VALUE ary1, VALUE ary2)
 
 /*
  *  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
  *     ary.max {|a, b| block}      -> obj
  *     ary.max(n)                  -> array
@@ -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");