Merge pull request #2254 from pocke/Array#&

Add Array#intersection since Ruby 2.7

refm/api/src/_builtin/Array

@@ -433,7 +433,11 @@ self 中で重複していて、other_arrays中に存在していなかった要
 
   [1, 1, 2, 3] & [3, 1, 4] #=> [1, 3]
 
+#@since 2.7.0
+@see [[m:Array#|]], [[m:Array#intersection]]
+#@else
 @see [[m:Array#|]]
+#@end
 
 --- |(other)    -> Array
 
@@ -1119,6 +1123,30 @@ self 以下のネストしたオブジェクトを dig メソッドで再帰的
     ary.insert(-2, "X")
     p ary                  # => [1, 2, "a", "b", "X", 3]
 
+#@since 2.7.0
+--- intersection(*other_arrays) -> Array
+
+自身と引数に渡された配列の共通要素を新しい配列として返します。
+要素が重複する場合は、そのうちの1つのみを返します。
+要素の順序は自身の順序を維持します。
+
+@param other_arrays 自身と共通要素を取りたい配列を指定します。
+                    配列以外のオブジェクトを指定した場合は to_ary
+                    メソッドによる暗黙の型変換を試みます。
+
+@raise TypeError 引数に配列以外の(暗黙の型変換が行えない)オブジェクトを
+                 指定した場合に発生します。
+
+intersectionは[[m:Object#hash]]と[[m:Object#eql?]]を使って比較を行います。
+
+#@samplecode
+[1, 1, 3, 5].intersection([3, 2, 1])                  # => [1, 3]
+["a", "b", "z"].intersection(["a", "b", "c"], ["b"])  # => ["b"]
+["a"].intersection                                    # => ["a"]
+#@end
+
+@see [[m:Set#intersection]], [[m:Array#&]]
+#@end
 
 --- join(sep = $,)    -> String
 

refm/api/src/set.rd

@@ -451,10 +451,18 @@ nil を返します。
 @raise ArgumentError 引数が Enumerable オブジェクトでない場合に発生します。
 #@end
 
-  require 'set'
-  s1 = Set[10, 20, 30]
-  s2 = Set[10, 30, 50]
-  p s1 & s2 #=> #<Set: {10, 30}>
+#@samplecode
+require 'set'
+s1 = Set[10, 20, 30]
+s2 = Set[10, 30, 50]
+p s1 & s2 #=> #<Set: {10, 30}>
+#@end
+
+#@since 2.7.0
+@see [[m:Array#&]], [[m:Array#intersection]]
+#@else
+@see [[m:Array#&]]
+#@end
 
 --- ^(enum) -> Set