ruby-changes:68168
From: Burdette <ko1@a...>
Date: Wed, 29 Sep 2021 01:39:01 +0900 (JST)
Subject: [ruby-changes:68168] 1e10099e09 (master): Enhanced RDoc for Enumerable (#4906)
https://git.ruby-lang.org/ruby.git/commit/?id=1e10099e09 From 1e10099e0919eda9464ef454b4920213eca658f3 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Tue, 28 Sep 2021 11:38:35 -0500 Subject: Enhanced RDoc for Enumerable (#4906) Treats: #partition #group_by #tally #first #sort #sort_by #all? #any? --- enum.c | 264 +++++++++++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 176 insertions(+), 88 deletions(-) diff --git a/enum.c b/enum.c index 2ce2cfad24..d29e598a07 100644 --- a/enum.c +++ b/enum.c @@ -1066,16 +1066,29 @@ partition_i(RB_BLOCK_CALL_FUNC_ARGLIST(i, arys)) https://github.com/ruby/ruby/blob/trunk/enum.c#L1066 /* * call-seq: - * enum.partition { |obj| block } -> [ true_array, false_array ] - * enum.partition -> an_enumerator + * partition {|element| ... } -> [true_array, false_array] + * partition -> enumerator * - * Returns two arrays, the first containing the elements of - * <i>enum</i> for which the block evaluates to true, the second - * containing the rest. + * With a block given, returns an array of two arrays: * - * If no block is given, an enumerator is returned instead. + * - The first having those elements for which the block returns a truthy value. + * - The other having all other elements. + * + * Examples: + * + * p = (1..4).partition {|i| i.even? } + * p # => [[2, 4], [1, 3]] + * p = ('a'..'d').partition {|c| c < 'c' } + * p # => [["a", "b"], ["c", "d"]] + * h = {foo: 0, bar: 1, baz: 2, bat: 3} + * p = h.partition {|key, value| key.start_with?('b') } + * p # => [[[:bar, 1], [:baz, 2], [:bat, 3]], [[:foo, 0]]] + * p = h.partition {|key, value| value < 2 } + * p # => [[[:foo, 0], [:bar, 1]], [[:baz, 2], [:bat, 3]]] + * + * With no block given, returns an Enumerator. * - * (1..6).partition { |v| v.even? } #=> [[2, 4, 6], [1, 3, 5]] + * Related: Enumerable#group_by. * */ @@ -1114,16 +1127,23 @@ group_by_i(RB_BLOCK_CALL_FUNC_ARGLIST(i, hash)) https://github.com/ruby/ruby/blob/trunk/enum.c#L1127 /* * call-seq: - * enum.group_by { |obj| block } -> a_hash - * enum.group_by -> an_enumerator + * group_by {|element| ... } -> hash + * group_by -> enumerator * - * Groups the collection by result of the block. Returns a hash where the - * keys are the evaluated result from the block and the values are - * arrays of elements in the collection that correspond to the key. + * With a block given returns a hash: * - * If no block is given an enumerator is returned. + * - Each key is a return value from the block. + * - Each value is an array of those elements for which the block returned that key. * - * (1..6).group_by { |i| i%3 } #=> {0=>[3, 6], 1=>[1, 4], 2=>[2, 5]} + * Examples: + * + * g = (1..6).group_by {|i| i%3 } + * g # => {1=>[1, 4], 2=>[2, 5], 0=>[3, 6]} + * h = {foo: 0, bar: 1, baz: 0, bat: 1} + * g = h.group_by {|key, value| value } + * g # => {0=>[[:foo, 0], [:baz, 0]], 1=>[[:bar, 1], [:bat, 1]]} + * + * With no block given, returns an Enumerator. * */ @@ -1173,18 +1193,30 @@ tally_i(RB_BLOCK_CALL_FUNC_ARGLIST(i, hash)) https://github.com/ruby/ruby/blob/trunk/enum.c#L1193 /* * call-seq: - * enum.tally -> a_hash - * enum.tally(a_hash) -> a_hash + * tally -> new_hash + * tally(hash) -> hash + * + * Returns a hash containing the counts of equal elements: + * + * - Each key is an element of +self+. + * - Each value is the number elements equal to that key. * - * Tallies the collection, i.e., counts the occurrences of each element. - * Returns a hash with the elements of the collection as keys and the - * corresponding counts as values. + * With no argument: * - * ["a", "b", "c", "b"].tally #=> {"a"=>1, "b"=>2, "c"=>1} + * %w[a b c b c a c b].tally # => {"a"=>2, "b"=>3, "c"=>3} + * + * With a hash argument, that hash is used for the tally (instead of a new hash), + * and is returned; + * this may be useful for accumulating tallies across multiple enumerables: + * + * hash = {} + * hash = %w[a c d b c a].tally(hash) + * hash # => {"a"=>2, "c"=>2, "d"=>1, "b"=>1} + * hash = %w[b a z].tally(hash) + * hash # => {"a"=>3, "c"=>2, "d"=>1, "b"=>2, "z"=>1} + * hash = %w[b a m].tally(hash) + * hash # => {"a"=>4, "c"=>2, "d"=>1, "b"=>3, "z"=>1, "m"=> 1} * - * If a hash is given, the number of occurrences is added to each value - * in the hash, and the hash is returned. The value corresponding to - * each element must be an integer. */ static VALUE @@ -1219,18 +1251,26 @@ static VALUE enum_take(VALUE obj, VALUE n); https://github.com/ruby/ruby/blob/trunk/enum.c#L1251 /* * call-seq: - * enum.first -> obj or nil - * enum.first(n) -> an_array + * first -> element or nil + * first(n) -> array + * + * Returns the first element or elements. + * + * With no argument, returns the first element, or +nil+ if there is none: * - * Returns the first element, or the first +n+ elements, of the enumerable. - * If the enumerable is empty, the first form returns <code>nil</code>, and the - * second form returns an empty array. + * (1..4).first # => 1 + * %w[a b c].first # => "a" + * {foo: 1, bar: 1, baz: 2}.first # => [:foo, 1] + * [].first # => nil * - * %w[foo bar baz].first #=> "foo" - * %w[foo bar baz].first(2) #=> ["foo", "bar"] - * %w[foo bar baz].first(10) #=> ["foo", "bar", "baz"] - * [].first #=> nil - * [].first(10) #=> [] + * With integer argument +n+, returns an array + * containing the first +n+ elements that exist: + * + * (1..4).first(2) # => [1, 2] + * %w[a b c d].first(3) # => ["a", "b", "c"] + * %w[a b c d].first(50) # => ["a", "b", "c", "d"] + * {foo: 1, bar: 1, baz: 2}.first(2) # => [[:foo, 1], [:bar, 1]] + * [].first(2) # => [] * */ @@ -1249,28 +1289,35 @@ enum_first(int argc, VALUE *argv, VALUE obj) https://github.com/ruby/ruby/blob/trunk/enum.c#L1289 } } - /* * call-seq: - * enum.sort -> array - * enum.sort { |a, b| block } -> array + * sort -> array + * sort {|a, b| ... } -> array + * + * Returns an array containing the sorted elements of +self+. + * The ordering of equal elements is indeterminate and may be unstable. + * + * With no block given, the sort compares + * using the items' own method <tt><=></tt>: * - * Returns an array containing the items in <i>enum</i> sorted. + * %w[b c a d].sort # => ["a", "b", "c", "d"] + * {foo: 0, bar: 1, baz: 2}.sort # => [[:bar, 1], [:baz, 2], [:foo, 0]] * - * Comparisons for the sort will be done using the items' own - * <code><=></code> operator or using an optional code block. + * With a block given, comparisons in the block determine the ordering. + * The block is called with two elements +a+ and +b+, and must return: * - * The block must implement a comparison between +a+ and +b+ and return - * an integer less than 0 when +b+ follows +a+, +0+ when +a+ and +b+ - * are equivalent, or an integer greater than 0 when +a+ follows +b+. + * - A negative integer if <tt>a < b</tt>. + * - Zero if <tt>a == b</tt>. + * - A positive integer if <tt>a > b</tt>. * - * The result is not guaranteed to be stable. When the comparison of two - * elements returns +0+, the order of the elements is unpredictable. + * Examples: * - * %w(rhea kea flea).sort #=> ["flea", "kea", "rhea"] - * (1..10).sort { |a, b| b <=> a } #=> [10, 9, 8, 7, 6, 5, 4, 3, 2, 1] + * a = %w[b c a d] + * a.sort {|a, b| b <=> a } # => ["d", "c", "b", "a"] + * h = {foo: 0, bar: 1, baz: 2} + * h.sort {|a, b| b <=> a } # => [[:foo, 0], [:baz, 2], [:bar, 1]] * - * See also Enumerable#sort_by. It implements a Schwartzian transform + * See also #sort_by. It implements a Schwartzian transform * which is useful when key computation or comparison is expensive. */ @@ -1335,19 +1382,23 @@ sort_by_cmp(const void *ap, const void *bp, void *data) https://github.com/ruby/ruby/blob/trunk/enum.c#L1382 /* * call-seq: - * enum.sort_by { |obj| block } -> array - * enum.sort_by -> an_enumerator + * sort_by {|element| ... } -> array + * sort_by -> enumerator * - * Sorts <i>enum</i> using a set of keys generated by mapping the - * values in <i>enum</i> through the given block. + * With a block given, returns an array of elements of +self+, + * sorted according to the value returned by the block for each element. + * The ordering of equal elements is indeterminate and may be unstable. * - * The result is not guaranteed to be stable. When two keys are equal, - * the order of the corresponding elements is unpredictable. + * Examples: * - * If no block is given, an enumerator is returned instead. + * a = %w[xx xxx x xxxx] + * a.sort_by {|s| s.size } # => ["x", "xx", "xxx", "xxxx"] + * a.sort_by {|s| -s.size } # => ["xxxx", "xxx", "xx", "x"] + * h = {foo: 2, bar: 1, baz: 0} + * h.sort_by{|key, value| value } # => [[:baz, 0], [:bar, 1], [:foo, 2]] + * h.sort_by{|key, value| key } # => [[:bar, 1], [:baz, 0], [:foo, 2]] * - * %w{apple pear fig}.sort_by { |word| word.length } - * #=> ["fig", "pear", "apple"] + * With no block given, returns an Enumerator. * * The current implementation of #sort_by generates an array of * tuples containing the original collection element and the mapped @@ -1505,25 +1556,44 @@ DEFINE_ENUMFUNCS(all) https://github.com/ruby/ruby/blob/trunk/enum.c#L1556 /* * call-seq: - * enum.all? [{ |obj| block } ] -> true or false - * enum.all?(pattern) -> true or false + * all (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/