Permalink
Browse files

AS guide: documents Hash#diff

  • Loading branch information...
1 parent d74783e commit 848bdaaa222603c9efefc7b7a22e35ddc25a0f0f @fxn fxn committed Sep 12, 2009
Showing with 36 additions and 0 deletions.
  1. +36 −0 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+

0 comments on commit 848bdaa

Please sign in to comment.