ruby-changes:62415
From: BurdetteLamar <ko1@a...>
Date: Wed, 29 Jul 2020 04:06:13 +0900 (JST)
Subject: [ruby-changes:62415] e1b6e1d126 (master): Enhanced RDoc for Array [ci skip]
https://git.ruby-lang.org/ruby.git/commit/?id=e1b6e1d126 From e1b6e1d12607ee25a11feb7fcbe81ca1bc4b8cad Mon Sep 17 00:00:00 2001 From: BurdetteLamar <burdettelamar@y...> Date: Thu, 23 Jul 2020 15:06:14 -0500 Subject: Enhanced RDoc for Array [ci skip] diff --git a/array.c b/array.c index ed18503..8c14d5b 100644 --- a/array.c +++ b/array.c @@ -5412,7 +5412,7 @@ ary_append(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/array.c#L5412 * * Returns +self+ unmodified if no arguments given: * a = [0, 1] - * a.concat + * a.concat(*[]) * a # => [0, 1] * * --- @@ -5920,23 +5920,24 @@ ary_recycle_hash(VALUE hash) https://github.com/ruby/ruby/blob/trunk/array.c#L5920 /* * call-seq: - * ary - other_ary -> new_ary + * array - other_array -> new_array * - * Array Difference - * - * Returns a new array that is a copy of the original array, removing all - * occurrences of any item that also appear in +other_ary+. The order is - * preserved from the original array. - * - * It compares elements using their #hash and #eql? methods for efficiency. + * Argument +other_array+ must be an + * {Array-convertible object}[doc/implicit_conversion_rdoc.html#label-Array-Convertible+Objects]. * - * [ 1, 1, 2, 2, 3, 3, 4, 5 ] - [ 1, 2, 4 ] #=> [ 3, 3, 5 ] + * Returns a new \Array containing only those elements from +array+ + * that are not found in +other_array+; + * items are compared using <tt>eql?</tt>; + * the order from +array+ is preserved: + * [0, 1, 1, 2, 1, 1, 3, 1, 1] - [1] # => [0, 2, 3] + * [0, 1, 2, 3] - [3, 0] # => [1, 2] + * [0, 1, 2] - [4] # => [0, 1, 2] * - * Note that while 1 and 2 were only present once in the array argument, and - * were present twice in the receiver array, all occurrences of each Integer are - * removed in the returned array. + * --- * - * If you need set-like behavior, see the library class Set. + * Raises an exception if +other_array+ is not an Array-convertible object: + * # Raises TypeError (no implicit conversion of Symbol into Array): + * [] - :foo * * See also Array#difference. */ @@ -5971,29 +5972,29 @@ rb_ary_diff(VALUE ary1, VALUE ary2) https://github.com/ruby/ruby/blob/trunk/array.c#L5972 /* * call-seq: - * ary.difference(other_ary1, other_ary2, ...) -> new_ary - * - * Array Difference - * - * Returns a new array that is a copy of the original array, removing all - * occurrences of any item that also appear in +other_ary+. The order is - * preserved from the original array. + * array.difference(*other_arrays) -> new_array * - * 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 ] + * Each argument in +other_arrays+ must be an + * {Array-convertible object}[doc/implicit_conversion_rdoc.html#label-Array-Convertible+Objects]. * - * Note that while 1 and 2 were only present once in the array argument, and - * were present twice in the receiver array, all occurrences of each Integer are - * removed in the returned array. + * Returns a new \Array containing only those elements from +self+ + * that are not found in any of the +other_arrays+; + * items are compared using <tt>eql?</tt>; order from +self+ is preserved: + * [0, 1, 1, 2, 1, 1, 3, 1, 1].difference([1]) # => [0, 2, 3] + * [0, 1, 2, 3].difference([3, 0], [1, 3]) # => [2] + * [0, 1, 2].difference([4]) # => [0, 1, 2] * - * Multiple array arguments can be supplied and all occurrences of any element - * in those supplied arrays that match the receiver will be removed from the - * returned array. + * Returns a copy of +self+ if no arguments given: + * a0 = [0, 1] + * a1 = a0.difference(*[]) + * a1 # => [0, 1] + * a1.equal?(a0) # => false * - * [ 1, 'c', :s, 'yep' ].difference([ 1 ], [ 'a', 'c' ]) #=> [ :s, "yep" ] + * --- * - * If you need set-like behavior, see the library class Set. + * Raises an exception if any of +other_arrays+ is not an Array-convertible object: + * # Raises TypeError (no implicit conversion of Symbol into Array): + * [].difference(:foo) * * See also Array#-. */ @@ -6037,17 +6038,26 @@ rb_ary_difference_multi(int argc, VALUE *argv, VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L6038 /* * call-seq: - * ary & other_ary -> new_ary + * array & other_array -> new_array + * + * Argument +other_array+ must be an + * {Array-convertible object}[doc/implicit_conversion_rdoc.html#label-Array-Convertible+Objects]. * - * Set Intersection --- Returns a new array containing unique elements common to the - * two arrays. The order is preserved from the original array. + * Returns a new \Array containing each element found in both +array+ and +other_array+; + * duplicates are omitted; items are compared using <tt>eql?</tt>: + * [0, 1, 2, 3] & [1, 2] # => [1, 2] + * [0, 1, 0, 1] & [0, 1] # => [0, 1] * - * It compares elements using their #hash and #eql? methods for efficiency. + * Preserves order from +array+: + * [0, 1, 2] & [3, 2, 1, 0] # => [0, 1, 2] * - * [ 1, 1, 3, 5 ] & [ 3, 2, 1 ] #=> [ 1, 3 ] - * [ 'a', 'b', 'b', 'z' ] & [ 'a', 'b', 'c' ] #=> [ 'a', 'b' ] + * --- * - * See also Array#uniq. + * Raises an exception if +other_array+ is not an Array-convertible object: + * # Raises TypeError (no implicit conversion of Symbol into Array): + * [] & :foo + * + * See also Array#intersection. */ @@ -6088,17 +6098,31 @@ rb_ary_and(VALUE ary1, VALUE ary2) https://github.com/ruby/ruby/blob/trunk/array.c#L6098 /* * call-seq: - * ary.intersection(other_ary1, other_ary2, ...) -> new_ary + * array.intersection(*other_arrays) -> new_array * - * Set Intersection --- Returns a new array containing unique elements common - * to +self+ and <code>other_ary</code>s. Order is preserved from the original - * array. + * Each object in +other_arrays+ must be an + * {Array-convertible object}[doc/implicit_conversion_rdoc.html#label-Array-Convertible+Objects]. + * + * Returns a new \Array containing each element found both in +self+ + * and in all of the given +other_arrays+; + * duplicates are omitted; items are compared using <tt>eql?</tt>: + * [0, 1, 2, 3].intersection([0, 1, 2], [0, 1, 3]) # => [0, 1] + * [0, 0, 1, 1, 2, 3].intersection([0, 1, 2], [0, 1, 3]) # => [0, 1] + * + * Preserves order from +self+: + * [0, 1, 2].intersection([2, 1, 0]) # => [0, 1, 2] * - * It compares elements using their #hash and #eql? methods for efficiency. + * Returns a copy of +self+ if no arguments given: + * a0 = [0, 1] + * a1 = a0.intersection(*[]) + * a1 # => [0, 1] + * a1.equal?(a0) # => false + * + * --- * - * [ 1, 1, 3, 5 ].intersection([ 3, 2, 1 ]) # => [ 1, 3 ] - * [ "a", "b", "z" ].intersection([ "a", "b", "c" ], [ "b" ]) # => [ "b" ] - * [ "a" ].intersection #=> [ "a" ] + * Raises an exception if any of the given +other_arrays+ is not an Array-convertible object: + * # Raises TypeError (no implicit conversion of Symbol into Array): + * [].intersection([0, 1], :foo) * * See also Array#&. */ @@ -6149,15 +6173,23 @@ rb_ary_union_hash(VALUE hash, VALUE ary2) https://github.com/ruby/ruby/blob/trunk/array.c#L6173 /* * call-seq: - * ary | other_ary -> new_ary + * array | other_array -> new_array * - * Set Union --- Returns a new array by joining +ary+ with +other_ary+, - * excluding any duplicates and preserving the order from the given arrays. + * Argument +other_array+ must be an + * {Array-convertible object}[doc/implicit_conversion_rdoc.html#label-Array-Convertible+Objects]. * - * It compares elements using their #hash and #eql? methods for efficiency. + * Returns the union of +array+ and +other_array+; + * duplicates are removed; order is preserved; + * items are compared using <tt>eql?</tt>: + * [0, 1] | [2, 3] # => [0, 1, 2, 3] + * [0, 1, 1] | [2, 2, 3] # => [0, 1, 2, 3] + * [0, 1, 2] | [3, 2, 1, 0] # => [0, 1, 2, 3] + * + * --- * - * [ "a", "b", "c" ] | [ "c", "d", "a" ] #=> [ "a", "b", "c", "d" ] - * [ "c", "d", "a" ] | [ "a", "b", "c" ] #=> [ "c", "d", "a", "b" ] + * Raises an exception if +other_array+ is not an Array-convertible object: + * # Raises TypeError (no implicit conversion of Symbol into Array): + * [] | :foo * * See also Array#union. */ @@ -6185,16 +6217,28 @@ rb_ary_or(VALUE ary1, VALUE ary2) https://github.com/ruby/ruby/blob/trunk/array.c#L6217 /* * call-seq: - * ary.union(other_ary1, other_ary2, ...) -> new_ary + * array.union(*other_arrays) -> new_array + * + * Each object in +other_arrays+ must be an + * {Array-convertible object}[doc/implicit_conversion_rdoc.html#label-Array-Convertible+Objects]. * - * Set Union --- Returns a new array by joining <code>other_ary</code>s with +self+, - * excluding any duplicates and preserving the order from the given arrays. + * Returns a new \Array that is the union of +self+ and all given +other_arrays+; + * duplicates are removed; order is preserved; items are compared using <tt>eql?</tt>: + * [0, 1, 2, 3].union([4, 5], [6, 7]) # => [0, 1, 2, 3, 4, 5, 6, 7] + * [0, 1, 1].union([2, 1], [3, 1]) # => [0, 1, 2, 3] + * [0, 1, 2, 3].union([3, 2], [1, 0]) # => [0, 1, 2, 3] * - * It compares elements using their #hash and #eql? methods for efficiency. + * Returns a copy of +self+ if no arguments given: + * a0 = [0, 1] + * a1 = a0.union(*[]) + * a1 # => [0, 1] + * a1.equal?(a0) # => false * - * [ "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" ] + * --- + * + * Raises an exception if any argument is not an \Array-convertible object: + * # Raises TypeError (no implicit conversion of Symbol into Array): + * [].union([], (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/