From 848bdaaa222603c9efefc7b7a22e35ddc25a0f0f Mon Sep 17 00:00:00 2001
From: Xavier Noria <fxn@hashref.com>
Date: Sat, 12 Sep 2009 13:25:06 +0200
Subject: AS guide: documents Hash#diff

---
 .../guides/source/active_support_overview.textile  | 36 ++++++++++++++++++++++
 1 file changed, 36 insertions(+)

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+
 
-- 
cgit v1.2.3