Please Expose "breaker"

[machineghost]

Unlike jQuery's $.each, Underscore has the good sense to give the passed-in callback the value first, followed by the key/index. This alone makes Underscore's _.each superior ... except for one minor detail.

Unlike just about every other for/each loop in existence (the JS native one, the jQuery one, etc.) Underscore's _.each does not have a way to explicitly break out of the loop. Actually, that's not technically correct: it does have just such a mechanism (the "breaker" variable), but the library selfishly reserves it for use by other Underscore functions only.

It doesn't have to be this way; if breaker was simply exposed as a property of the underscore object, then everyone could use the wonderful _.each function without any negative trade-offs. Imagine:

_.each([1,2,3], function(x) {
    if (x == 2) return _.breaker; // or _.BREAKER?
    console.log(x);
});
1

and all that would require is a single line of code to export breaker (actually not even that: just change "var breaker" to "_.breaker", move it down a few lines below the declaration of "var _" and call it a day).

[samuelclay]

In my experience, if you want to use a breaker, you might be able to get away with doing a _.filter first, or just using _.any, _.detect, or _.filter to grab what you want from the array.

[braddunbar]

Hey @machineghost! This was previously discussed in #211. _.each uses the native forEach when available and breaker has no effect on it. Using _.filter or a for loop are much better options here.

[domenic]

Not very intention-revealing, but you can use _.any and then return true to break:

_.any([1, 2, 3], function (x) {
    if (x === 2) { return true; }
    console.log(x);
});

This of course works in native JS too:

[1, 2, 3].some(function (x) { /* as before */ });

[jashkenas]

FWIW -- this is the ECMAScript-committee-approved way to stop early ... it's simply not supported in the native forEach.

[paulmillr]

The thing is — they're functional programming functions and functional programming strongly discourages breaks, continues etc. Of course breaks can be emulated with foldr though.

[machineghost]

Ok, that all makes sense, but it still leaves Underscore users without a way to break. What about a _.BreakException? This seems to be the accepted pattern for breaking out of the native forEach, and it works perfectly well with the simulated forEachs also.

Basically, if you want to break inside a _.each loop, you just throw new _.BreakException(). Then, inside underscore's _.each code, you'd just have to wrap the forEach loop section (the whole if block with both the native one and the two simulated ones) with a try/catch that breaks out of the loop (but does nothing else) if it catches a _.BreakException, and then throws any other exception caught. Something like

_.BreakException = function(message) {this.message = message};
var each = _.each = _.forEach = function(obj, iterator, context) {
    if (obj == null) return;
    try {
        if (nativeForEach && obj.forEach === nativeForEach) {
          obj.forEach(iterator, context);
        } else if (obj.length === +obj.length) {
          for (var i = 0, l = obj.length; i < l; i++) {
            if (i in obj && iterator.call(context, obj[i], i, obj) === breaker) return;
          }
        } else {
          for (var key in obj) {
            if (_.has(obj, key)) {
              if (iterator.call(context, obj[key], key, obj) === breaker) return;
            }
          }
        }
    } catch(e) {
        if (e instanceof _.BreakException) return;
        throw new Error(e);
    }
};

and then to use it:

_.each([1,2,3], function(num) {
    if (num == 2) throw new _.BreakException();
    console.log(num);
});
// Logs "1"

[jashkenas]

Nope. Just use _.any, and return true.

[machineghost]

"Nope"
If it's not too much trouble, could you please explain your reasoning? This doesn't seem like a real solution to me because there's no reason why any user who wants to break out of a _.each loop would know to return true from (or even to use in the first place) an _.any call.

Therefore, unless you update the documentation to say something like "_.each isn't really what you're looking for; if you want the real each loop use _.any" (which would, obviously, be kinda dumb) you're basically saying you won't provide a very useful feature to Underscore for no reason. There's a reason why every other library's each (and the basic JS for and for/each) has a break mechanism; it's a useful thing to have. Why make Underscore inferior for no reason?

[samuelclay]

@machineghost: It's not that it wouldn't be nice-to-have, it's that there are two implementations of _.each: 1) the one you see in Underscore.js, and 2) the native implementation that Underscore uses if available. That native implementation does not allow you to use a breaker. Although I believe @jashkenas mentioned above that the ECMAscript spec says that it should.

[iamnoah]

If you prefer false as a breaker :P

_.extend({
    breakableEach: _.all
});

and return false to break.

[jashkenas]

@machineghost -- It's been discussed more in previous tickets if you feel like doing some archaeology.

We don't want to expose breaker, because without wrapping the native forEach in an additional function, with a try/catch, there's no way of catching it. Throwing breaker would cause the loop to stop in IE, and in modern browsers, it would raise an exception. Not exactly what you want.

This issue has been raised with the TC39 folks who spec'd forEach originally, and their response is (paraphrasing): "If you want to end the loop early, use any". We're respecting that.

[machineghost]

First off, I appreciate everyone's explanations; thanks for taking the time to explain things.

@samuelclay Right, but you're ignoring the possibility of a throw-based break system, which would work with both Underscore's custom each and the built-in each.

@iamnoah I don't think that adding a breakableEach to Underscore is a bad idea, but it does seem unnecessary to me when the normal each can handle breaking just fine (via a special exception).

@ashkenas

Throwing breaker would cause the loop to stop in IE, and in modern browsers, it would raise an exception.
Not exactly what you want.

Actually, stopping the loop is exactly what I'd want; that's sort of what "break" is supposed to do ;-)

As for modern browsers, if Underscore catches the exception (which is what I proposed/what my sample code does) then everything works perfectly:

1. You start a loop via _.each
2. If you don't want to break, everything works normally
3. If you want to break, you throw a new _.BREAK_EXCEPTION() inside your function
4. Regardless of whether Underscore was using the built-in each or its own, that exception is going to come out and get caught by the (imaginary future) _.each code, effectively breaking the loop.

Now, if by "stop in IE" you mean it freezes the browser or something, or if there's some sort of noticeable performance penalty to adding a try/catch, or something like that, that's one thing; I'm not trying to make Underscore worse. But if not, exception-based breaking is a win all-around; existing code isn't affected, but anyone who wants a breaking mechanism gets one.

This issue has been raised with the TC39 folks who spec'd forEach originally, and their response is (paraphrasing):
"If you want to end the loop early, use any". We're respecting that.

So I thought Underscore was more than just a bridge to the latest Javascript; I thought it was trying to augment core Javascript. If that's true, then what matters isn't what the core JS devs want, it's what Underscore users want that matters. And if this has come up before, then isn't that a clear sign that people want to be able to break?

Also, I don't see what you're talking about with TC39 being anti-break; I'm looking at the "ECMA-262 5th edit" spec (which Wikipedia suggests is the final product of TC39) and it includes specific instructions regarding breaks in forEach (eg. "If s.type is break and s.target is in the current label set, return (normal, V, empty)").

So my point is, Underscore should do whatever makes Underscore a better library. If adding a try/catch to allow breaking would make it a worse library, then it's a terrible idea and I'm sorry for wasting your time. But if not, if the only objection is "someone else chose not to" ... that seems unfortunate to me. Why make a library worse just because someone else made a bad call?

[samuelclay]

If adding a try/catch to allow breaking would make it a worse library, then it's a terrible idea

Easiest way to find out is to perf test it at http://jsperf.com. I have a feeling that exception catching is noticeably slower. Also, you should supply a test case that cannot easily be re-written using _.any and a side-effect.

[machineghost]

Thanks for the link Sam, but unfortunately I haven't had time to make a set of try/catch performance tests. However, I found this:
http://jsperf.com/try-catch-performance-overhead
which is far more comprehensive than anything I'd ever do (plus, it uses for loops setting variables to do its metric-ing, which is perfect for this case) ... and it does look like there's enough of a performance penalty in some browsers that the try/catch loop would actually matter.

I still think a _.breakableEach option might be a nice addition to the library, but until enough other people request to justify adding it, I guess I'll just stick to $.each (or either of the built-in for loops, or Mochikit's each, or ...) when I need a breakable each.

Thanks all for taking the time to explain things; it really is so much nicer to use a library when you feel like features are denied for a good reason, as opposed to just an arbitrary whim :-)