dotnet / dotnet/docs

Clarify that System.Decimal is not IEEE-754 compliant in documentation

Open
#33,523 1 comment 3 reactions 0 assignees View on GitHub
dotnet-csharp/svc lang-reference/subsvc okr-quality
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.