New TimeSpan.From overloads which take integers.

[tannergooding]

Summary

TimeSpan exposes several From* methods that allow users to create a timespan using a double. However, double is a binary based floating-point format and thus has natural imprecision that can introduce error. For example, TimeSpan.FromSeconds(101.832) is not 101 seconds, 832 milliseconds, but rather is 101 seconds, 831.9999999999936335370875895023345947265625 milliseconds.

This has, over time, led to repeated user confusion and bugs in the API surface that users have had to rationalize and deal with. It is also one of the less efficient ways to represent this data and makes it problematic for users wanting or expecting a particular behavior

As such, it is proposed that new overloads be provided, allowing users to pass in integers so they can get the desired and intended behavior. It may be worth considering whether or not the double overloads should be "deprecated" (either via obsoletion or some analyzer) to help direct users towards success.

API Proposal

namespace System;

public partial struct TimeSpan
{
    public static TimeSpan FromDays(int days, int hours = 0, int minutes = 0, int seconds = 0, int milliseconds = 0, int microseconds = 0);
    public static TimeSpan FromHours(int hours, int minutes = 0, int seconds = 0, int milliseconds = 0, int microseconds = 0);
    public static TimeSpan FromMinutes(int minutes, int seconds = 0, int milliseconds = 0, int microseconds = 0);
    public static TimeSpan FromSeconds(int seconds, int milliseconds = 0, int microseconds = 0);
    public static TimeSpan FromMilliseconds(int milliseconds, int microseconds = 0);
    public static TimeSpan FromMicroseconds(int microseconds);
}

Additional Considerations

It may be desirable to not use default parameters. However, this provides a benefit that a user can do something like FromDays(5, seconds: 30) if that were appropriate for their use case.

After these APIs are exposed, calling From(x) where x was an integer may produce a different result in various edge cases.

APIs where the user specifies a uint, long, or ulong would still end up calling the double overload due to the implicit conversion that exists in C#. Thus, an analyzer or deprecation of the double overloads may be desirable to help users achieve success.

Exposing overloads that take decimal could also be desirable and would avoid the issues around precision loss, but would be much less performant than breaking it apart like this.

Tagging subscribers to this area: @dotnet/area-system-datetime
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Summary

TimeSpan exposes several From* methods that allow users to create a timespan using a double. However, double is a binary based floating-point format and thus has natural imprecision that can introduce error. For example, TimeSpan.FromSeconds(101.832) is not 101 seconds, 832 milliseconds, but rather is 101 seconds, 831.9999999999936335370875895023345947265625 milliseconds.

This has, over time, led to repeated user confusion and bugs in the API surface that users have had to rationalize and deal with. It is also one of the less efficient ways to represent this data and makes it problematic for users wanting or expecting a particular behavior

As such, it is proposed that new overloads be provided, allowing users to pass in integers so they can get the desired and intended behavior. It may be worth considering whether or not the double overloads should be "deprecated" (either via obsoletion or some analyzer) to help direct users towards success.

API Proposal

namespace System;

public partial struct TimeSpan
{
    public static TimeSpan FromDays(int days, int hours = 0, int minutes = 0, int seconds = 0, int milliseconds = 0, int microseconds = 0);
    public static TimeSpan FromHours(int hours = 0, int minutes = 0, int seconds = 0, int milliseconds = 0, int microseconds = 0);
    public static TimeSpan FromMinutes(int minutes, int seconds = 0, int milliseconds = 0, int microseconds = 0);
    public static TimeSpan FromSeconds(int seconds, int milliseconds = 0, int microseconds = 0);
    public static TimeSpan FromMilliseconds(int milliseconds, int microseconds = 0);
    public static TimeSpan FromMicroseconds(int microseconds);
}

Additional Considerations

It may be desirable to not use default parameters. However, this provides a benefit that a user can do something like FromDays(5, seconds: 30) if that were appropriate for their use case.

After these APIs are exposed, calling From(x) where x was an integer may produce a different result in various edge cases.

APIs where the user specifies a uint, long, or ulong would still end up calling the double overload due to the implicit conversion that exists in C#. Thus, an analyzer or deprecation of the double overloads may be desirable to help users achieve success.

Exposing overloads that take decimal could also be desirable and would avoid the issues around precision loss, but would be much less performant than breaking it apart like this.

Author:	tannergooding
Assignees:	-
Labels:	api-suggestion, area-System.DateTime
Milestone:	-

[tannergooding]

Opened in response to #93831 and the numerous other issues where the various TimeSpan APIs which take double have shown themselves to be problematic.

CC. @tarekgh

[vcsjones]

TimeSpan has constructors that largely do the same thing, unless I am misunderstanding. There was also the recent addition of constructors that take microseconds in #23799.

Are the constructors reasonable enough? If not, should the focus instead be on improving the constructors?

[tarekgh]

public static TimeSpan FromHours(int hours = 0, int minutes = 0, int seconds = 0, int milliseconds = 0, int microseconds = 0);

@tannergooding did you mean to have the hours parameter with default value?

@vcsjones the idea here is having the users not providing a lot of value as the constructor requires. Having default parameter values will help.

[tannergooding]

did you mean to have the hours parameter with default value?

Nope. The first parameter should be non-defaultable. Fixed.

Please feel free to mark api-ready-for-review if you think this is in the right shape and good for API review.

Are the constructors reasonable enough? If not, should the focus instead be on improving the constructors?

I think the constructors are worse in a lot of ways over static methods. For example, new TimeSpan(1, 2, 3) and new TimeSpan(1, 2, 3, 4) having arguments not line up (one is hours first the other is days first). You can't expose defaultable parameters without causing ambiguities. new TimeSpan(...) in general doesn't help provide clarity or intent, at a glance, etc.

The explicit From* APIs, on the other hand, avoid most of these issues and provide additional clarity to the code in question (as a personal preference, TimeSpan.FromHours(5, 1, 30) also looks a lot cleaner than new TimeSpan(5, 1, 30) and is more visually appealing in code).