dotnet / dotnet/dotnet-api-docs
Add explainers to the summaries for Double/Single's IsNormal, IsSubnormal, IsFinite, IsInfinity and IsNegative,; consider adding a shared table to all IEEE-754 functions pages
- Dominant language
- C#
- Stars
- 949
- Forks
- 1.7k
- Avg merge
- 3d 27m
- Merged PRs (30d)
- 49
Description
## `IsNormal` and `IsSubnormal`
[The documentation for `Double.IsNormal`](https://docs.microsoft.com/en-us/dotnet/api/system.double.isnormal) (and [`Single.IsNormal`](https://docs.microsoft.com/en-us/dotnet/api/system.single.isnormal?view=net-6.0)) and related members, is very sparse and _somewhat tautological_ - making it unhelpfully useless for people unfamiliar with the specifics and terminology of IEEE-754.
> **`Double.IsNormal(Double)` Method**
> Determines whether the specified value is normal.
Ditto for [`Double.IsSubnormal`](https://docs.microsoft.com/en-us/dotnet/api/system.single.issubnormal?view=net-6.0):
> **`Double.IsSubnormal(Double)` Method**
> Determines whether the specified value is subnormal.
These `` descriptions should/could be written as:
> **`Double.IsNormal(Double)` Method**
> Determines whether the specified number is a finite, non-zero value, who's internal IEEE-754 base-2 floating-point representation does not have any leading zeroes in its significand (mantissa). This method always returns `false` for `+0`, `-0`, `Epsilon`, `NaN`, `PositiveInfinity`, and `NegativeInfinity`.
> **`Double.IsSubnormal(Double)` Method**
> Determines whether the specified number is a finite, non-zero value, who's internal IEEE-754 base-2 floating-point representation has leading zeroes in its significand (mantissa). This method always returns `true` for `Epsilon`, and always returns `false` for `+0`, `-0`, `NaN`, `PositiveInfinity`, and `NegativeInfinity`.
## `IsNegative`
> [**`Double.IsNegative(Double)` Method**](https://docs.microsoft.com/en-us/dotnet/api/system.double.isnegative?view=net-6.0
)
> Determines whether the specified value is negative.
This description is unhelpful because it doesn't explain why `IsNegative(value)` would be used instead of `value < 0`. There's also a slight _gotcha_ in the case of negative-zero, where `IsNegative( -0f ) == true` but `( -0f < 0 ) == false` (surprisingly!).
> **`Double.IsNegative(Double)` Method**
> Indicates if the value's internal IEEE-754 base-2 floating-point _sign-bit_ is `1`, indicating a negative value, including negative-zero (`-0f`). This method also returns `true` for `NaN`. This method returns `false` for positive-zero values.
## `IsFinite`, `IsInfinity`, and `IsNaN`
The documentation for `IsInfinity` and `IsNaN` is mature and largely comprehensive, but the recently-added `IsFinite` method lacks sufficient supporting documentation - and the `` can be improved.
The summary currently reads as this:
> [**`Double.IsFinite(Double)` Method**](https://docs.microsoft.com/en-us/dotnet/api/system.single.isfinite?view=net-6.0)
> Determines whether the specified value is finite (zero, subnormal or normal).
Now, one might assume that `IsInfinity` and `IsFinite` are logical negations of each other (over all argument values), however this doesn't include `NaN`. Could it be something like this instead?
> **`Double.IsFinite(Double)` Method**
> Determines whether the specified value is finite (zero, subnormal or normal) - that is, not `PositiveInfinity` nor `NegativeInfinity` (`IsInfinity`), and also not `NaN`, otherwise this method always returns `true`.
And update `IsInfinity` similarly too:
> **`Double.IsInfinity(Double)` Method**
> Returns `true` only if the specified value evaluates to `PositiveInfinity` or `NegativeInfinity`, otherwise this method returns `false` for `NaN` and all other values.
## Add a comparison table?
I made a Linqpad script in a gist that shows the results of each of the `Single.*` methods, as well as some additional custom comparisons, and I think this table it generates would be a useful resource to add to all of the pages for those methods.
https://gist.github.com/Jehoel/ebb18d5a6804287544f397f300f7543b
I think it would be useful to have a table similar to this one I generated:

The gist above includes a Markdown representation of the same table if you want to use that.
Contributor guide
Assessment
This issue has not been assessed yet.