provide a peeking API to std.io.BufferedReader

[andrewrk]

The point of BufferedInStream is to call read() on the underlying stream in bursts, rather than separate calls. E.g. to make 1 syscall to read() reading 999 bytes, rather than 999 syscalls to read() reading 1 byte each.

The point of PeekStream is to be able to "put back" bytes, so that the next call to read() will get them again. In order to accomplish this, PeekStream needs a buffer. That makes PeekStream also a BufferedInStream.

All we need to unify these two APIs is for BufferedInStream to have a parameter called reserved_buffer_space or something like this, and then it's guaranteed to be able to "put back" this many elements.

Related:

• change std.io.BufferedReader and std.io.BufferedWriter to accept the buffer as a runtime parameter, and use AnyReader / AnyWriter #19298