PutBack behavior

[casey]

Thank you for itertools!

It's my fault for not reading the documentation for put_back, but I accidentally wrote a bug by putting two items back into an iterator and overwriting the old one.

I might be wrong, but this behavior seems a bit error prone, and might be unexpected.

I would consider renaming PutBack to PutBackOne, and PutBackN to PutBack. Unless the overwriting behavior is desirable, PutBack is essentially a speed/memory optimization when compared to PutBackN, so I would guide users to what is currently PutBackN, and they can then switch to what is currently PutBack as an optimization.

If the overwriting behavior is never desirable, it might be good to make it panic on the second call to put_back in a row. In my case, this would have saved me a bit of debugging time.

[Philippe-Cholet]

I see your point it might be error prone or unexpected (even if the documentation is clear enough).

I see your point about renaming but no other seems to bother this while such change would break everyone.

Panic on the "second call in a row" would be too much of a breaking change as people might be happy with the current behavior and would not have an easy alternative.

I guess the put_back method could return the old value instead of just discarding it as it would at least indicates more what it is doing.
Still a breaking change but it would be reasonable.

[Philippe-Cholet]

@phimuemue Do you think PutBack::put_back should return the old item (instead of discarding it)?

[phimuemue]

@phimuemue Do you think PutBack::put_back should return the old item (instead of discarding it)?

Came to my mind, too, when I first read the question.