specify that Iterators.rest must be given a valid state

[adienes]

currently Iterators.rest(1:2, 3) creates an infinite loop. after this PR it would be an ArgumentError

docs only now

[KristofferC]

Tangentially, but it is kind of ugly how this wants an explicit state passed in (and how the docstring uses the function). I don't think the value of the state has any meaning outside how it should be used in the iteration protocol, or?

[adienes]

I agree, and as far as I can see it's the only iterator with an API like that. I guess it's to draw a distinction with Iterators.drop

but anyway that's probably not changeable, so I just wanted to make it harder to hit infinite loops

[KristofferC]

Maybe it is worth adding to the docstring that you should have received that state from an iterate call (and update the example)?

[adienes]

is the fact that rest(1:4, 6) errors but rest([1,2,3,4], 6) does not acceptable? per the docstring, this is an illegal state so the output is undefined (not in the fancy sense, just that the semantics are not specified).

but pretty much any implementation of _iteratorstate_invalid will contain false negatives as it is simply impossible in the general case to query if an iteration state is valid

[mbauman]

Maybe it is worth adding to the docstring that you should have received that state from an iterate call (and update the example)?

This is the way. But stronger: s/should/must/.

It's not really different from iterate(1:0, 1000) itself. If you give that something that's not actually a state from iterate, you may have a bad time. The point of rest is to allow you to swap back from a manual sequence of iterates to a for loop or to pass to another iterator function.

I honestly don't think it's worth trying to protect against this case, particularly because ::OrdinalRanges can (and do!) define their own iterate methods and may use different meaning for their own state. So this is worse than incomplete: it isn't correct.

Ideally, iterators would always return nothing or error for invalid states. But not all do, and it's not a promise we make.

[adienes]

ok, fair enough. I've amended the PR to just make the docstring a bit more emphatic about the state validity then

[mbauman]

I can't quite reach into the example to suggest a change there, but let's also have that example use a state it got from val, state = iterate([1,2,3,4])