AS guide: documents Hash#except

1 files changed, 23 insertions, 0 deletions

diff --git a/railties/guides/source/active_support_overview.textile b/railties/guides/source/active_support_overview.textile
index 5723fbffa2..392640d239 100644
--- a/railties/guides/source/active_support_overview.textile
+++ b/railties/guides/source/active_support_overview.textile
@@ -1166,6 +1166,29 @@ hash1.diff(hash2).diff(hash2) == hash1
 
 Diffing hashes may be useful for error messages related to expected option hashes for example.
 
+h4. Removing Keys
+
+The method +except+ returns a hash with the keys in the argument list removed, if present:
+
+<ruby>
+{:a => 1, :b => 2}.except(:a) # => {:b => 2}
+</ruby>
+
+If the receiver responds to +convert_key+, the method is called on each of the arguments. This allows +except+ to play nice with hashes with indifferent access for instance:
+
+<ruby>
+{:a => 1}.with_indifferent_access.except(:a)  # => {}
+{:a => 1}.with_indifferent_access.except("a") # => {}
+</ruby>
+
+The method +except+ may come in handy for example when you want to protect some parameter that can't be globally protected with +attr_protected+:
+
+<ruby>
+params[:account] = params[:account].except(:plan_id) unless admin?
+@account.update_attributes(params[:account])
+</ruby>
+
+There's also the bang variant +except!+ that removes keys in the very receiver.
 
 h3. Extensions to +Range+