[API Proposal]: IDate, IDateTime, ITime Interfaces

[robloo]

Background and motivation

.NET now has many different DateTime types: DateTime, DateTimeOffset, DateOnly, etc. Each of these were added for good reasons.

• DateTime : The original but fails to account for time zone offsets
• DateTimeOffset : Accounts for only a numerical DateTimeOffset (not named IANA zones)
• DateOnly : Simplified dates without worrying about time and timezone offsets complicating calculations
• TimeOnly : Simplified again with only time-related components.

But there is one obvious gap. For UI programming IANA time zone or Windows ID time zones are required for user selection. It's not 1:1 to convert this to/from a numerical time zone offset which means DateTimeOffset can't be used in some cases as well. Then 3rd party libraries come into play to fill this gap.

Now we have way too many Date/Time types to manage and no way to do it in a generic way. So my proposal is something like the INumber interface to bring all of this together.

The use cases are not only for backend code. But also for UI controls. For example UI frameworks can start writing generic Date/TimePickers and allow the app to define the type they need to work with. An IDate interface is perfect for this to support all known date/time types (since a DatePicker control only cares about the date-related components).

API Proposal

I'll flesh this out when I have more time.

public interface IDate
{
  int Day;
  int Month;
  int Year;
}

public interface IDateTime
{
  int Day;
  int Month;
  int Year;
  int Hour;
  int Minute;
  int Second;
}

public interface ITime
{
  int Hour;
  int Minute;
  int Second;
}

API Usage

TBD

Alternative Designs

It needs to be discussed:

1. Whether to call these interfaces IDateOnly and ITimeOnly instead and model them almost entirely based on DateOnly and TimeOnly. Then IDateTime will simply be a union of the two interfaces.
2. The specific members to include in ITimeOnly are debatable. Should this be only high-level hours/minutes/seconds (all that usually needed for general-purpose or UI code) or should it include all members down to ticks. The answer is likely all members down to ticks. However, some 3rd party libraries may not support all these members. Therefore, there could be multiple levels to these interfaces like what was done for INumber. Basically IBasicTimeOnly with only hours/minutes/seconds and then an ITimeOnly that derives from that and includes everything.

Risks

This seems low risk to me as it is only abstracting common, shared properties already used in all the types.

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

.NET now has many different DateTime types: DateTime, DateTimeOffset, DateOnly, etc. Each of these were added for good reasons.

• DateTime : The original but fails to account for time zone offsets
• DateTimeOffset : Accounts for only a numerical DateTimeOffset (not named IANA zones)
• DateOnly : Simplified dates without worrying about time and timezone offsets calculating calculations
• TimeOnly : Simplified again with only time components.

But there is one obvious gap. For UI programming IANA time zone or Windows ID time zones are required for user selection. It's not 1:1 to convert this to/from a numerical time zone offset which means DateTimeOffset can't be used in some cases as well. Then 3rd party libraries come into play to fill this gap.

Now we have way too many Date/Time types to manage and no way to do it in a generic way. So my proposal is something like the new INumber interface to bring all of this together.

The use cases are not only for backend code. But also for UI controls. For example UI frameworks can start writing generic Date/TimePickers and allow the app to define the type they need to work with. An IDate interface is perfect for this to support all known date/time types (since a DatePicker control only cares about the date-related components).

API Proposal

I'll flesh this out when I have more time.

public interface IDate
{
  int Day;
  int Month;
  int Year;
}

public interface IDateTime
{
  int Day;
  int Month;
  int Year;
  int Hour;
  int Minute;
  int Second;
}

public interface ITime
{
  int Hour;
  int Minute;
  int Second;
}

API Usage

TBD

Alternative Designs

It needs to be discussed:

1. Whether to call these interfaces IDateOnly and ITimeOnly instead and model them almost entirely based on DateOnly and TimeOnly. Then IDateTime will simply be a union of the two interfaces.
2. The specific members to include in ITimeOnly are debatable. Should this be only high-level hours/minutes/seconds (all that usually needed for general-purpose or UI code) or should it include all members down to ticks. The answer is likely all members down to ticks. However, some 3rd party libraries may not support all these members. Therefore, there could be multiple levels to these interfaces like what was done for INumber. Basically IBasicTimeOnly with only hours/minutes/seconds and then an ITimeOnly that derives from that and includes everything.

Risks

This seems low risk to me as it is only abstracting common, shared properties already used in all the types.

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

[danmoseley]

Would something like nodatime be expected to expose it too?
@mattjohnsonpint

[robloo]

@danmoseley Yes, I was thinking of NodaTime specifically when I mentioned 3rd party libraries.

[tarekgh]

What exactly is your scenario here? Can you describe the details of the problem you are trying to solve here and how the proposal will solve it? Having some code examples will help here.

We have exposed TimeProvider for time abstraction in general.

This issue has been marked needs-author-action and may be missing some important information.

[robloo]

@tarekgh I'm not sure why you immediately flagged this as needs authors attention. It also is unexpected that you don't recognize the utility of this. It seems obvious as explained above and the thinking is the same as INumber.

What exactly is your scenario here?

I explained the background of the scenario above. We have too many Date/Time types and it's difficult to manage the types in both backends and frontends in a general-purpose way.

I would also advise you to speak internally with the team that developed the INumber interface. Their reasons for doing so are the same as I'm proposing here.

Can you describe the details of the problem you are trying to solve here and how the proposal will solve it?

Yes, this originates here: AvaloniaUI/Avalonia#13480. In developing UI controls the underlying date/time type has become an issue. Old controls in WPF used DateTime new controls in WinUI use DateTimeOffset. However, each is only to select a date and really should be using DateOnly but that didn't exist until recently. This creates a problem for app developers that now need to manage two different types (DateTime or DateTimeOffset) as well as their nullability. We need to clean all of this up and just let the app developer specify the type they want to use. These controls can operate on anything (generally speaking) as long as it has Year/Month/Day components to increment/decrement.

Long term you really need to remove DateTime, add a time zone ID component to DateTimeOffset and then use DateTimeOffset internally for all APIs. That will likely never happen though and is out of scope for this discussion.

We have exposed TimeProvider for time abstraction in general.

This is irrelevant. I'm not talking about providing time. I'm talking about making general-purpose code that can edit/modify any date/time types. I was clear about that above.