diff options
| author | BurdetteLamar <[email protected]> | 2024-08-17 19:18:32 +0100 |
|---|---|---|
| committer | Peter Zhu <[email protected]> | 2024-08-21 15:56:59 -0400 |
| commit | 76ccd1df3777312f865f83d5fd945b18140ecb48 (patch) | |
| tree | 3dd7f21be08526754337d4a435060a9592479b82 /enum.c | |
| parent | 53e37953791921b42c3d409b23c488861094f714 (diff) | |
[DOC] Tweaks for Enum#tally
Notes
Notes:
Merged: https://github.com/ruby/ruby/pull/11399
Diffstat (limited to 'enum.c')
| -rw-r--r-- | enum.c | 54 |
1 files changed, 36 insertions, 18 deletions
@@ -1235,29 +1235,47 @@ tally_i(RB_BLOCK_CALL_FUNC_ARGLIST(i, hash)) /* * call-seq: - * tally -> new_hash - * tally(hash) -> hash + * tally(hash = {}) -> hash * - * Returns a hash containing the counts of equal elements: + * When argument +hash+ is not given, + * returns a new hash whose keys are the distinct elements in +self+; + * each integer value is the count of occurrences of each element: * - * - Each key is an element of +self+. - * - Each value is the number elements equal to that key. + * %w[a b c b c a c b].tally # => {"a"=>2, "b"=>3, "c"=>3} * - * With no argument: + * When argument +hash+ is given, + * returns +hash+, possibly augmented; for each element +ele+ in +self+: * - * %w[a b c b c a c b].tally # => {"a"=>2, "b"=>3, "c"=>3} + * - Adds it as a key with a zero value if that key does not already exist: + * + * hash[ele] = 0 unless hash.include?(ele) + * + * - Increments the value of key +ele+: + * + * hash[ele] += 1 + * + * This is useful for accumulating tallies across multiple enumerables: + * + * h = {} # => {} + * %w[a c d b c a].tally(h) # => {"a"=>2, "c"=>2, "d"=>1, "b"=>1} + * %w[b a z].tally(h) # => {"a"=>3, "c"=>2, "d"=>1, "b"=>2, "z"=>1} + * %w[b a m].tally(h) # => {"a"=>4, "c"=>2, "d"=>1, "b"=>3, "z"=>1, "m"=>1} + * + * The key to be added or found for an element depends on the class of +self+; + * see {Enumerable in Ruby Classes}[rdoc-ref:Enumerable@Enumerable+in+Ruby+Classes]. + * + * Examples: + * + * - Array (and certain array-like classes): + * the key is the element (as above). + * - Hash (and certain hash-like classes): + * the key is the 2-element array formed from the key-value pair: * - * 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} + * h = {} # => {} + * {foo: 'a', bar: 'b'}.tally(h) # => {[:foo, "a"]=>1, [:bar, "b"]=>1} + * {foo: 'c', bar: 'd'}.tally(h) # => {[:foo, "a"]=>1, [:bar, "b"]=>1, [:foo, "c"]=>1, [:bar, "d"]=>1} + * {foo: 'a', bar: 'b'}.tally(h) # => {[:foo, "a"]=>2, [:bar, "b"]=>2, [:foo, "c"]=>1, [:bar, "d"]=>1} + * {foo: 'c', bar: 'd'}.tally(h) # => {[:foo, "a"]=>2, [:bar, "b"]=>2, [:foo, "c"]=>2, [:bar, "d"]=>2} * */ |