Split String.num() into two functions: num_float and num_simple

[aaronfranke]

Describe the project you are working on

This applies to all Godot Engine projects.

Describe the problem or limitation you are having in your project

As of #7894 and godotengine/godot#47502, the number-to-string functions in Godot look like this:

Function Name	Param Type	Behavior Brief Description
num	float	Has a trailing decimal point (.0), always float literal.
num_scienfitic	float	Compact representation, using scientific notation for big numbers.
num_int64	int	No trailing decimal point, always int literal.
num_uint64	int	No trailing decimal point, always int literal.
str	Variant	If given a float, behaves like num. If given an int, like num_int64.

All of the num* functions are in String, but str is a global function.

There are 2 problems here:

• There is no built-in function for accepting a float and converting it without whole numbers having a trailing .0.
  • On its own this is bad due to lack of choice, but moreso, this means the Godot 4.3 and earlier behavior is just not available.
• "num" is not a clear name for a function that always adds a trailing decimal point.
  • If anything, I would expect a function called "num" to be close to a mathematical number, where there is no distinction between float and int, and therefore no trailing .0 would be added for whole numbers.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

My proposal is to split num into two functions so that it looks like this:

Function Name	Param Type	Behavior Brief Description
num	float	Deprecated alias for num_float (or maybe num_simple for 4.3 compat?)
num_float	float	Has a trailing decimal point (.0), always float literal.
num_simple	float	Does not include trailing decimal for whole numbers.
num_scienfitic	float	Compact representation, using scientific notation for big numbers.
num_int64	int	No trailing decimal point, always int literal.
num_uint64	int	No trailing decimal point, always int literal.
str	Variant	If given a float, behaves like num_float. If given an int, like num_int64.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

The proposal would work like this, all three should happen in the same PR:

• Rename num to num_float.
• Add a new num_simple function that works like num did in Godot 4.3.
• Add an alias num to num_float to keep existing code running.

Or, alternatively:

• Rename num to num_float.
• Add a new num_simple function that works like num did in Godot 4.3.
• Add an alias num to num_simple to keep existing code working like it did in Godot 4.3 and earlier.

If this enhancement will not be used often, can it be worked around with a few lines of script?

Yes, trivially, but confusingly, and inefficiently: String.num(my_float).trim_suffix(".0")

Is there a reason why this should be core and not an add-on in the asset library?

Converting numbers to strings is core.

[Ivorforce]

The num_simple function should probably take a Variant parameter, to avoid accidental conversion for potential int arguments:

print(9223372036854775806)  // 9223372036854775806
print(float(9223372036854775806))  // 9223372036854775808, precision lost

It's unfortunate num was used to format float, otherwise i'd suggest that as a name for 'format any number in a compact manner'. num_simple is a serviceable name, though I wish I'd have a better suggestion for it since I may have avoided it had I stumbled across it, thinking it may do something different from 'normal' number formatting.