From b8bfb1d5f5b15aa0bfa54ac3f97af1034f16359b Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Thu, 27 Aug 2020 08:31:32 -0500 Subject: Comply with guide for method doc: hash.c (#3459) Instance methods considered (some maybe not changed): clear []= replace length empty? each_value each_key each_pair transform_keys transform_keys! transform_values transform_values! --- hash.c | 64 +++++++++++----------------------------------------------------- 1 file changed, 11 insertions(+), 53 deletions(-) (limited to 'hash.c') diff --git a/hash.c b/hash.c index 0f9f932015..ebe600f58a 100644 --- a/hash.c +++ b/hash.c @@ -2837,9 +2837,7 @@ clear_i(VALUE key, VALUE value, VALUE dummy) * call-seq: * hash.clear -> self * - * Removes all hash entries; returns +self+: - * h = {foo: 0, bar: 1, baz: 2} - * h.clear # => {} + * Removes all hash entries; returns +self+. */ VALUE @@ -2903,7 +2901,9 @@ NOINSERT_UPDATE_CALLBACK(hash_aset_str) * hash[key] = value -> value * hash.store(key, value) * - * Associates the given +value+ with the given +key+, and returns +value+. + * Hash#store is an alias for Hash#[]=. + + * Associates the given +value+ with the given +key+; returns +value+. * * If the given +key+ exists, replaces its value with the given +value+; * the ordering is not affected @@ -2997,8 +2997,7 @@ rb_hash_replace(VALUE hash, VALUE hash2) * hash.size -> integer * * Returns the count of entries in +self+: - * h = {foo: 0, bar: 1, baz: 2} - * h.length # => 3 + * {foo: 0, bar: 1, baz: 2}.length # => 3 * * Hash#length is an alias for Hash#size. */ @@ -3050,7 +3049,7 @@ each_value_i(VALUE key, VALUE value, VALUE _) * 1 * 2 * - * Returns an \Enumerator if no block given: + * Returns a new \Enumerator if no block given: * h = {foo: 0, bar: 1, baz: 2} * e = h.each_value # => #0, :bar=>1, :baz=>2}:each_value> * h1 = e.each {|value| puts value } @@ -3059,13 +3058,6 @@ each_value_i(VALUE key, VALUE value, VALUE _) * 0 * 1 * 2 - * - * --- - * - * Raises an exception if the block attempts to add a new key: - * h = {foo: 0, bar: 1, baz: 2} - * # Raises RuntimeError (can't add a new key into hash during iteration): - * h.each_value {|value| h[:new_key] = 3 } */ static VALUE @@ -3096,7 +3088,7 @@ each_key_i(VALUE key, VALUE value, VALUE _) * bar * baz * - * Returns an \Enumerator if no block given: + * Returns a new \Enumerator if no block given: * h = {foo: 0, bar: 1, baz: 2} * e = h.each_key # => #0, :bar=>1, :baz=>2}:each_key> * h1 = e.each {|key| puts key } @@ -3105,13 +3097,6 @@ each_key_i(VALUE key, VALUE value, VALUE _) * foo * bar * baz - * - * --- - * - * Raises an exception if the block attempts to add a new key: - * h = {foo: 0, bar: 1, baz: 2} - * # Raises RuntimeError (can't add a new key into hash during iteration): - * h.each_key {|key| h[:new_key] = 3 } */ static VALUE rb_hash_each_key(VALUE hash) @@ -3145,7 +3130,9 @@ each_pair_i_fast(VALUE key, VALUE value, VALUE _) * hash.each -> new_enumerator * hash.each_pair -> new_enumerator * - * Calls the given block with each key-value pair, returning +self+: + * Hash#each is an alias for Hash#each_pair. + + * Calls the given block with each key-value pair; returns +self+: * h = {foo: 0, bar: 1, baz: 2} * h.each_pair {|key, value| puts "#{key}: #{value}"} # => {:foo=>0, :bar=>1, :baz=>2} * Output: @@ -3153,7 +3140,7 @@ each_pair_i_fast(VALUE key, VALUE value, VALUE _) * bar: 1 * baz: 2 * - * Returns an \Enumerator if no block given: + * Returns a new \Enumerator if no block given: * h = {foo: 0, bar: 1, baz: 2} * e = h.each_pair # => #0, :bar=>1, :baz=>2}:each_pair> * h1 = e.each {|key, value| puts "#{key}: #{value}"} @@ -3162,13 +3149,6 @@ each_pair_i_fast(VALUE key, VALUE value, VALUE _) * foo: 0 * bar: 1 * baz: 2 - * - * --- - * - * Raises an exception if the block attempts to add a new key: - * h = {foo: 0, bar: 1, baz: 2} - * # Raises RuntimeError (can't add a new key into hash during iteration) - * h.each_pair {|key, value| h[:new_key] = 3 } */ static VALUE @@ -3236,13 +3216,6 @@ transform_keys_i(VALUE key, VALUE value, VALUE result) * e = h.transform_keys # => #0, :bar=>1, :baz=>2}:transform_keys> * h1 = e.each { |key| key.to_s } * h1 # => {"foo"=>0, "bar"=>1, "baz"=>2} - * - * --- - * - * Raises an exception if the block attempts to add a new key: - * h = {foo: 0, bar: 1, baz: 2} - * # Raises RuntimeError (can't add a new key into hash during iteration) - * h.transform_keys {|key| h[:new_key] = 3 } */ static VALUE rb_hash_transform_keys(int argc, VALUE *argv, VALUE hash) @@ -3288,11 +3261,6 @@ static VALUE rb_hash_flatten(int argc, VALUE *argv, VALUE hash); * h1 = h.transform_keys! {|key| :bat } * h1 # => {:bat=>2} * - * Allows the block to add a new entry: - * h = {foo: 0, bar: 1, baz: 2} - * h1 = h.transform_keys! {|key| h[:new_key] = key.to_s } - * h1 # => {:new_key=>"baz", "foo"=>0, "bar"=>1, "baz"=>2} - * * Returns a new \Enumerator if no block given: * h = {foo: 0, bar: 1, baz: 2} * e = h.transform_keys! # => #0, "bar"=>1, "baz"=>2}:transform_keys!> @@ -3369,11 +3337,6 @@ transform_values_foreach_replace(st_data_t *key, st_data_t *value, st_data_t arg * h1 = h.transform_values {|value| value * 100} * h1 # => {:foo=>0, :bar=>100, :baz=>200} * - * Ignores an attempt in the block to add a new key: - * h = {foo: 0, bar: 1, baz: 2} - * h1 = h.transform_values {|value| h[:new_key] = 3; value * 100 } - * h1 # => {:foo=>0, :bar=>100, :baz=>200} - * * Returns a new \Enumerator if no block given: * h = {foo: 0, bar: 1, baz: 2} * e = h.transform_values # => #0, :bar=>1, :baz=>2}:transform_values> @@ -3404,11 +3367,6 @@ rb_hash_transform_values(VALUE hash) * h = {foo: 0, bar: 1, baz: 2} * h.transform_values! {|value| value * 100} # => {:foo=>0, :bar=>100, :baz=>200} * - * Allows the block to add a new entry: - * h = {foo: 0, bar: 1, baz: 2} - * h1 = h.transform_values! {|value| h[:new_key] = 3; value * 100 } - * h1 # => {:foo=>0, :bar=>100, :baz=>200, :new_key=>3} - * * Returns a new \Enumerator if no block given: * h = {foo: 0, bar: 1, baz: 2} * e = h.transform_values! # => #0, :bar=>100, :baz=>200}:transform_values!> -- cgit v1.2.3