modify Base.peek to return a Char and export it

[StefanKarpinski]

The peek function is very useful and an efficient alternative to marking and resetting a stream when all you need to do is get a single character. The current peek returns a byte, however, which leads to errors when people assume that they can compare that byte to a character and check for a character (only works for UTF-8 streams and ASCII characters). This was a significant annoyance in implementing #16024. This is technically not breaking since Base.peek isn't exported. Most code that uses it will actually continue to work.

[quinnj]

we should make this match the read API, so:

read(io, UInt8)
read(io, Char)

peek(io, UInt8)
peek(io, Char)

[vtjnash]

duplicate of #2638 [decision: no]

[StefanKarpinski]

The mark/reset API is good but it's very high overhead for just looking at a single character, which requires only a fixed amount of lookahead. The fact that we still use peek in a lot of places in Base indicates that peek is necessary and should work correctly, rather than continue to exist and be broken and non-public.

[StefanKarpinski]

This could probably be closed just by renaming peekchar to peek and renaming peek to peekbyte. Since both are unexported, we could potentially just do the rename.

[StefanKarpinski]

Or we could just do what @quinnj recommends and make peek match read.

[StefanKarpinski]

Actually, even better: we can support generic peek(io, T) implemented with mark, read and reset but with more efficient methods when T is UInt8 or Char.

[KristofferC]

#28811