Skip to content

Commit 7916e10

Browse files
authored
Add note on BigInteger bin/hex formatting of positive values
See 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.
1 parent 20e230a commit 7916e10

File tree

1 file changed

+6
-0
lines changed

1 file changed

+6
-0
lines changed

docs/standard/base-types/standard-numeric-format-strings.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,9 @@ The binary ("B") format specifier converts a number to a string of binary digits
9898

9999
The precision specifier indicates the minimum number of digits desired in the resulting string. If required, the number is padded with zeros to its left to produce the number of digits given by the precision specifier.
100100

101+
For <xref:System.Numerics.BigInteger>, positive values always have a leading zero to distinguish them from negative values. This ensures the output round-trips to the original value when parsed.
102+
For instance, the number `3` converted with the format specifier `"B2"` is `011` because the binary number `11` represents the negative value `-1`.
103+
101104
The result string is not affected by the formatting information of the current <xref:System.Globalization.NumberFormatInfo> object.
102105

103106
<a name="CFormatString"></a>
@@ -309,6 +312,9 @@ The hexadecimal ("X") format specifier converts a number to a string of hexadeci
309312

310313
The precision specifier indicates the minimum number of digits desired in the resulting string. If required, the number is padded with zeros to its left to produce the number of digits given by the precision specifier.
311314

315+
For <xref:System.Numerics.BigInteger>, positive values always have a leading zero to distinguish them from negative values. This ensures the output round-trips to the original value when parsed.
316+
For instance, the number `F` converted with the format specifier `"X1"` is `0F` because the hexadecimal number `F` represents the negative value `-1`.
317+
312318
The result string is not affected by the formatting information of the current <xref:System.Globalization.NumberFormatInfo> object.
313319

314320
The following example formats <xref:System.Int32> values with the hexadecimal format specifier.

0 commit comments

Comments
 (0)