Merge PeekStream and BufferedInStream

[daurnimator]

Child of #4505
Closes #4501

[joachimschmidt557]

I'm very unsure about this, but: Isn't the behaviour of PeekStream.read different from BufferedInStream.read? A PeekStream.read never fills the FIFO, only PeekStream.putBack can do that. But a BufferedInStream does automatically add to the FIFO while reading to speed things up.

Couldn't that create a problem when I try to putBack something and it doesn't work with the merged API because read already filled the FIFO to its limit e.g. when I have a lookahead of exactly 1 byte?

[daurnimator]

I'm very unsure about this, but: Isn't the behaviour of PeekStream.read different from BufferedInStream.read? A PeekStream.read never fills the FIFO, only PeekStream.putBack can do that. But a BufferedInStream does automatically add to the FIFO while reading to speed things up.

Yes.

Couldn't that create a problem when I try to putBack something and it doesn't work with the merged API because read already filled the FIFO to its limit e.g. when I have a lookahead of exactly 1 byte?

Ah, prior experience has made me take something for granted here: in the traditional libc/POSIX ungetc api, you are only allowed to put back what you last read: a subsequent read makes it undefined if you can fit things in or not. I did one-better than the libc API by at least allowing putBack to return an error if it doesn't fit: additionally, if you use a Dynamic buffer, then it will attempt to grow.

[andrewrk]

Can you update this to take into account the use case of being able to do a "put back" operation that is guaranteed to succeed? From the issue that this is trying to solve:

... guaranteed to be able to "put back" this many elements.

[andrewrk]

Feel free to re-open with feedback addressed & rebased. It also sounds like it may be worth discussing on #4501 before implementing, since this takes the accepted proposal in a different direction.