yeah, but next() is optional and not used by foreach

There's no indication that next() is optional. At the very least, the documentation is somewhat lacking, if for no other reason than the api including two parallel sets of functions for interacting with the iterator, one of which is relatively more "standard" than the other without stating clearly which functions are actually used. I think most people who have used other languages with iterators will feel more comfortable with ->next() and friends, and be confused that they're not actually used. I know I was, and I'm probably not alone.

and += returns the iterator itself, so you can't return UNDEFINED there. since += never fails the only option is to test wether you still have an item there or not, and then ! is a good choice for that test.

Well, you can very easily return undefined from `+=(), and it doesn't make any difference. That, at the very least, should have prompted an error, but instead, it kept right on running. I'm not sure that the semantics of this are appropriate, as the side effect is important (or should be, even if you're always supposed to return this_object() from `+=()).

it would be different if next() where the standard way of advancing the iterator.

Well, it is the "standard" way, [by "standard", I mean the pattern employed by C++, Java, Objective-C, etc] Pike just happens to use operator overloading instead.

Anyhow, my problem is solved. If I find time, I may update the documentation to be a little more clear about what's required and what's optional.

Bill