I/O peeking

[notcancername]

Introduce:

• std.io.GenericPeeker and std.io.AnyPeeker, interfaces to a peekable stream.
• peeking support in std.io.BufferedReader
• peeking support in std.io.FixedBufferStream

This is intended to be a simple, well-tested, good-enough solution that still provides a rich API and fits well with the existing I/O APIs until they get the rewrite they deserve. It resolves the main issue of PeekStream: its redundancy with BufferedReader, as well as doing more than PeekStream used to provide by supporting similar operations to the Readers and being more flexible by not requiring a buffer and forgoing the ungetc/putBack-style API.

zig/lib/std/io.zig

Lines 373 to 389 in 513b44e

	// Design considerations:
	//
	// - A `getMaximumAvailableBytes` function returning the maximum number of bytes that will be
	// available for peeking. This would remove the need for guesswork and inefficient copies in
	// functions like `peekArrayList`, but also increase the size of `AnyPeeker` if a virtual table
	// approach like in `std.mem.Allocator` is not used. It's unclear whether all peekable streams can
	// support such a function, and it is not necessary for the basic functionality provided by a
	// peekable stream, so it is not yet included.
	// - Having `peekFn` reference an internal buffer. This is more performant, but very bug-prone,
	// *especially* since (`Any`)`Reader` and (`Any`)`Peeker` can be separated. Much like with
	// `SeekableStream`, this makes little sense and adds clunkiness. As before, it's not clear if it
	// can be applied to all peekable streams, and not required.
	// - Instead of the number of bytes fulfilled, `peekFn` could return the number of bytes
	// available. This could be unreliable though, since sometimes, the number of bytes that are
	// avaiable and the number of bytes that could be available are not equal.
	// - Revisit 0 bytes available being an EOF condition.
	// - An `ungetc`-like API is intentionally not provided, to allow for read-only streams.

resolve #4501
previously: #19310 #16114 #4878 #4505
related: #19297