Skip to content

IsNormal #11194

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
hjrb opened this issue Apr 14, 2025 · 6 comments
Open

IsNormal #11194

hjrb opened this issue Apr 14, 2025 · 6 comments
Labels
area-WinForms Issues or PRs that relate to WinForms. untriaged New issue has not been triaged by the area owner

Comments

@hjrb
Copy link

hjrb commented Apr 14, 2025

Type of issue

Missing information

Description

[Enter feedback here]
true if value is normal; otherwise, false.
I mean that is a zero value information. That is what the name expresses. But what is meant with "Normal"

Page URL

https://learn.microsoft.com/en-us/dotnet/api/system.numerics.inumberbase-1.isnormal?view=net-9.0#system-numerics-inumberbase-1-isnormal(-0)

Content source URL

https://github.com/dotnet/dotnet-api-docs/blob/main/xml/System.Numerics/INumberBase`1.xml

Document Version Independent Id

39653173-8e6e-5387-fd3e-f36b7e1fb52e

Platform Id

90f254b1-c168-6be0-b81b-49e8928a5c12

Article author

@dotnet-bot

@dotnet-policy-service dotnet-policy-service bot added the untriaged New issue has not been triaged by the area owner label Apr 14, 2025
@github-actions github-actions bot added the area-WinForms Issues or PRs that relate to WinForms. label Apr 14, 2025
@M-Badger
Copy link

I would agree that some extra information in the documentation would be helpful, for example an explanation of Normal and Subnormal and a code example, such as :

Normal
A normal number is one that is not zero and for which the IsNan, IsPositiveInfinity and IsNegativeInfinity methods return false.

Subnormal
A subnormal number is one that is too small to be represented in the normalised format of the floating-point arithmetic type in question.
For example, when tested with IsSubnormal a double that is smaller than Double.MinValue but which is not zero will return true

using System;
using System.Numerics;

public class Example
{
    public static void Main()
    {
        // This example demonstrates the behaviour of IsNormal and IsSubnormal properties using the double type
        double a = double.NaN;
        double b = double.PositiveInfinity;
        double c = double.NegativeInfinity;
        double d = 0.0;
        double e = 1.0;
        double f = 4.94065645841247E-324;

        Console.WriteLine("Result of IsNormal on double.Nan                            : {0}", Double.IsNormal(a));
        Console.WriteLine("Result of IsNormal on double.PositiveInfinity               : {0}", Double.IsNormal(b));
        Console.WriteLine("Result of IsNormal on double.NegativeInfinity               : {0}", Double.IsNormal(c));
        Console.WriteLine("Result of IsNormal on (double d = 0.0)                      : {0}", Double.IsNormal(d));
        Console.WriteLine("Result of IsNormal on (double e = 1.0)                      : {0}", Double.IsNormal(e));
        Console.WriteLine("Result of IsNormal on (double f = 4.94065645841247E-324)    : {0}", Double.IsNormal(f));

        Console.WriteLine();

        Console.WriteLine("Result of IsSubnormal on Double.Nan                         : {0}", Double.IsSubnormal(a));
        Console.WriteLine("Result of IsSubnormal on Double.PositiveInfinity            : {0}", Double.IsSubnormal(b));
        Console.WriteLine("Result of IsSubnormal on Double.NegativeInfinity            : {0}", Double.IsSubnormal(c));
        Console.WriteLine("Result of IsSubnormal on (double d = 0.0)                   : {0}", Double.IsSubnormal(d));
        Console.WriteLine("Result of IsSubnormal on (double e = 1.0)                   : {0}", Double.IsSubnormal(e));
        Console.WriteLine("Result of IsSubnormal on (double f = 4.94065645841247E-324) : {0}", Double.IsSubnormal(f));

        // The example displays the following output:
        //       Result of IsNormal on double.Nan                             : False
        //       Result of IsNormal on double.PositiveInfinity                : False
        //       Result of IsNormal on double.NegativeInfinity                : False
        //       Result of IsNormal on (double d = 0.0)                       : False
        //       Result of IsNormal on (double e = 1.0)                       : True
        //       Result of IsNormal on (double f = 4.94065645841247E-324)     : False

        //       Result of IsSubnormal on Double.Nan                          : False
        //       Result of IsSubnormal on Double.PositiveInfinity             : False
        //       Result of IsSubnormal on Double.NegativeInfinity             : False
        //       Result of IsSubnormal on (double d = 0.0)                    : False
        //       Result of IsSubnormal on (double e = 1.0)                    : False
        //       Result of IsSubnormal on (double f = 4.94065645841247E-324)  : True
    }
}

@tannergooding
Copy link
Member

A code example doesn't really help or tell people anything either. The definitions given above are also not accurate.

The official definition, as laid out in the IEEE 754 specification is:

normal number: For a particular format, a finite non-zero floating-point number with magnitude greater
than or equal to a minimum bemin value, where b is the radix. Normal numbers can use the full precision
available in a format. In this standard, zero is neither normal nor subnormal.

subnormal number: In a particular format, a non-zero floating-point number with magnitude less than the
magnitude of that format’s smallest normal number. A subnormal number does not use the full precision
available to normal numbers of the same format.

This arguably doesn't really tell people much either as it requires more in depth technical information about the IEEE 754 standard and the underlying format/representation of the types. You need to understand that emin = 1 - emax and then that emax is dependent on the type, so

  • float: emin=-126, emax=+127
  • double: emin=-1022, emax=+1023

There is likely some better wording that can be added here, but these are somewhat domain specific terms that largely are going to refer to other specs and definitions. The API on INumberBase then needs to talk about it without giving a concrete number, since its a generic type and what is subnormal for one type is not subnormal for another.

@gewarren gewarren added the code-of-conduct Indicates issues that are spam, trolling, or anything that violates our code of conduct label Apr 22, 2025
@svick
Copy link
Contributor

svick commented Apr 22, 2025

@gewarren I don't think this issue should be closed. Despite the brief title and description, the problem (unclear documentation of the member) is real.

@hjrb
Copy link
Author

hjrb commented Apr 22, 2025

I agree. Especially as some kind people have provided a load of really helpful information.

@gewarren
Copy link
Contributor

Apologies, bulk labeling mistake.

@hjrb
Copy link
Author

hjrb commented Apr 22, 2025

got automatically closed again after re-open

@gewarren gewarren removed the code-of-conduct Indicates issues that are spam, trolling, or anything that violates our code of conduct label Apr 22, 2025
@gewarren gewarren reopened this Apr 22, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area-WinForms Issues or PRs that relate to WinForms. untriaged New issue has not been triaged by the area owner
Projects
None yet
Development

No branches or pull requests

5 participants