AS guide: documents Hash#diff

1 files changed, 36 insertions, 0 deletions

diff --git a/railties/guides/source/active_support_overview.textile b/railties/guides/source/active_support_overview.textile
index ce548f28d2..5723fbffa2 100644
--- a/railties/guides/source/active_support_overview.textile
+++ b/railties/guides/source/active_support_overview.textile
@@ -1130,6 +1130,42 @@ Active Support defines +Hash#deep_merge+. In a deep merge, if a key is found in
 
 The method +deep_merge!+ performs a deep merge in place.
 
+h4. Diffing
+
+The method +diff+ returns a hash that represents a diff of the receiver and the argument with the following logic:
+
+* Pairs +key+, +value+ that exist in both hashes do not belong to the diff hash.
+
+* If both hashes have +key+, but with different values, the pair in the receiver wins.
+
+* The rest is just merged.
+
+<ruby>
+{:a => 1}.diff(:a => 1)
+# => {}, first rule
+
+{:a => 1}.diff(:a => 2)
+# => {:a => 1}, second rule
+
+{:a => 1}.diff(:b => 2)
+# => {:a => 1, :b => 2}, third rule
+
+{:a => 1, :b => 2, :c => 3}.diff(:b => 1, :c => 3, :d => 4)
+# => {:a => 1, :b => 2, :d => 4}, all rules
+
+{}.diff({})        # => {}
+{:a => 1}.diff({}) # => {:a => 1}
+{}.diff(:a => 1)   # => {:a => 1}
+</ruby>
+
+An important property of this diff hash is that you can retrieve the original hash by applying +diff+ twice:
+
+<ruby>
+hash1.diff(hash2).diff(hash2) == hash1
+</ruby>
+
+Diffing hashes may be useful for error messages related to expected option hashes for example.
+
 
 h3. Extensions to +Range+