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

Open
#7,962 1 comment 0 reactions 0 assignees View on GitHub
area-System.Runtime Pri3 untriaged
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:

![image](https://user-images.githubusercontent.com/1693078/163430479-c3bf574e-73cc-4162-899f-b8d611457386.png)

The gist above includes a Markdown representation of the same table if you want to use that.

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.