From 3ed6b3a8b310598b391d004514ee72c58171d637 Mon Sep 17 00:00:00 2001
From: Xavier Noria <fxn@hashref.com>
Date: Mon, 21 Sep 2009 23:27:48 +0200
Subject: AS guide: documents Enumerable#each_with_object

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

(limited to 'railties/guides')

diff --git a/railties/guides/source/active_support_overview.textile b/railties/guides/source/active_support_overview.textile
index 48faf260c7..d09b8cde88 100644
--- a/railties/guides/source/active_support_overview.textile
+++ b/railties/guides/source/active_support_overview.textile
@@ -847,6 +847,30 @@ def observed_subclasses
 end
 </ruby>
 
+h4. +each_with_object+
+
+The +inject+ method offers iteration with an accumulator:
+
+<ruby>
+[2, 3, 4].inject(1) {|acc, i| product*i } # => 24
+</ruby>
+
+The block is expected to return the value for the accumulator in the next iteration, and this makes building mutable objects a bit cumbersome:
+
+<ruby>
+[1, 2].inject({}) {|h, i| h[i] = i**2; h} # => {1 => 1, 2 => 4}
+</ruby>
+
+See that spurious "+; h+"?
+
+Active Support backports +each_with_object+ from Ruby 1.9, which addresses that use case. It iterates over the collection, passes the accumulator, and returns the accumulator when done. You normally modify the accumulator in place. The example above would be written this way:
+
+<ruby>
+[1, 2].each_with_object({}) {|i, h| h[i] = i**2} # => {1 => 1, 2 => 4}
+</ruby>
+
+WARNING. Note that the item of the collection and the accumulator come in different order in +inject+ and +each_with_object+.
+
 h3. Extensions to +Array+
 
 h4. Accessing
-- 
cgit v1.2.3