Merge branch 'master' of github.com:lifo/docrails

1 files changed, 53 insertions, 0 deletions

diff --git a/guides/source/active_support_core_extensions.textile b/guides/source/active_support_core_extensions.textile
index 80faffa49c..587f65529e 100644
--- a/guides/source/active_support_core_extensions.textile
+++ b/guides/source/active_support_core_extensions.textile
@@ -2549,6 +2549,45 @@ There's also the bang variant +except!+ that removes keys in the very receiver.
 
 NOTE: Defined in +active_support/core_ext/hash/except.rb+.
 
+h5. +transform_keys+ and +transform_keys!+
+
+The method +transform_keys+ accepts a block and returns a hash that has applied the block operations to each of the keys in the receiver:
+
+<ruby>
+{nil => nil, 1 => 1, :a => :a}.transform_keys{ |key| key.to_s.upcase }
+# => {"" => nil, "A" => :a, "1" => 1}
+</ruby>
+
+The result in case of collision is undefined:
+
+<ruby>
+{"a" => 1, :a => 2}.transform_keys{ |key| key.to_s.upcase }
+# => {"A" => 2}, in my test, can't rely on this result though
+</ruby>
+
+This method may be useful for example to build specialized conversions. For instance +stringify_keys+ and +symbolize_keys+ use +transform_keys+ to perform their key conversions:
+
+<ruby>
+def stringify_keys
+  transform_keys{ |key| key.to_s }
+end
+...
+def symbolize_keys
+  transform_keys{ |key| key.to_sym rescue key }
+end
+</ruby>
+
+There's also the bang variant +transform_keys!+ that applies the block operations to keys in the very receiver.
+
+Besides that, one can use +deep_transform_keys+ and +deep_transform_keys!+ to perform the block operation on all the keys in the given hash and all the hashes nested into it. An example of the result is:
+
+<ruby>
+{nil => nil, 1 => 1, :nested => {:a => 3, 5 => 5}}.deep_transform_keys{ |key| key.to_s.upcase }
+# => {""=>nil, "1"=>1, "NESTED"=>{"A"=>3, "5"=>5}}
+</ruby>
+
+NOTE: Defined in +active_support/core_ext/hash/keys.rb+.
+
 h5. +stringify_keys+ and +stringify_keys!+
 
 The method +stringify_keys+ returns a hash that has a stringified version of the keys in the receiver. It does so by sending +to_s+ to them:
@@ -2579,6 +2618,13 @@ The second line can safely access the "type" key, and let the user to pass eithe
 
 There's also the bang variant +stringify_keys!+ that stringifies keys in the very receiver.
 
+Besides that, one can use +deep_stringify_keys+ and +deep_stringify_keys!+ to stringify all the keys in the given hash and all the hashes nested into it. An example of the result is:
+
+<ruby>
+{nil => nil, 1 => 1, :nested => {:a => 3, 5 => 5}}.deep_stringify_keys
+# => {""=>nil, "1"=>1, "nested"=>{"a"=>3, "5"=>5}}
+</ruby>
+
 NOTE: Defined in +active_support/core_ext/hash/keys.rb+.
 
 h5. +symbolize_keys+ and +symbolize_keys!+
@@ -2613,6 +2659,13 @@ The second line can safely access the +:params+ key, and let the user to pass ei
 
 There's also the bang variant +symbolize_keys!+ that symbolizes keys in the very receiver.
 
+Besides that, one can use +deep_symbolize_keys+ and +deep_symbolize_keys!+ to symbolize all the keys in the given hash and all the hashes nested into it. An example of the result is:
+
+<ruby>
+{nil => nil, 1 => 1, "nested" => {"a" => 3, 5 => 5}}.deep_symbolize_keys
+# => {nil=>nil, 1=>1, :nested=>{:a=>3, 5=>5}}
+</ruby>
+
 NOTE: Defined in +active_support/core_ext/hash/keys.rb+.
 
 h5. +to_options+ and +to_options!+