* hash.c (rb_hash_update): Documentation for Hash#merge and shallow

  copies Patch by Yorick Peterse [Fixes Github #228]


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@38672 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 18 insertions, 5 deletions

diff --git a/hash.c b/hash.c
index 34fbbf7035..976a57ee0d 100644
--- a/hash.c
+++ b/hash.c
@@ -1879,11 +1879,11 @@ rb_hash_update_block_i(VALUE key, VALUE value, VALUE hash)
  *     hsh.merge!(other_hash){|key, oldval, newval| block}    -> hsh
  *     hsh.update(other_hash){|key, oldval, newval| block}    -> hsh
  *
- *  Adds the contents of <i>other_hash</i> to <i>hsh</i>.  If no
- *  block is specified, entries with duplicate keys are overwritten
- *  with the values from <i>other_hash</i>, otherwise the value
- *  of each duplicate key is determined by calling the block with
- *  the key, its value in <i>hsh</i> and its value in <i>other_hash</i>.
+ *  Adds the contents of _other_hash_ to _hsh_.  If no block is specified,
+ *  entries with duplicate keys are overwritten with the values from
+ *  _other_hash_, otherwise the value of each duplicate key is determined by
+ *  calling the block with the key, its value in _hsh_ and its value in
+ *  _other_hash_.
  *
  *     h1 = { "a" => 100, "b" => 200 }
  *     h2 = { "b" => 254, "c" => 300 }
@@ -1893,6 +1893,19 @@ rb_hash_update_block_i(VALUE key, VALUE value, VALUE hash)
  *     h2 = { "b" => 254, "c" => 300 }
  *     h1.merge!(h2) { |key, v1, v2| v1 }
  *                     #=> {"a"=>100, "b"=>200, "c"=>300}
+ *
+ *  Note that this method creates a shallow copy of the value in _other_hash_.
+ *  This means that when for example Array#select! is used on one of the values
+ *  in _other_hash_ both the original object as well as the copy will be
+ *  modified. This is illustrated in the following example:
+ *
+ *    original = { "numbers" => [10, 20, 30] }
+ *    copy     = {}.merge(original)
+ *
+ *    copy["numbers"].select! { |number| number <= 20 }
+ *
+ *    puts copy     # => { "numbers" => [10, 20] }
+ *    puts original # => { "numbers" => [10, 20] }
  */
 
 static VALUE