ruby-changes:62427
From: Burdette <ko1@a...>
Date: Thu, 30 Jul 2020 07:25:42 +0900 (JST)
Subject: [ruby-changes:62427] 35e5b8fb82 (master): Enhanced RDoc for Array (#3372)
https://git.ruby-lang.org/ruby.git/commit/?id=35e5b8fb82 From 35e5b8fb82ffd09ea34af88834588aa078ee9db3 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Wed, 29 Jul 2020 17:25:24 -0500 Subject: Enhanced RDoc for Array (#3372) diff --git a/array.c b/array.c index 8c14d5b..345ee32 100644 --- a/array.c +++ b/array.c @@ -6706,31 +6706,41 @@ push_value(st_data_t key, st_data_t val, st_data_t ary) https://github.com/ruby/ruby/blob/trunk/array.c#L6706 /* * call-seq: - * ary.uniq! -> ary or nil - * ary.uniq! {|item| ...} -> ary or nil + * array.uniq! -> self or nil + * array.uniq! {|element| ... } -> self or nil * - * Removes duplicate elements from +self+. + * Removes duplicate elements from +self+, the first occurrence always being retained; + * returns +self+ if any elements removed, +nil+ otherwise. * - * If a block is given, it will use the return value of the block for - * comparison. + * --- * - * It compares values using their #hash and #eql? methods for efficiency. + * With no block given, identifies and removes elements using method <tt>eql?</tt> + * to compare. * - * +self+ is traversed in order, and the first occurrence is kept. + * Returns +self+ if any elements removed: + * a = [0, 0, 1, 1, 2, 2] + * a1 = a.uniq! + * a1 # => [0, 1, 2] + * a1.equal?(a) # => true # Returned self * - * Returns +nil+ if no changes are made (that is, no duplicates are found). + * Returns +nil+ if no elements removed: + * [0, 1, 2].uniq! # => nil * - * a = [ "a", "a", "b", "b", "c" ] - * a.uniq! # => ["a", "b", "c"] + * --- * - * b = [ "a", "b", "c" ] - * b.uniq! # => nil + * With a block given, calls the block for each element; + * identifies (using method <tt>eql?</tt>) and removes + * elements for which the block returns duplicate values. * - * c = [["student","sam"], ["student","george"], ["teacher","matz"]] - * c.uniq! {|s| s.first} # => [["student", "sam"], ["teacher", "matz"]] + * Returns +self+ if any elements removed: + * a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb'] + * a1 = a.uniq! {|element| element.size } + * a1 # => ['a', 'aa', 'aaa'] + * a1.equal?(a) # => true # Returned self * + * Returns +nil+ if no elements removed: + * a.uniq! {|element| element.size } # => nil */ - static VALUE rb_ary_uniq_bang(VALUE ary) { @@ -6764,23 +6774,22 @@ rb_ary_uniq_bang(VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L6774 /* * call-seq: - * ary.uniq -> new_ary - * ary.uniq {|item| ...} -> new_ary - * - * Returns a new array by removing duplicate values in +self+. - * - * If a block is given, it will use the return value of the block for comparison. - * - * It compares values using their #hash and #eql? methods for efficiency. - * - * +self+ is traversed in order, and the first occurrence is kept. - * - * a = [ "a", "a", "b", "b", "c" ] - * a.uniq # => ["a", "b", "c"] - * - * b = [["student","sam"], ["student","george"], ["teacher","matz"]] - * b.uniq {|s| s.first} # => [["student", "sam"], ["teacher", "matz"]] - * + * array.uniq -> new_array + * array.uniq {|element| ... } -> new_array + * + * Returns a new \Array containing those elements from +self+ that are not duplicates, + * the first occurrence always being retained. + * + * With no block given, identifies and omits duplicates using method <tt>eql?</tt> + * to compare. + * a = [0, 0, 1, 1, 2, 2] + * a.uniq # => [0, 1, 2] + * + * With a block given, calls the block for each element; + * identifies (using method <tt>eql?</tt>) and omits duplicate values, + * that is, those elements for which the block returns the same value: + * a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb'] + * a.uniq { |element| element.size } # => ["a", "aa", "aaa"] */ static VALUE @@ -6810,14 +6819,17 @@ rb_ary_uniq(VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L6819 /* * call-seq: - * ary.compact! -> ary or nil + * array.compact! -> self or nil * - * Removes +nil+ elements from the array. + * Removes all +nil+ elements from +self+. * - * Returns +nil+ if no changes were made, otherwise returns the array. + * Returns +self+ if any elements removed: + * a = [nil, 0, nil, 1, nil, 2, nil] + * a1 = a.compact! # => [0, 1, 2] + * a1.equal?(a) # => true # Returned self * - * [ "a", nil, "b", nil, "c" ].compact! #=> [ "a", "b", "c" ] - * [ "a", "b", "c" ].compact! #=> nil + * Returns +nil+ if no elements removed: + * [0, 1, 2].compact! # => nil */ static VALUE @@ -6845,12 +6857,11 @@ rb_ary_compact_bang(VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L6857 /* * call-seq: - * ary.compact -> new_ary - * - * Returns a copy of +self+ with all +nil+ elements removed. + * array.compact -> new_array * - * [ "a", nil, "b", nil, "c", nil ].compact - * #=> [ "a", "b", "c" ] + * Returns a new \Array containing all non-+nil+ elements from +self+: + * a = [nil, 0, nil, 1, nil, 2, nil] + * a.compact # => [0, 1, 2] */ static VALUE @@ -6863,23 +6874,26 @@ rb_ary_compact(VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L6874 /* * call-seq: - * ary.count -> int - * ary.count(obj) -> int - * ary.count {|item| block} -> int + * array.count -> an_integer + * array.count(obj) -> an_integer + * array.count {|element| ... } -> an_integer * - * Returns the number of elements. + * Returns a count of specified elements. * - * If an argument is given, counts the number of elements which equal +obj+ - * using <code>==</code>. + * With no argument and no block, returns the count of all elements: + * [0, 1, 2].count # => 3 + * [].count # => 0 * - * If a block is given, counts the number of elements for which the block - * returns a true value. + * With argument +obj+, returns the count of elements <tt>eql?</tt> to +obj+: + * [0, 1, 2, 0].count(0) # => 2 + * [0, 1, 2].count(3) # => 0 * - * ary = [1, 2, 4, 2] - * ary.count #=> 4 - * ary.count(2) #=> 2 - * ary.count {|x| x%2 == 0} #=> 3 + * With no argument and a block given, calls the block with each element; + * returns the count of elements for which the block returns a truthy value: + * [0, 1, 2, 3].count {|element| element > 1} # => 2 * + * With argument +obj+ and a block given, issues a warning, ignores the block, + * and returns the count of elements <tt>eql?</tt> to +obj+: */ static VALUE @@ -6998,22 +7012,47 @@ flatten(VALUE ary, int level) https://github.com/ruby/ruby/blob/trunk/array.c#L7012 /* * call-seq: - * ary.flatten! -> ary or nil - * ary.flatten!(level) -> ary or nil + * array.flatten! -> self or nil + * array.flatten!(level) -> self or nil * - * Flattens +self+ in place. + * Replaces each nested \Array in +self+ with the elements from that \Array; + * returns +self+ if any changes, +nil+ otherwise. + * + * Argument +level+, if given, must be an + * {Integer-convertible object}[doc/implicit_conversion_rdoc.html#label-Integer-Convertible+Objects]. + * + * With non-negative argument +level+, flattens recursively through +level+ levels: + * a = [ 0, [ 1, [2, 3], 4 ], 5 ] + * a1 = a.flatten!(1) + * a1 # => [0, 1, [2, 3], 4, 5] + * a1.equal?(a) # => true # Returned self + * a = [ 0, [ 1, [2, 3], 4 ], 5 ] + * a.flatten!(2) # => [0, 1, 2, 3, 4, 5] + * a = [ 0, [ 1, [2, 3], 4 ], 5 ] + * a.flatten!(3) # => [0, 1, 2, 3, 4, 5] + * [0, 1, 2].flatten!(1) # => nil + * + * With no argument, or with negative argument +level+, flattens all levels: + * a = [ 0, [ 1, [2, 3], 4 ], 5 ] + * a.flatten! # => [0, 1, 2, 3, 4, 5] + * [0, 1, 2].flatten! # => nil + * a = [ 0, [ 1, [2, 3], 4 ], 5 ] + * a.flatten!(-1) # => [0, 1, 2, 3, 4, 5] + * a = [ 0, [ 1, [2, 3], 4 ], 5 ] + * a.flatten!(-2) # => [0, 1, 2, 3, 4, 5] + * [0, 1, 2].flatten!(-1) # => nil * - * Returns +nil+ if no modifications were made (i.e., the array contains no - * subarrays.) + * --- * - * The optional +level+ argument determines the level of recursion to flatten. + * Raises an exception if +level+ is not an Integer-convertible object: + * # Raises TypeError (no implicit conversion of Symbol into Integer): + * [].flatten!(:foo) * - * a = [ 1, 2, [3, [4, 5] ] ] - * a.flatten! #=> [1, 2, 3, 4, 5] - * a.flatten! #=> nil - * a #=> [1, 2, 3, 4, 5] - * a = [ 1, 2, [3, [4, 5] ] ] - * a.flatten!(1) #=> [1, 2, 3, [4, 5]] + * Raises an exception if +self+ contains a circular reference: + * a = [] + * a.push([a, a]) + * # Raises ArgumentError (tried to flatten recursive array): + * a.flatten! */ static VALUE @@ -7040,24 +7079,47 @@ rb_ary_flatten_bang(int argc, VALUE *argv, VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L7079 /* * call-seq: - * ary.flatten -> new_ary - * ary.flatten(level) -> new_ary + * array.flatten -> new_array + * array.flatten(level) -> new_array + * + * Returns a new \Array that is a recursive flattening of +self+: + * - Each non-Array element is unchanged. + * - Each \Array is replaced by its individual elements. + * + * Argument +level+, if given, must be + * {Integer-convertible object}[doc/implicit_conversion_rdoc.html#label-Integer-Convertible+Objects]. * - * Returns a new array that is a one-dimensional flattening of +self+ - * (recursively). + * With non-negative argument +level+, flattens recursively through +level+ levels: + * a = [ 0, [ 1, [2, 3], 4 ], 5 ] + * a.flatten(0) # => [0, [1, [2, 3], 4], 5] + * a = [ 0, [ 1, [2, 3], 4 ], 5 ] + * a.flatten(1) # => [0, 1, [2, 3], 4, 5] + * a = [ 0, [ 1, [2, 3], 4 ], 5 ] + * a.flatten(2) # => [0, 1, 2, 3, 4, 5] + * a = [ 0, [ 1, [2, 3], 4 ], 5 ] + * a.fla (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/