Document casting INF/NAN to int is undefined behavior

[Arecher]

• Extended warning to document int(INF) and int(NAN) return -9223372036854775808 on most platforms

What problem(s) does this PR solve?

• Documents (but does not fix) the bugs described in Can't compare INF or NAN reliably when used on an int var #33017

Additional information

While I consider this a bug, it has been present since at least Godot 3.x, so it is better documented until fixed.

[AThousandShips]

LGTM!

[bruvzg]

I do think removing the explicit value means the documentation won't be surfaced when users google for the keywords INF and -9223372036854775808/ negative value, which (going by the half-dozen bug reports) is how this issue is mostly referenced to. But I understand the reason for removing it.

Documentation can include keywords="" field, which is used for search but not displayed in UI.

diff --git a/modules/gdscript/doc_classes/@GDScript.xml b/modules/gdscript/doc_classes/@GDScript.xml
index a84c59b4ee..6f78d07d9a 100644
--- a/modules/gdscript/doc_classes/@GDScript.xml
+++ b/modules/gdscript/doc_classes/@GDScript.xml
@@ -285,11 +285,11 @@
                <constant name="TAU" value="6.28318530717959">
                        The circle constant, the circumference of the unit circle in radians. This is equivalent to [code]PI * 2[/code], or 360 degrees in rotations.
                </constant>
-               <constant name="INF" value="inf">
+               <constant name="INF" value="inf" keywords="-9223372036854775808,9223372036854775808,-9223372036854775807,9223372036854775807">
                        Positive floating-point infinity. This is the result of floating-point division when the divisor is [code]0.0[/code]. For negative infinity, use [code]-INF[/code]. Dividing by [code]-0.0[/code] will result in negative infinity if the numerator is positive, so dividing by [code]0.0[/code] is not the same as dividing by [code]-0.0[/code] (despite [code]0.0 == -0.0[/code] returning [code]true[/code]).
                        [b]Warning:[/b] Numeric infinity is only a concept with floating-point numbers, and has no equivalent for integers. Dividing an integer number by [code]0[/code] will not result in [constant INF] and will result in a run-time error instead.
                </constant>
-               <constant name="NAN" value="nan">
+               <constant name="NAN" value="nan" keywords="-9223372036854775808,9223372036854775808,-9223372036854775807,9223372036854775807">
                        "Not a Number", an invalid floating-point value. It is returned by some invalid operations, such as dividing floating-point [code]0.0[/code] by [code]0.0[/code].
                        [constant NAN] has special properties, including that [code]!=[/code] always returns [code]true[/code], while other comparison operators always return [code]false[/code]. This is true even when comparing with itself ([code]NAN == NAN[/code] returns [code]false[/code] and [code]NAN != NAN[/code] returns [code]true[/code]). Due to this, you must use [method @GlobalScope.is_nan] to check whether a number is equal to [constant NAN].
                        [b]Warning:[/b] "Not a Number" is only a concept with floating-point numbers, and has no equivalent for integers. Dividing an integer [code]0[/code] by [code]0[/code] will not result in [constant NAN] and will result in a run-time error instead.

[Arecher]

Interesting! That would be an improvement for being able to surface the documentation for sure.

I could add that if desired, although I do not understand the impact of changing:

--- a/modules/gdscript/doc_classes/@GDScript.xml
+++ b/modules/gdscript/doc_classes/@GDScript.xml

[bruvzg]

I could add that if desired, although I do not understand the impact of changing

This is just a part of diff file format, ignore it if you adding it manually.

[Arecher]

Is there a way to add an invisible note to the keywords, so if this bug gets fixed in the future, it is clear why these seemingly random int values are in the documentation?

[AThousandShips]

There's no bug here, this is undefined behavior in the C++ language, conversions from floating point values to integers are defined as "If the truncated value cannot fit into the destination type, the behavior is undefined (even when the destination type is unsigned, modulo arithmetic does not apply).", so we'd have to do some arbitrary decision as to what to make it become in those cases

[Arecher]

Right, from an implementation standpoint I agree there is no bug, but from a user perspective int(INF) returning -9223372036854775808* is clearly perceived as a bug due to how unexpected and counterintuitive it is. In issues where this got discussed, there seems to be relative consensus that it should be changed, just not how it should be changed (disabled completely, always return 0, return lowest/highest int, etc).

[AThousandShips]

I disagree that casting INF to an int should have any reasonable result, any result at all would be wrong I'd say, INF is not the same as "the maximum value" so returning INT64_MAX would be incorrect

But something to discuss on the issue thread

[Repiteo]

Regardless of what casting ±INF to int should do, any change to that logic would be compatibility-breaking and is out of the scope of this PR. For the time being, documenting the existing behavior is sufficient

[Repiteo]

Could you squash your commits? See our pull request guidelines for more information