dotnet / dotnet/dotnet-api-docs

Document differences in Single/Double behavior from IEEE spec

Open
#3,509 4 comments 2 reactions 0 assignees View on GitHub
area-System.Numerics doc-enhancement Pri3
Dominant language
C#
Stars
949
Forks
1.7k
Avg merge
3d 27m
Merged PRs (30d)
49

Description

https://docs.microsoft.com/en-us/dotnet/api/system.double?view=netframework-4.8 currently says:

> The Double type complies with the IEC 60559:1989 (IEEE 754) standard for binary floating-point arithmetic.

It would be good to point out the major breaks in spec, hopefully specifying them directly around that sentence (from a quick read, that page doesn't mention any at all).

In particular, I know of two cases:

* `double.NaN.Equals(double.NaN)` is true. (`double.NaN == double.NaN` is false, which is the IEEE spec for standard equality)
* `x % y` is not the IEEE remainder operation (maybe also point out in the docs that `Math.IEEERemainder` exists if you want that operation)

All the above also applies for `float`/`System.Single`.

(To be clear and avoid misinterpretation, this is _not_ a request for changing behavior, I know that these behaviors cannot be changed due to _huge_ backcompat issues, I'm only asking for these edge cases to be documented)

(Ping @tannergooding, as follow-up from [our thread on twitter](https://twitter.com/tannergooding/status/1196307853566283776))

Thanks!

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.