[API Proposal]: Expose the remaining const values in TimeSpan

[IDisposable]

Edited By @tarekgh

This proposal has been approved before #94545 (comment). There was some feedback from @tannergooding and @IDisposable.

@tannergooding said: the concern I raised is that there are scenarios this can cause problems since days * TimeSpan.HoursPerDay could overflow. For example, if days > 89,478,485 then this will overflow to a negative int.
HoursPerDay happens to be the only case where it is "sensible" for it to be int, since both MaxDays (10,675,199) and MaxHours (256,204,778) are within int.MaxValue. That is also why the signatures are FromDays(int days, int hours, long minutes, long milliseconds, long microseconds). So other values, like MinutesPerDay (1440), MinutesPerHour (60), or even the existing MillisecondsPerTick (10,000) are all expected to be used in contexts where long is the target type.
When considering TimeSpan, which is where these constants are defined, hours and days are int, all other units are long.

---

Background and motivation

In the TimeSpan class there are a few public const values that are generally applicable that are usefully exposed.

There are also a bunch more that are internal const but would be generally useful for other code and are not more implementation driven than the already exposed const values.

These values should be exposed publicly on the TimeSpan class.

Note: NOT suggesting we expose the truly internal const values that are related to MinTicks and MaxTicks. They could be included but are just not as naturally useful elsewhere.

API Proposal

namespace System.Collections.Generic;

public class TimeSpan: // elided details
{
        // more elision

        public const long MicrosecondsPerMillisecond = TicksPerMillisecond / TicksPerMicrosecond; //           1,000
        public const long MicrosecondsPerSecond = TicksPerSecond / TicksPerMicrosecond;           //       1,000,000
        public const long MicrosecondsPerMinute = TicksPerMinute / TicksPerMicrosecond;           //      60,000,000
        public const long MicrosecondsPerHour = TicksPerHour / TicksPerMicrosecond;               //   3,600,000,000
        public const long MicrosecondsPerDay = TicksPerDay / TicksPerMicrosecond;                 //  86,400,000,000

        public const long MillisecondsPerSecond = TicksPerSecond / TicksPerMillisecond;           //           1,000
        public const long MillisecondsPerMinute = TicksPerMinute / TicksPerMillisecond;           //          60,000
        public const long MillisecondsPerHour = TicksPerHour / TicksPerMillisecond;               //       3,600,000
        public const long MillisecondsPerDay = TicksPerDay / TicksPerMillisecond;                 //      86,400,000

        public const long SecondsPerMinute = TicksPerMinute / TicksPerSecond;                     //              60
        public const long SecondsPerHour = TicksPerHour / TicksPerSecond;                         //           3,600
        public const long SecondsPerDay = TicksPerDay / TicksPerSecond;                           //          86,400

        public const long MinutesPerHour = TicksPerHour / TicksPerMinute;                         //              60
        public const long MinutesPerDay = TicksPerDay / TicksPerMinute;                           //           1,440

        public const long HoursPerDay = TicksPerDay / TicksPerHour;                               //              24
}

API Usage

if (TimeSpan.MinutesPerHour * numHours) > TimeSpan.MinutesPerDay * 7)
    Console.WriteLine("That's really weeks");

Alternative Designs

N/A

Risks

Since these are compile-time constant values, there would be no runtime cost in either memory or execution overhead. Additionally they would centralize basic real-world facts to one logical location (TimeSpan).

[ghost]

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

Issue Details

---

Background and motivation

In the TimeSpan class there are a few public const values that are generally applicable that are usefully exposed.

There are also a bunch more that are internal const but would be generally useful for other code and are not more implementation driven than the already exposed const values.

These values should be exposed publicly on the TimeSpan class.

Note: NOT suggesting we expose the truly internal const values that are related to MinTicks and MaxTicks. They could be included but are just not as naturally useful elsewhere.

API Proposal

namespace System.Collections.Generic;

public class TimeSpan: // elided details
{
        // more elision

        public const long MicrosecondsPerMillisecond = TicksPerMillisecond / TicksPerMicrosecond; //           1,000
        public const long MicrosecondsPerSecond = TicksPerSecond / TicksPerMicrosecond;           //       1,000,000
        public const long MicrosecondsPerMinute = TicksPerMinute / TicksPerMicrosecond;           //      60,000,000
        public const long MicrosecondsPerHour = TicksPerHour / TicksPerMicrosecond;               //   3,600,000,000
        public const long MicrosecondsPerDay = TicksPerDay / TicksPerMicrosecond;                 //  86,400,000,000

        public const long MillisecondsPerSecond = TicksPerSecond / TicksPerMillisecond;           //           1,000
        public const long MillisecondsPerMinute = TicksPerMinute / TicksPerMillisecond;           //          60,000
        public const long MillisecondsPerHour = TicksPerHour / TicksPerMillisecond;               //       3,600,000
        public const long MillisecondsPerDay = TicksPerDay / TicksPerMillisecond;                 //      86,400,000

        public const long SecondsPerMinute = TicksPerMinute / TicksPerSecond;                     //              60
        public const long SecondsPerHour = TicksPerHour / TicksPerSecond;                         //           3,600
        public const long SecondsPerDay = TicksPerDay / TicksPerSecond;                           //          86,400

        public const long MinutesPerHour = TicksPerHour / TicksPerMinute;                         //              60
        public const long MinutesPerDay = TicksPerDay / TicksPerMinute;                           //           1,440

        public const long HoursPerDay = TicksPerDay / TicksPerHour;                               //              24
}

API Usage

if (TimeSpan.MinutesPerHour * numHours) > TimeSpan.MinutesPerDay * 7)
    Console.WriteLine("That's really weeks");

Alternative Designs

N/A

Risks

Since these are compile-time constant values, there would be no runtime cost in either memory or execution overhead. Additionally they would centralize basic real-world facts to one logical location (TimeSpan).

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

[IDisposable]

Is this something we can add to the API review?

[tannergooding]

CC. @tarekgh, this is a relatively simple ask and I know I've had to redefine such constants myself in personal projects to help with various extension methods or other time related structs used (such as a Timestamp struct used to track frame timings in a game engine).

[tarekgh]

I am fine to proceed with the proposal. I don't have any feedback as the proposal looks good to me as it is. I'll mark this as ready for review.

[IDisposable]

Should I reopen the PR or start a new one? :)

[tarekgh]

@IDisposable please wait till the issue gets reviewed by the design committee and then we can reopen the PR. Thanks!

[bartonjs]

Video

• The consts that can be int should be
• Otherwise, looks good as proposed.

namespace System.Collections.Generic;

public partial class TimeSpan
{
        public const int MicrosecondsPerMillisecond = TicksPerMillisecond / TicksPerMicrosecond; //           1,000
        public const int MicrosecondsPerSecond = TicksPerSecond / TicksPerMicrosecond;           //       1,000,000
        public const int MicrosecondsPerMinute = TicksPerMinute / TicksPerMicrosecond;           //      60,000,000
        public const long MicrosecondsPerHour = TicksPerHour / TicksPerMicrosecond;               //   3,600,000,000
        public const long MicrosecondsPerDay = TicksPerDay / TicksPerMicrosecond;                 //  86,400,000,000

        public const int MillisecondsPerSecond = TicksPerSecond / TicksPerMillisecond;           //           1,000
        public const int MillisecondsPerMinute = TicksPerMinute / TicksPerMillisecond;           //          60,000
        public const int MillisecondsPerHour = TicksPerHour / TicksPerMillisecond;               //       3,600,000
        public const int MillisecondsPerDay = TicksPerDay / TicksPerMillisecond;                 //      86,400,000

        public const int SecondsPerMinute = TicksPerMinute / TicksPerSecond;                     //              60
        public const int SecondsPerHour = TicksPerHour / TicksPerSecond;                         //           3,600
        public const int SecondsPerDay = TicksPerDay / TicksPerSecond;                           //          86,400

        public const int MinutesPerHour = TicksPerHour / TicksPerMinute;                         //              60
        public const int MinutesPerDay = TicksPerDay / TicksPerMinute;                           //           1,440

        public const int HoursPerDay = TicksPerDay / TicksPerHour;                               //              24
}

[julealgon]

What was the underlying reason to not expose these when they were first introduced? Was it just a matter of YAGNI, or was there more to it?

[IDisposable]

@bartonjs

The consts that can be int should be

In general, I certainly agree, I was just adjusting the visibility of what was already there... so moving them to int from long would have to be carefully checked in the current consumers of these internal values to make sure that this change doesn't accidentally introduce cases where binary operations that were dealing with an int combined with one of these long constants wouldn't break (overflow/etc.) if it's now ant int op int. I will ensure I've got tests for that in the final PR

[tarekgh]

What was the underlying reason to not expose these when they were first introduced? Was it just a matter of YAGNI, or was there more to it?

Usually, such constants get introduced when implementing other approved features. To expose anything, it needs to go as a separate proposal to design review it. That is what happened here.

[tannergooding]

so moving them to int from long would have to be carefully checked

If we find this is problematic, then please comment back and we can keep them as long with the annotation that they need to be so that regular usage doesn't cause overflow or other problems.

I can easily get the sign-off for that over e-mail and just chalk it up to a consideration no one thought about in the 60s it took to review the APIs 😆

[tarekgh]

@bartonjs

I merged the changes but I missed your comment #94545 (comment). We went with long types for the new constants but if you think HoursPerDay should be int we can submit another PR to change that. Please let me know and sorry for missing your comment.

CC @tannergooding @terrajobst

[IDisposable]

Preparing a change to make the smaller constants int instead of long per this comment but given the concerns about accidental overflows, and other feedback maybe push back on keeping these two as long as well (as they're the most likely to unintentionally overflow) to parallel what was done with the MicrosecondsPerHour and MicrosecondsPerDay in the revised proposal

        public const long MillisecondsPerHour = TicksPerHour / TicksPerMillisecond;               //       3,600,000
        public const long MillisecondsPerDay = TicksPerDay / TicksPerMillisecond;                 //      86,400,000

[tarekgh]

@IDisposable let's apply the approved proposal #94545 (comment) and then we can track any further changes to bring it back to the design review.

[IDisposable]

New PR #103721

[bartonjs]

Video

Based on the domain (the TimeSpan type itself), the belief is that long is correct for everything except HoursPerDay (int).

While that's not so nice for seconds * TimeSpan.MillisecondsPerSecond for passing to (e.g.) new CancellationTokenSource(int), it is more appropriate for working with the TimeSpan type itself.

namespace System.Collections.Generic;

public class TimeSpan: // elided details
{
        // more elision

        public const long MicrosecondsPerMillisecond = TicksPerMillisecond / TicksPerMicrosecond; //           1,000
        public const long MicrosecondsPerSecond = TicksPerSecond / TicksPerMicrosecond;           //       1,000,000
        public const long MicrosecondsPerMinute = TicksPerMinute / TicksPerMicrosecond;           //      60,000,000
        public const long MicrosecondsPerHour = TicksPerHour / TicksPerMicrosecond;               //   3,600,000,000
        public const long MicrosecondsPerDay = TicksPerDay / TicksPerMicrosecond;                 //  86,400,000,000

        public const long MillisecondsPerSecond = TicksPerSecond / TicksPerMillisecond;           //           1,000
        public const long MillisecondsPerMinute = TicksPerMinute / TicksPerMillisecond;           //          60,000
        public const long MillisecondsPerHour = TicksPerHour / TicksPerMillisecond;               //       3,600,000
        public const long MillisecondsPerDay = TicksPerDay / TicksPerMillisecond;                 //      86,400,000

        public const long SecondsPerMinute = TicksPerMinute / TicksPerSecond;                     //              60
        public const long SecondsPerHour = TicksPerHour / TicksPerSecond;                         //           3,600
        public const long SecondsPerDay = TicksPerDay / TicksPerSecond;                           //          86,400

        public const long MinutesPerHour = TicksPerHour / TicksPerMinute;                         //              60
        public const long MinutesPerDay = TicksPerDay / TicksPerMinute;                           //           1,440

        public const int HoursPerDay = TicksPerDay / TicksPerHour;                               //              24
}

[IDisposable]

That makes perfect sense, let me know when/what the final should be and I will resubmit

[tannergooding]

You should feel free to submit a PR matching it at any time now, we're in agreement as to the handling here now.

[tarekgh]

@IDisposable

let me know when/what the final should be and I will resubmit

It is ready now so you can resurrect or create a new PR now.

[IDisposable]

Working on it... do we have a decision about the casting at call-site or modifying the parameters type as mentioned here?

We had settled on casting at the call site, last I remember... and suspect we should go that route now.

[IDisposable]

PR #103993 has hopefully final iteration :)