Add note on BigInteger bin/hex formatting of positive values

[SolalPirelli]

Summary

Fixes dotnet/runtime#115618.

It's somewhat unexpected that "print 3 with 2 binary digits" returns a string of length 3 ("011"), but also makes sense given the round-trip requirement and the historical context of not using - for negative bin/hex numbers.

I think documenting this behavior would be useful.

---

Internal previews

📄 File	🔗 Preview link
docs/standard/base-types/parsing-numeric.md	Parsing numeric strings in .NET
docs/standard/base-types/standard-numeric-format-strings.md	Standard numeric format strings

[tannergooding]

It might be worth clarifying that 11 is interpreted as a signed two's complement value that is 2-bits wide. Thus 1, 11, 111, 1111, etc are all interpreted as -1. This allows BigInteger to always use the shortest roundtrippable string when formatting and to support inputs from any smaller signed type without loss of data.

This is different from int.Parse and similar, where:

sbyte x = -1;
int y = int.Parse(x.ToString("B")); // 255

Which is due to them having a fixed number of bits and so interpreting any unspecified bits as being 0

[adegeo]

@tannergooding Thank you for breaking my brain. How does this sound?

Suggested change

	For instance, the number `3` converted with the format specifier `"B2"` is `011` because the binary number `11` represents the negative value `-1`.
	For instance, the number `3` converted with the format specifier `"B2"` is `011` because the binary number `11` represents the negative value `-1`. Negative numbers are interpreted as a signed two's complement value that's 2-bits wide. This allows <xref:System.Numerics.BigInteger> to always use the shortest round-trippable string when formatting, especially with smaller negative numbers.

[SolalPirelli]

Given that the 2 here is just an example, maybe:

Suggested change

	For instance, the number `3` converted with the format specifier `"B2"` is `011` because the binary number `11` represents the negative value `-1`.
	For instance, the number `3` converted with the format specifier `"B2"` is `011`. That's because the binary number `11` represents the negative value `-1`, as it is interpreted as a number with exactly `2` bits due to the `"B2"` format.

(I've been thinking about something of the form "it's like intN.Parse if you had an intN type", but adding one extra concept C# doesn't actually have to understand BigIntege is probably not a great idea)

[tannergooding]

Right, it's that the input is always treated as a signed 2's complement number with the least number of required bits.

This is why 1, 11, and 11...1 are all going to produce -1. You therefore need a leading zero for positive numbers and need to consider that a string with n-digits will be treated as some IntN for the purposes of parsing.

[adegeo]

I do think it's important to point out the shorter round trip, because if you used int you get a giant 111111111111111 or whatever it is returned, unlike BigInteger which has the shorter 11.

Also, in the docs line breaks don't render unless you have two consecutive line breaks to form a new paragraph, so please make sure you remove those needless line breaks 😄

[SolalPirelli]

Done. (See also the other comment thread re: roundtripping, I updated the parsing docs as well)

[SolalPirelli]

@dotnet-policy-service agree