[API Proposal]: BinaryReader.ReadExactly

[terrajobst]

Background and motivation

When reading custom binary formats one very often needs a specific number of bytes. The existing Read() method doesn't read a specific number of bytes, it reads as many bytes are currently available. Calling code has to handle this.

We had the same issue on Stream and solved this by exposing Stream.ReadExactly and Stream.ReadAtLeast.

API Proposal

namespace System.IO;

public partial class BinaryReader
{
    public virtual void ReadExactly(Span<byte> buffer);
}

API Usage

BinaryReader binaryReader = GetReader();

Span<byte> guidBytes = (Span<byte>)stackalloc byte[16];
reader.ReadExactly(guidBytes);

Guid guid = new Guid(guidBytes);

Alternative Designs

No response

Risks

No response

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-io
See info in area-owners.md if you want to be subscribed.

[PaulusParssinen]

This would be equivalent to calling ReadExactly(Span<byte>) on the BinaryReader.BaseStream property, right? This method would be much nicer/accessible though.

[terrajobst]

Logically yes, but practically the challenge is that the reader has its own buffer. By passing that would be problematic.

[adamsitnik]

The proposal LGTM, I've marked it as ready for review.

[terrajobst]

Video

• Looks good as proposed

namespace System.IO;

public partial class BinaryReader
{
    public virtual void ReadExactly(Span<byte> buffer);
}

[paulbartrum]

public partial class BinaryReader
{
    public virtual ReadExactly(Span<byte> buffer);
}

The method return type is missing (I'm assuming it should be void?)

[terrajobst]

LOL. Look, I only work here. Fixed.

[adamsitnik]

Logically yes, but practically the challenge is that the reader has its own buffer.

It used to have it's own buffer, after #80331 it does not.

I've marked this issue as "help wanted" and "good first issue" to attract some new contributors (any .NET Team member who whishes to contribute please wait for a PR from community and review it, it's the best way you can help).

The person who wishes to work on this issue should let others know here, so there are no multiple contributors working on the same problem.

Here are some tips that you may find useful:

• here you can find our workflow instructions, the first step is to install everything required to build the product
• to build the clr, libs and tests you need to build following subsets:

.\build.cmd -c Release -subset clr+libs+libs.tests

• the BinaryReader type is included in corelib, not in System.IO.dll: https://github.com/dotnet/runtime/blob/main/src/libraries/System.Private.CoreLib/src/System/IO/BinaryReader.cs
• its tests are in System.IO.Tests: https://github.com/dotnet/runtime/blob/main/src/libraries/System.Runtime/tests/System.IO.Tests/BinaryReader/BinaryReaderTests.cs
• the test projects can access only the public classes and methods that were added to the ref assembly: https://github.com/dotnet/runtime/blob/019d7580a27db97f1fbdcf0d26f7ae3fa54fc2d1/src/libraries/System.Runtime/ref/System.Runtime.cs#L9900
• To rebuild only the corelib (where BinaryReader is) and run the tests you can run following command:

.\build.cmd -c Release -subset clr.corelib+clr.nativecorelib+libs.PreTest && .\dotnet.cmd build -c Release .\src\libraries\System.Runtime\System.Runtime.sln && .\dotnet.cmd build -c Release .\src\libraries\System.Runtime\tests\System.IO.Tests\System.IO.Tests.csproj /t:Test

Good luck!

[Log234]

I would like to attempt providing an implementation for this proposal, if I may have the chance.