diff options
author | Burdette Lamar <BurdetteLamar@Yahoo.com> | 2021-10-06 15:51:49 -0500 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-10-06 15:51:49 -0500 |
commit | fb122042e004c799d4ed7080785c86a57db0ee9c (patch) | |
tree | 8b57b38f5f6523f90a04c6620af50191ddc60bd5 /enum.c | |
parent | 121424a097a654084ef016bcc88cdb49c528d3ed (diff) | |
download | ruby-fb122042e004c799d4ed7080785c86a57db0ee9c.tar.gz |
Enhanced RDoc for Enumerable (#4941)
Treated:
#sum
#uniq
#compact
Diffstat (limited to 'enum.c')
-rw-r--r-- | enum.c | 78 |
1 files changed, 40 insertions, 38 deletions
@@ -4455,36 +4455,35 @@ int_range_sum(VALUE beg, VALUE end, int excl, VALUE init) } /* - * call-seq: - * enum.sum(init=0) -> number - * enum.sum(init=0) {|e| expr } -> number - * - * Returns the sum of elements in an Enumerable. + * call-seq: + * sum(initial_value = 0) -> number + * sum(initial_value = 0) {|element| ... } -> object * - * If a block is given, the block is applied to each element - * before addition. + * With no block given, + * returns the sum of +initial_value+ and the elements: * - * If <i>enum</i> is empty, it returns <i>init</i>. + * (1..100).sum # => 5050 + * (1..100).sum(1) # => 5051 + * ('a'..'d').sum('foo') # => "fooabcd" * - * For example: + * Generally, the sum is computed using methods <tt>+</tt> and +each+; + * for performance optimizations, those methods may not be used, + * and so any redefinition of those methods may not have effect here. * - * { 1 => 10, 2 => 20 }.sum {|k, v| k * v } #=> 50 - * (1..10).sum #=> 55 - * (1..10).sum {|v| v * 2 } #=> 110 - * ('a'..'z').sum #=> TypeError + * One such optimization: When possible, computes using Gauss's summation + * formula <em>n(n+1)/2</em>: * - * This method can be used for non-numeric objects by - * explicit <i>init</i> argument. + * 100 * (100 + 1) / 2 # => 5050 * - * { 1 => 10, 2 => 20 }.sum([]) #=> [1, 10, 2, 20] - * "a\nb\nc".each_line.lazy.map(&:chomp).sum("") #=> "abc" + * With a block given, calls the block with each element; + * returns the sum of +initial_value+ and the block return values: * - * If the method is applied to an Integer range without a block, - * the sum is not done by iteration, but instead using Gauss's summation - * formula. + * (1..4).sum {|i| i*i } # => 30 + * (1..4).sum(100) {|i| i*i } # => 130 + * h = {a: 0, b: 1, c: 2, d: 3, e: 4, f: 5} + * h.sum {|key, value| value.odd? ? value : 0 } # => 9 + * ('a'..'f').sum('x') {|c| c < 'd' ? c : '' } # => "xabc" * - * Enumerable#sum method may not respect method redefinition of "+" - * methods such as Integer#+, or "each" methods such as Range#each. */ static VALUE enum_sum(int argc, VALUE* argv, VALUE obj) @@ -4552,12 +4551,23 @@ uniq_iter(RB_BLOCK_CALL_FUNC_ARGLIST(i, hash)) /* * call-seq: - * enum.uniq -> new_ary - * enum.uniq { |item| ... } -> new_ary + * uniq -> array + * uniq {|element| ... } -> array + * + * With no block, returns a new array containing only unique elements; + * the array has no two elements +e0+ and +e1+ such that <tt>e0.eql?(e1)</tt>: * - * Returns a new array by removing duplicate values in +self+. + * %w[a b c c b a a b c].uniq # => ["a", "b", "c"] + * [0, 1, 2, 2, 1, 0, 0, 1, 2].uniq # => [0, 1, 2] + * + * With a block, returns a new array containing only for which the block + * returns a unique value: + * + * a = [0, 1, 2, 3, 4, 5, 5, 4, 3, 2, 1] + * a.uniq {|i| i.even? ? i : 0 } # => [0, 2, 4] + * a = %w[a b c d e e d c b a a b c d e] + a.uniq {|c| c < 'c' } # => ["a", "c"] * - * See also Array#uniq. */ static VALUE @@ -4587,21 +4597,13 @@ compact_i(RB_BLOCK_CALL_FUNC_ARGLIST(i, ary)) /* * call-seq: - * enum.compact -> array - * - * Returns an array of all non-+nil+ elements from enumeration. + * compact -> array * - * def with_nils - * yield 1 - * yield 2 - * yield nil - * yield 3 - * end + * Returns an array of all non-+nil+ elements: * - * to_enum(:with_nils).compact - * # => [1, 2, 3] + * a = [nil, 0, nil, 'a', false, nil, false, nil, 'a', nil, 0, nil] + * a.compact # => [0, "a", false, false, "a", 0] * - * See also Array#compact. */ static VALUE |