Implement BinaryReader.ReadExactly

[Log234]

This PR implements the BinaryReader.ReadExactly(Span<byte> buffer) method, as proposed in #101614, as well as some new tests to cover the new method.

The BinaryReader source files appear almost not have any tripple slash comments documenting the methods. I would of course be happy to add documentation, but I am unsure if the documentation of these methods is supposed to go somewhere else or if I am supposed to break with the existing "convention" of not documenting these methods.

Fixes #101614

[ghost]

Note regarding the new-api-needs-documentation label:

This serves as a reminder for when your PR is modifying a ref *.cs file and adding/modifying public APIs, please make sure the API implementation in the src *.cs file is documented with triple slash comments, so the PR reviewers can sign off that change.

[ghost]

Note regarding the new-api-needs-documentation label:

This serves as a reminder for when your PR is modifying a ref *.cs file and adding/modifying public APIs, please make sure the API implementation in the src *.cs file is documented with triple slash comments, so the PR reviewers can sign off that change.

[Log234]

@dotnet-policy-bot agree

[adamsitnik]

The PR is almost ready, PTAL at my comments.

@Log234 thank you for your contribution!

[adamsitnik]

nit: AsSpan is needed only for test projects that target older monikers like Full .NET Framework (because Span<T> is not part of mscorlib.dll in Full Framework, so we could not have added an implicit cast operator from array to span for Full Framework).

Suggested change

	var source = new byte[sourceSize].AsSpan();
	byte[] source = new byte[sourceSize];

[Log234]

I see, thanks for the explanation. I have updated the tests to remove the .AsSpan() calls.

[adamsitnik]

The BinaryReader source files appear almost not have any tripple slash comments documenting the methods. I would of course be happy to add documentation, but I am unsure if the documentation of these methods is supposed to go somewhere else or if I am supposed to break with the existing "convention" of not documenting these methods.

Please add the tripple slash comments here. We have an internal porting process where we sporadically run a command line app that feeds the new comments to api docs. Sample outcome: dotnet/dotnet-api-docs#10210

You can use the wording from Stream.ReadExactly as an inspiration.

[Log234]

Thanks for the clarification, I have updated the method with a triple slash comment, based on the Stream.ReadExactly method as you suggested.

[adamsitnik]

LGTM, thank you @Log234 !

BTW dotnet/runtime is currently in a temporary mode where we merge to main only PRs that are a must have for the .NET 9 release. As soon as our main branch becomes .NET 10, I am going to merge your PR and it will be released in .NET 10 Preview 1.

[skyoxZ]

It seems that there's a similar method:

runtime/src/libraries/System.Private.CoreLib/src/System/IO/BinaryReader.cs

Lines 456 to 474 in dcf9814

	private ReadOnlySpan<byte> InternalRead(Span<byte> buffer)
	{
	Debug.Assert(buffer.Length != 1, "length of 1 should use ReadByte.");
	if (_isMemoryStream)
	{
	// read directly from MemoryStream buffer
	Debug.Assert(_stream is MemoryStream);
	return Unsafe.As<MemoryStream>(_stream).InternalReadSpan(buffer.Length);
	}
	else
	{
	ThrowIfDisposed();
	_stream.ReadExactly(buffer);
	return buffer;
	}
	}