Re: [whatwg/streams] Add ReadableStreamBYOBReader.readFully() (#1145)

I looked at a few other languages to see what their API looks like:
* [Java `java.io.DataInput.readFully`](https://docs.oracle.com/en/java/javase/16/docs/api/java.base/java/io/DataInput.html#readFully(byte%5B%5D))
  * If end of file is detected before filling up to `b.length`, then this throws an `EOFException`. In this case, it may be that some but not all bytes of `b` have been updated with data from the input stream.
* [Rust `std::io::Read::read_exact`](https://doc.rust-lang.org/std/io/trait.Read.html#method.read_exact)
  * If this function encounters an “end of file” before completely filling the buffer, it returns an error of the kind `ErrorKind::UnexpectedEof`. The contents of `buf` are unspecified in this case.
* [.NET `System.IO.Stream.ReadAsync`](https://docs.microsoft.com/en-us/dotnet/api/system.io.stream.readasync?view=net-5.0#System_IO_Stream_ReadAsync_System_Memory_System_Byte__System_Threading_CancellationToken_)
  * Behaves like `ReadableStreamBYOBReader.read(view)`, in that it doesn't necessarily fill the entire buffer. I couldn't find a direct equivalent that does fill up the entire buffer. Even [`BinaryReader.ReadBytes()`](https://docs.microsoft.com/en-us/dotnet/api/system.io.binaryreader.readbytes?view=net-5.0#System_IO_BinaryReader_ReadBytes_System_Int32_) may read less than the requested number of bytes.
  * [`BinaryReader.ReadUint32()`](https://docs.microsoft.com/en-us/dotnet/api/system.io.binaryreader.readuint32?view=net-5.0#System_IO_BinaryReader_ReadUInt32) throws an `EndOfStreamException` if it detects EOF before reading 4 bytes.

It looks like most other languages throw an error if they encounter EOF before completely filling the buffer. That said, the Streams standard already takes a different approach for "regular" reads too: instead of returning the number of bytes read into the given buffer, we transfer the given buffer and return a `{ done, value }` pair with a view on that buffer. So it seems appropriate to align closer with our existing `read(view)` and use the `done` flag to indicate if we encountered EOF earlier. We can also guarantee that the returned view contains all data up to EOF, rather than leaving the buffer contents unspecified.

If we want to bikeshed a bit on the name, here are some ideas:
* `readFully(view)`
* `readExact(view)`

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/streams/pull/1145#issuecomment-884145491