Clarify that System.Decimal is not IEEE-754 compliant in documentation
- Dominant language
- No language data
- Stars
- 4.8k
- Forks
- 6.1k
- Avg merge
- 19h 10m
- Merged PRs (30d)
- 268
Description
**Issue description**
Neither [the reference docs](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/floating-point-numeric-types) or the [decimal docs](https://learn.microsoft.com/en-us/dotnet/api/system.decimal) point out that the `decimal` type is not a `binary128` or `decimal128` value despite being listed among binary32 and binary64 values.
This is evident when we look at the representation of 1.0 in different 128-bit floating point formats (in little endian.)
- binary128: `0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xFF, 0x3F`
- decimal128: `0x1, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x08, 0x22`
- Decimal (GetBits): `0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00`
- Decimal (Memory): `0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00`
Note that the last 2 bytes of decimal128 are different. Parsing the decimal128 value into System.Decimal either through GetBits or Memory casting will fail the IsValid() check (indicating it's not a Win32 DECIMAL.)
Since decimal128 and binary128 are standardized in the 2008 revision of the IEEE-754 format, this can lead to confusion when referring to decimal128 values (as System.Decimal is not an IEEE decimal float despite being a decimal floating point value.)
---
#### Document Details
⚠ *Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.*
* ID: b24345d9-7aec-14ad-8c3c-56410267849a
* Version Independent ID: f83555d8-9dac-5019-3345-bb0f03e1311d
* Content: [Floating-point numeric types - C# reference](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/floating-point-numeric-types)
* Content Source: [docs/csharp/language-reference/builtin-types/floating-point-numeric-types.md](https://github.com/dotnet/docs/blob/main/docs/csharp/language-reference/builtin-types/floating-point-numeric-types.md)
* Product: **dotnet-csharp**
* Technology: **csharp-language-reference**
* GitHub Login: @BillWagner
* Microsoft Alias: **wiwagn**
Contributor guide
Assessment
This issue has not been assessed yet.