ruby-changes:68173
From: Burdette <ko1@a...>
Date: Thu, 30 Sep 2021 08:04:46 +0900 (JST)
Subject: [ruby-changes:68173] 49edaa061f (master): Enhanced RDoc for Enumerable (#4910)
https://git.ruby-lang.org/ruby.git/commit/?id=49edaa061f From 49edaa061fc2a910a167fd02c01b4be8845d25cc Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Wed, 29 Sep 2021 18:04:29 -0500 Subject: Enhanced RDoc for Enumerable (#4910) Treats: #min #max #minmax #min_by #max_by #minmax_by #include? --- enum.c | 284 +++++++++++++++++++++++++++++++++++++---------------------------- 1 file changed, 160 insertions(+), 124 deletions(-) diff --git a/enum.c b/enum.c index f049f086d7..03b432a983 100644 --- a/enum.c +++ b/enum.c @@ -2063,15 +2063,15 @@ min_ii(RB_BLOCK_CALL_FUNC_ARGLIST(i, args)) https://github.com/ruby/ruby/blob/trunk/enum.c#L2063 /* * call-seq: - * min -> element - * min(n) -> array - * min {|a, b| block } -> element - * min(n) {|a, b| block } -> array + * min -> element + * min(n) -> array + * min {|a, b| ... } -> element + * min(n) {|a, b| ... } -> array * - * Returns the element with the minimum value according to a given criterion. + * Returns the element with the minimum element according to a given criterion. * The ordering of equal elements is indeterminate and may be unstable. * - * With no argument and no block, returns the minimum value, + * With no argument and no block, returns the minimum element, * using the elements' own method <tt><=></tt> for comparison: * * (1..4).min # => 1 @@ -2081,7 +2081,7 @@ min_ii(RB_BLOCK_CALL_FUNC_ARGLIST(i, args)) https://github.com/ruby/ruby/blob/trunk/enum.c#L2081 * [].min # => nil * * With positive integer argument +n+ given, and no block, - * returns an array containing the first +n+ minimum values that exist: + * returns an array containing the first +n+ minimum elements that exist: * * (1..4).min(2) # => [1, 2] * (-4..-1).min(2) # => [-4, -3] @@ -2089,7 +2089,7 @@ min_ii(RB_BLOCK_CALL_FUNC_ARGLIST(i, args)) https://github.com/ruby/ruby/blob/trunk/enum.c#L2089 * {foo: 0, bar: 1, baz: 2}.min(2) # => [[:bar, 1], [:baz, 2]] * [].min(2) # => [] * - * With a block given, the block determines the minimum values. + * With a block given, the block determines the minimum elements. * The block is called with two elements +a+ and +b+, and must return: * * - A negative integer if <tt>a < b</tt>. @@ -2097,7 +2097,7 @@ min_ii(RB_BLOCK_CALL_FUNC_ARGLIST(i, args)) https://github.com/ruby/ruby/blob/trunk/enum.c#L2097 * - A positive integer if <tt>a > b</tt>. * * With a block given and no argument, - * returns the minimum value as determined by the block: + * returns the minimum element as determined by the block: * * %w[xxx x xxxx xx].min {|a, b| a.size <=> b.size } # => "x" * [].min {|a, b| a <=> b } # => nil @@ -2109,6 +2109,8 @@ min_ii(RB_BLOCK_CALL_FUNC_ARGLIST(i, args)) https://github.com/ruby/ruby/blob/trunk/enum.c#L2109 * %w[xxx x xxxx xx].min(2) {|a, b| a.size <=> b.size } # => ["x", "xx"] * [].min(2) {|a, b| a <=> b } # => [] * + * Related: #min_by, #minmax, #max. + * */ static VALUE @@ -2181,26 +2183,54 @@ max_ii(RB_BLOCK_CALL_FUNC_ARGLIST(i, args)) https://github.com/ruby/ruby/blob/trunk/enum.c#L2183 /* * call-seq: - * enum.max -> obj - * enum.max { |a, b| block } -> obj - * enum.max(n) -> array - * enum.max(n) { |a, b| block } -> array - * - * Returns the object in _enum_ with the maximum value. The - * first form assumes all objects implement <code><=></code>; - * the second uses the block to return <em>a <=> b</em>. - * - * a = %w(albatross dog horse) - * a.max #=> "horse" - * a.max { |a, b| a.length <=> b.length } #=> "albatross" - * - * If the +n+ argument is given, maximum +n+ elements are returned - * as an array, sorted in descending order. - * - * a = %w[albatross dog horse] - * a.max(2) #=> ["horse", "dog"] - * a.max(2) {|a, b| a.length <=> b.length } #=> ["albatross", "horse"] - * [5, 1, 3, 4, 2].max(3) #=> [5, 4, 3] + * max -> element + * max(n) -> array + * max {|a, b| ... } -> element + * max(n) {|a, b| ... } -> array + * + * Returns the element with the maximum element according to a given criterion. + * The ordering of equal elements is indeterminate and may be unstable. + * + * With no argument and no block, returns the maximum element, + * using the elements' own method <tt><=></tt> for comparison: + * + * (1..4).max # => 4 + * (-4..-1).max # => -1 + * %w[d c b a].max # => "d" + * {foo: 0, bar: 1, baz: 2}.max # => [:foo, 0] + * [].max # => nil + * + * With positive integer argument +n+ given, and no block, + * returns an array containing the first +n+ maximum elements that exist: + * + * (1..4).max(2) # => [4, 3] + * (-4..-1).max(2) # => [-1, -2] + * %w[d c b a].max(2) # => ["d", "c"] + * {foo: 0, bar: 1, baz: 2}.max(2) # => [[:foo, 0], [:baz, 2]] + * [].max(2) # => [] + * + * With a block given, the block determines the maximum elements. + * The block is called with two elements +a+ and +b+, and must return: + * + * - A negative integer if <tt>a < b</tt>. + * - Zero if <tt>a == b</tt>. + * - A positive integer if <tt>a > b</tt>. + * + * With a block given and no argument, + * returns the maximum element as determined by the block: + * + * %w[xxx x xxxx xx].max {|a, b| a.size <=> b.size } # => "xxxx" + * [].max {|a, b| a <=> b } # => nil + * + * With a block given and positive integer argument +n+ given, + * returns an array containing the first +n+ maximum elements that exist, + * as determined by the block. + * + * %w[xxx x xxxx xx].max(2) {|a, b| a.size <=> b.size } # => ["xxxx", "xxx"] + * [].max(2) {|a, b| a <=> b } # => [] + * + * Related: #min, #minmax, #max_by. + * */ static VALUE @@ -2341,17 +2371,30 @@ minmax_ii(RB_BLOCK_CALL_FUNC_ARGLIST(i, _memo)) https://github.com/ruby/ruby/blob/trunk/enum.c#L2371 /* * call-seq: - * enum.minmax -> [min, max] - * enum.minmax { |a, b| block } -> [min, max] + * minmax -> [minimum, maximum] + * minmax {|a, b| ... } -> [minimum, maximum] * - * Returns a two element array which contains the minimum and the - * maximum value in the enumerable. The first form assumes all - * objects implement <code><=></code>; the second uses the - * block to return <em>a <=> b</em>. + * Returns a 2-element array containing the minimum and maximum elements + * according to a given criterion. + * The ordering of equal elements is indeterminate and may be unstable. + * + * With no argument and no block, returns the minimum and maximum elements, + * using the elements' own method <tt><=></tt> for comparison: + * + * (1..4).minmax # => [1, 4] + * (-4..-1).minmax # => [-4, -1] + * %w[d c b a].minmax # => ["a", "d"] + * {foo: 0, bar: 1, baz: 2}.minmax # => [[:bar, 1], [:foo, 0]] + * [].minmax # => [nil, nil] + * + * With a block given, returns the minimum and maximum elements + * as determined by the block: + * + * %w[xxx x xxxx xx].minmax {|a, b| a.size <=> b.size } # => ["x", "xxxx"] + * [].minmax {|a, b| a <=> b } # => [nil, nil] + * + * Related: #min, #max, #minmax_by. * - * a = %w(albatross dog horse) - * a.minmax #=> ["albatross", "horse"] - * a.minmax { |a, b| a.length <=> b.length } #=> ["dog", "albatross"] */ static VALUE @@ -2403,25 +2446,38 @@ min_by_i(RB_BLOCK_CALL_FUNC_ARGLIST(i, args)) https://github.com/ruby/ruby/blob/trunk/enum.c#L2446 /* * call-seq: - * enum.min_by {|obj| block } -> obj - * enum.min_by -> an_enumerator - * enum.min_by(n) {|obj| block } -> array - * enum.min_by(n) -> an_enumerator + * min_by {|element| ... } -> element + * min_by(n) {|element| ... } -> array + * min_by -> enumerator + * min_by(n) -> enumerator * - * Returns the object in <i>enum</i> that gives the minimum - * value from the given block. + * Returns the elements for which the block returns the minimum values. * - * If no block is given, an enumerator is returned instead. + * With a block given and no argument, + * returns the element for which the block returns the minimum value: + * + * (1..4).min_by {|element| -element } # => 4 + * %w[a b c d].min_by {|element| -element.ord } # => "d" + * {foo: 0, bar: 1, baz: 2}.min_by {|key, value| -value } # => [:baz, 2] + * [].min_by {|element| -element } # => nil + * + * With a block given and positive integer argument +n+ given, + * returns an array containing the +n+ elements + * for which the block returns minimum values: * - * a = %w(albatross dog horse) - * a.min_by { |x| x.length } #=> "dog" + * (1..4).min_by(2) {|element| -element } + * # => [4, 3] + * %w[a b c d].min_by(2) {|element| -element.ord } + * # => ["d", "c"] + * {foo: 0, bar: 1, baz: 2}.min_by(2) {|key, value| -value } + * # => [[:baz, 2], [:bar, 1]] + * [].min_by(2) {|element| -element } + * # => [] * - * If the +n+ argument is given, minimum +n+ elements are returned - * as an array. These +n+ elements are sorted by the value from the - * given block. + * Returns an Enumerator if no block is given. + * + * Related: #min, #minmax, #max_by (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/