Adding groupBy.

index.html

@@ -141,7 +141,7 @@ <h2>Table of Contents</h2>
       <a href="#any">any</a>, <a href="#include">include</a>,
       <a href="#invoke">invoke</a>, <a href="#pluck">pluck</a>,
       <a href="#max">max</a>, <a href="#min">min</a>,
-      <a href="#sortBy">sortBy</a>, <a href="#sortedIndex">sortedIndex</a>,
+      <a href="#sortBy">sortBy</a>, <a href="#groupBy">groupBy</a>, <a href="#sortedIndex">sortedIndex</a>,
       <a href="#toArray">toArray</a>, <a href="#size">size</a></span>
     </p>
 
@@ -437,6 +437,17 @@ <h2>Collection Functions (Arrays or Objects)</h2>
       <pre>
 _.sortBy([1, 2, 3, 4, 5, 6], function(num){ return Math.sin(num); });
 =&gt; [5, 4, 6, 3, 1, 2]
+</pre>
+
+      <p id="groupBy">
+        <b class="header">groupBy</b><code>_.groupBy(list, iterator)</code>
+        <br />
+        Splits a collection into sets, grouped by the result of running each
+        value through <b>iterator</b>.
+      </p>
+      <pre>
+_.groupBy([1.3, 2.1, 2.4], function(num){ return Math.floor(num); });
+=&gt; {1: [1.3], 2: [2.1, 2.4]}
 </pre>
 
       <p id="sortedIndex">

test/collections.js

@@ -185,6 +185,12 @@ $(document).ready(function() {
     people = _.sortBy(people, function(person){ return person.age; });
     equals(_.pluck(people, 'name').join(', '), 'moe, curly', 'stooges sorted by age');
   });
+
+  test('collections: groupBy', function() {
+    var parity = _.groupBy([1, 2, 3, 4, 5, 6], function(num){ return num % 2; });
+    equals(_.keys(parity).join(', '), '0, 1', 'created a group for each value');
+    equals(parity[0].join(', '), '2, 4, 6', 'put each even number in the right group');
+  })
 
   test('collections: sortedIndex', function() {
     var numbers = [10, 20, 30, 40, 50], num = 35;

underscore.js

@@ -250,6 +250,21 @@
       return a < b ? -1 : a > b ? 1 : 0;
     }), 'value');
   };
+
+  // Groups the object's values by a criterion produced by an iterator
+  _.groupBy = function(obj, iterator) {
+    var result = {};
+    each(obj, function(value) {
+      var key = iterator(value);
+      if (result.hasOwnProperty(key)) {
+        result[key].push(value);
+      }
+      else {
+        result[key] = [value];
+      }
+    });
+    return result;
+  }
 
   // Use a comparator function to figure out at what index an object should
   // be inserted so as to maintain order. Uses binary search.