Add method Time.get_duration_dict_from_duration()

[Meorge]

Closes godotengine/godot-proposals#12735 .

This PR adds a new method, Time.get_duration_dict_from_duration(), which takes a number of seconds as a float and a set of time units as an enum bitfield, and returns a Dictionary with the seconds converted into the specified units.

var godot_is_open_source = Time.get_unix_time_from_datetime_string("2014-02-10T01:10:00.000Z")
var godot_4_4_stable = Time.get_unix_time_from_datetime_string("2025-03-02T23:31:23.000Z")
var delta = godot_4_4_stable - godot_is_open_source
print(
        Time.get_duration_dict_from_duration(
            delta,
            Time.DURATION_SECONDS |
            Time.DURATION_MINUTES |
            Time.DURATION_HOURS |
            Time.DURATION_DAYS |
            Time.DURATION_MILLISECONDS
        )
)

print(
        Time.get_duration_dict_from_duration(
            delta,
            Time.DURATION_SECONDS |
            Time.DURATION_MINUTES
        )
)

print(
        Time.get_duration_dict_from_duration(
            3700.0 - 3623.82,
            Time.DURATION_SECONDS |
            Time.DURATION_MINUTES |
            Time.DURATION_MILLISECONDS
        )
)

Prints out:

{ "days": 4038.0, "hours": 22.0, "minutes": 21.0, "seconds": 23.0, "milliseconds": 0.0, "remaining": 0.0 }
{ "minutes": 5816061.0, "seconds": 23.0, "remaining": 0.0 }
{ "minutes": 1.0, "seconds": 16.0, "milliseconds": 179.0, "remaining": 0.00099999999984 }

The first test's results, at least, align with Python code using its official libraries:

import datetime

godot_is_open_source = datetime.datetime.fromisoformat("2014-02-10T01:10:00.000Z")
godot_4_4_stable = datetime.datetime.fromisoformat("2025-03-02T23:31:23.000Z")

print(godot_4_4_stable - godot_is_open_source)

4038 days, 22:21:23

(If anyone's got suggestions on good benchmarks/standards to test other select combinations of units on, please feel free to suggest them!)

To Do

• Write actual tests for the engine
• Determine how remaining seconds should be handled (passed back as "remaining", or included as fractional part of smallest specified unit, etc?)
• Write documentation for the method and enum