adding breakLoop

index.html

@@ -202,8 +202,8 @@ _(lyrics).chain()
       <b>Utility</b>
       <br />
       <span class="methods"><a href="#noConflict">noConflict</a>,
-      <a href="#identity">identity</a>, <a href="#uniqueId">uniqueId</a>, 
+      <a href="#identity">identity</a>, <a href="#breakLoop">breakLoop</a></span>,
-      <a href="#template">template</a></span>
+      <a href="#uniqueId">uniqueId</a>, <a href="#template">template</a></span>
     </p>
 
     <p>
@@ -789,7 +789,21 @@ var underscore = _.noConflict();</pre>
       <pre>
 var moe = {name : 'moe'};
 moe === _.identity(moe);
-=> true</pre>
+=&gt; true</pre>
+
+      <p id="breakLoop">
+        <b class="header">breakLoop</b><code>_.breakLoop()</code>
+        <br />
+        Breaks out of the current loop iteration. Similar to the <tt>break</tt>
+        keyword in regular "for" loop, but works within an iterator function.
+      </p>
+      <pre>
+var result = null;
+_.each([1, 2, 3], function(num) { 
+  if ((result = num) == 2) _.breakLoop(); 
+});
+result;
+=&gt; 2</pre>
 
       <p id="uniqueId">
         <b class="header">uniqueId</b><code>_.uniqueId([prefix])</code>

test/utility.js

@@ -15,6 +15,15 @@ $(document).ready(function() {
     equals(_.identity(moe), moe, 'moe is the same as his identity');
   });
   
+  test('utility: breakLoop', function() {
+    var result = null;
+    _([1,2,3,4,5,6]).each(function(num) {
+      result = num;
+      if (num == 3) _.breakLoop();
+    });
+    equals(result, 3, 'broke out of a loop');
+  });
+    
   test("utility: uniqueId", function() {
     var ids = [], i = 0;
     while(i++ < 100) ids.push(_.uniqueId());
@@ -22,7 +31,7 @@ $(document).ready(function() {
   });
   
   test("utility: functions", function() {
-    var expected = ["all", "any", "bind", "bindAll", "clone", "compact", "compose", 
+    var expected = ["all", "any", "bind", "bindAll", "breakLoop", "clone", "compact", "compose", 
     "defer", "delay", "detect", "each", "every", "extend", "filter", "first", 
     "flatten", "foldl", "foldr", "forEach", "functions", "identity", "include", 
     "indexOf", "inject", "intersect", "invoke", "isArray", "isElement", "isEmpty", "isEqual", 

underscore.js

@@ -90,7 +90,7 @@
     _.each(obj, function(value, index, list) {
       if (iterator.call(context, value, index, list)) {
         result = value;
-        throw '__break__';
+        _.breakLoop();
       }
     });
     return result;
@@ -123,7 +123,7 @@
     if (obj.every) return obj.every(iterator, context);
     var result = true;
     _.each(obj, function(value, index, list) {
-      if (!(result = result && iterator.call(context, value, index, list))) throw '__break__';
+      if (!(result = result && iterator.call(context, value, index, list))) _.breakLoop();
     });
     return result;
   };
@@ -135,7 +135,7 @@
     if (obj.some) return obj.some(iterator, context);
     var result = false;
     _.each(obj, function(value, index, list) {
-      if (result = iterator.call(context, value, index, list)) throw '__break__';
+      if (result = iterator.call(context, value, index, list)) _.breakLoop();
     });
     return result;
   };
@@ -146,7 +146,7 @@
     if (_.isArray(obj)) return _.indexOf(obj, target) != -1;
     var found = false;
     _.each(obj, function(value) {
-      if (found = value === target) throw '__break__';
+      if (found = value === target) _.breakLoop();
     });
     return found;
   };
@@ -446,6 +446,11 @@
     return value;
   };
 
+  // Break out of the middle of an iteration.
+  _.breakLoop = function() {
+    throw "__break__";
+  };
+
   // Generate a unique integer id (unique within the entire client session).
   // Useful for temporary DOM ids.
   var idCounter = 0;