From e1b6e1d12607ee25a11feb7fcbe81ca1bc4b8cad Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Thu, 23 Jul 2020 15:06:14 -0500 Subject: Enhanced RDoc for Array [ci skip] --- array.c | 336 +++++++++++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 240 insertions(+), 96 deletions(-) diff --git a/array.c b/array.c index ed1850356b..8c14d5b7ce 100644 --- a/array.c +++ b/array.c @@ -5412,7 +5412,7 @@ ary_append(VALUE x, VALUE y) * * 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) /* * 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 eql?; + * 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) /* * 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 eql?; 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) /* * 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 eql?: + * [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) /* * 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 other_arys. 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 eql?: + * [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) /* * 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 eql?: + * [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) /* * 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 other_arys 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 eql?: + * [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([], :foo) * * See also Array#|. */ @@ -6320,25 +6364,64 @@ ary_max_opt_string(VALUE ary, long i, VALUE vmax) /* * call-seq: - * ary.max -> obj - * ary.max {|a, b| block} -> obj - * ary.max(n) -> array - * ary.max(n) {|a, b| block} -> array + * array.max -> element + * array.max {|a, b| ... } -> element + * array.max(n) -> new_array + * array.max(n) {|a, b| ... } -> new_array * - * Returns the object in _ary_ with the maximum value. The - * first form assumes all objects implement <=>; - * the second uses the block to return a <=> b. + * Returns one of the following: + * - The maximum-valued element from +self+. + * - A new \Array of maximum-valued elements selected from +self+. * - * ary = %w(albatross dog horse) - * ary.max #=> "horse" - * ary.max {|a, b| a.length <=> b.length} #=> "albatross" + * Argument +n+, if given, must be an + * {Integer-convertible object}[doc/implicit_conversion_rdoc.html#label-Integer-Convertible+Objects], + * and must be non-negative. * - * If the +n+ argument is given, maximum +n+ elements are returned - * as an array. + * --- * - * ary = %w[albatross dog horse] - * ary.max(2) #=> ["horse", "dog"] - * ary.max(2) {|a, b| a.length <=> b.length } #=> ["albatross", "horse"] + * When no block is given, each element in +self+ must respond to method <=> + * with an \Integer-convertible object. + * + * With no argument and no block, returns the element in +self+ + * having the maximum value per method <=>: + * [0, 1, 2].max # => 2 + * + * With an argument +n+ and no block, returns a new \Array with at most +n+ elements, + * in descending order per method <=>: + * [0, 1, 2, 3].max(3) # => [3, 2, 1] + * [0, 1, 2, 3].max(6) # => [3, 2, 1] + * [0, 1, 2, 3].max(0) # => [] + * + * --- + * + * When a block is given, the block must return an Integer-convertible object. + * + * With a block and no argument, calls the block self.size-1 times to compare elements; + * returns the element having the maximum value per the block: + * ['0', '00', '000'].max {|a, b| a.size <=> b.size } # => "000" + * + * With an argument +n+ and a block, returns a new \Array with at most +n+ elements, + * in descending order per the block: + * ['0', '00', '000'].max(2) {|a, b| a.size <=> b.size } # => ["000", "00"] + * ['0', '00', '000'].max(0) {|a, b| a.size <=> b.size } # => [] + * + * --- + * + * Raises an exception on encountering elements that are not comparable: + * # Raises ArgumentError (comparison of Symbol with 1 failed): + * [0, 1, :foo].max + * + * Raises an exception if argument +n+ is not an Integer-convertible object: + * # Raises TypeError (no implicit conversion of Symbol into Integer): + * [0, 1].max(:foo) + * + * Raises an exception if argument +n+ is negative: + * # Raises ArgumentError (negative size (-1)): + * [0, 1].max(-1) + * + * Raises an exception if the block returns an object that is not an Integer-convertible object: + * # Raises ArgumentError (comparison of Symbol with 0 failed): + * [0, 1, 2].max {|a, b| :foo } */ static VALUE rb_ary_max(int argc, VALUE *argv, VALUE ary) @@ -6472,25 +6555,65 @@ ary_min_opt_string(VALUE ary, long i, VALUE vmin) /* * call-seq: - * ary.min -> obj - * ary.min {| a,b | block } -> obj - * ary.min(n) -> array - * ary.min(n) {| a,b | block } -> array + * array.min -> element + * array.min { |a, b| ... } -> element + * array.min(n) -> new_array + * ary.min(n) { |a, b| ... } → new_array + * + * Returns one of the following: + * - The minimum-valued element from +self+. + * - A new \Array of minimum-valued elements selected from +self+. + * + * Argument +n+, if given, must be an + * {Integer-convertible object}[doc/implicit_conversion_rdoc.html#label-Integer-Convertible+Objects], + * and must be non-negative. + * + * --- * - * Returns the object in _ary_ with the minimum value. The - * first form assumes all objects implement <=>; - * the second uses the block to return a <=> b. + * When no block is given, each element in +self+ must respond to method <=> + * with an \Integer-convertible object. * - * ary = %w(albatross dog horse) - * ary.min #=> "albatross" - * ary.min {|a, b| a.length <=> b.length} #=> "dog" + * With no argument and no block, returns the element in +self+ + * having the minimum value per method <=>: + * [0, 1, 2].min # => 0 * - * If the +n+ argument is given, minimum +n+ elements are returned - * as an array. + * With an argument +n+ and no block, returns a new \Array with at most +n+ elements, + * in ascending order per method <=>: + * [0, 1, 2, 3].min(3) # => [0, 1, 2] + * [0, 1, 2, 3].min(6) # => [0, 1, 2, 3] + * [0, 1, 2, 3].min(0) # => [] * - * ary = %w[albatross dog horse] - * ary.min(2) #=> ["albatross", "dog"] - * ary.min(2) {|a, b| a.length <=> b.length } #=> ["dog", "horse"] + * --- + * + * When a block is given, the block must return an Integer-convertible object. + * + * With a block and no argument, calls the block self.size-1 times to compare elements; + * returns the element having the minimum value per the block: + * ['0', '00', '000'].min { |a, b| a.size <=> b.size } # => "0" + * + * With an argument +n+ and a block, returns a new \Array with at most +n+ elements, + * in ascending order per the block: + * [0, 1, 2, 3].min(3) # => [0, 1, 2] + * [0, 1, 2, 3].min(6) # => [0, 1, 2, 3] + * [0, 1, 2, 3].min(0) # => [] + * + * --- + * + * Raises an exception on encountering elements that are not comparable: + * # Raises ArgumentError (comparison of Symbol with 1 failed): + * [0, 1, :foo].min + * + * Raises an exception if argument +n+ is not an Integer-convertible object: + * # Raises TypeError (no implicit conversion of Symbol into Integer): + * [0, 1].min(:foo) + * + * Raises an exception if argument +n+ is negative: + * # Raises ArgumentError (negative size (-1)): + * [0, 1].min(-1) + * + * Raises an exception if the block returns an object that is not an Integer-convertible object: + * # Raises ArgumentError (comparison of Symbol with 0 failed): + * [0, 1, 2].min {|a, b| :foo } */ static VALUE rb_ary_min(int argc, VALUE *argv, VALUE ary) @@ -6535,14 +6658,35 @@ rb_ary_min(int argc, VALUE *argv, VALUE ary) /* * call-seq: - * ary.minmax -> [obj, obj] - * ary.minmax {| a,b | block } -> [obj, obj] + * array.minmax -> [min_val, max_val] + * array.minmax {|a, b| ... } -> [min_val, max_val] + * + * Returns a new 2-element \Array containing the minimum and maximum values + * from +self+, either per method <=> or per a given block:. + * + * --- * - * Returns a two element array which contains the minimum and the - * maximum value in the array. + * When no block is given, each element in +self+ must respond to method <=> + * with an \Integer-convertible object; + * returns a new 2-element \Array containing the minimum and maximum values + * from +self+, per method <=>: + * [0, 1, 2].minmax # => [0, 2] * - * Can be given an optional block to override the default comparison - * method a <=> b. + * When a block is given, the block must return an Integer-convertible object; + * the block is called self.size-1 times to compare elements; + * returns a new 2-element \Array containing the minimum and maximum values + * from +self+, per the block: + * ['0', '00', '000'].minmax {|a, b| a.size <=> b.size } # => ["0", "000"] + * + * --- + * + * Raises an exception on encountering elements that are not comparable: + * # Raises ArgumentError (comparison of Symbol with 1 failed): + * [0, 1, :foo].minmax + * + * Raises an exception if the block returns an object that is not an Integer-convertible object: + * # Raises ArgumentError (comparison of Symbol with 0 failed): + * [0, 1, 2].minmax {|a, b| :foo } */ static VALUE rb_ary_minmax(VALUE ary) -- cgit v1.2.3