DateOnly should have a matching Span type

[DrkWzrd]

Background and Motivation

I apologize in advance for my English.

TimeSpan is fine, but managing big time spans (years, months) with it (or, in the worst case, with DateTime struct) is so frustrating (and in DateTime case, incoherent). In real world there are so many scenarios where we use larger time spans than just a few days.

Therefore, I think DateOnly introduction should be accompanied with a DateSpan type (because I understand adding APIs like Months, or Years to TimeSpan should not be right). making computations with DateOnly easier, and more clear and straightforward when we are developing.

And DateOnly has this APIs, but separated in every field (days, months and years), and are backed by DateTime internally, but I think we need a structure to represent that, a DateSpan. a Date"Period" (something like TimeSpan, but with bigger concepts like weeks, months and years; like NodaTime Period).

E.g.: if i talk with someone about an appointment in "3 months" or "2 weeks", or "4 years" this numbers are so big to manage it in days values with TimeSpan. In addition, if we are working with DateOnly types, it doesn't make sense to use an XXXXSpan struct which accepts values smaller than days.

With this struct should be able to operate with DateOnly types (e.g.: operators like +, -, etc are not included right now).

Proposed API

    namespace System
    {
        public readonly struct DateSpan : IEquatable<DateSpan>, IFormattable, IComparable, IComparable<DateSpan>
        {

            public static DateSpan MinValue { get { throw null; } }
            public static DateSpan MaxValue { get { throw null; } }

            public int Days { get { throw null; } }
            public int Months { get { throw null; } }
            public int Years { get { throw null; } }

            public int TotalDays { get { throw null; } } //the lesser unit allowed should be days, then total days can be an integer
            public double TotalMonths { get { throw null; } }
            public double TotalYears { get { throw null; } }

            public int CompareTo(DateSpan other) { throw new NotImplementedException(); }
            public int CompareTo(object obj) { throw new NotImplementedException(); }
            public bool Equals(DateSpan other) { throw new NotImplementedException(); }
            public string ToString(string format, IFormatProvider formatProvider) { throw new NotImplementedException(); }

            public static DateSpan operator +(DateSpan ds1, DateSpan ds2) { throw null; }
            public static DateSpan operator -(DateSpan ds1, DateSpan ds2) { throw null; }

            public static implicit operator TimeSpan(DateSpan ds1) { throw null; } //something like this:  return new TimeSpan(ds1.TotalDays, 0, 0, 0, 0);
            public static implicit operator DateSpan(TimeSpan ts1) { throw null; }
        }

    }

Usage Examples

This API should allow this new operators

    public struct DateOnly
    {
        public static DateSpan operator -(DateOnly do1, DateOnly do2) { throw null; }

        public static DateOnly operator +(DateOnly do1, DateSpan ds1) { throw null; }
    }

    public struct DateTime
    {
        public static DateSpan operator -(DateTime dt1, DateTime dt2) { throw null; }
        public static DateTime operator +(DateTime dt1, DateSpan ds1) { throw null; }
    }

Risks

The one main risk I can see is the confusion of usage between TimeSpan and DateSpan. But I'm sure there are a lot I haven't thought.

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

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

Issue Details

---

Background and Motivation

I apologize in advance for my English.

TimeSpan is fine, but managing big time spans (years, months) with it (or, in the worst case, with DateTime struct) is so frustrating (and in DateTime case, incoherent). In real world there are so many scenarios where we use larger time spans than just a few days.

Therefore, I think DateOnly introduction should be accompanied with a DateSpan type (because I understand adding APIs like Months, or Years to TimeSpan should not be right). making computations with DateOnly easier, and more clear and straightforward when we are developing.

And DateOnly has this APIs, but separated in every field (days, months and years), and are backed by DateTime internally, but I think we need a structure to represent that, a DateSpan. a Date"Period" (something like TimeSpan, but with bigger concepts like weeks, months and years; like NodaTime Period).

E.g.: if i talk with someone about an appointment in "3 months" or "2 weeks", or "4 years" this numbers are so big to manage it in days values with TimeSpan. In addition, if we are working with DateOnly types, it doesn't make sense to use an XXXXSpan struct which accepts values smaller than days.

With this struct should be able to operate with DateOnly types (e.g.: operators like +, -, etc are not included right now).

Proposed API

    namespace System
    {
        public readonly struct DateSpan : IEquatable<DateSpan>, IFormattable, IComparable, IComparable<DateSpan>
        {

            public static DateSpan MinValue { get { throw null; } }
            public static DateSpan MaxValue { get { throw null; } }

            public int Days { get { throw null; } }
            public int Months { get { throw null; } }
            public int Years { get { throw null; } }

            public int TotalDays { get { throw null; } } //the lesser unit allowed should be days, then total days can be an integer
            public double TotalMonths { get { throw null; } }
            public double TotalYears { get { throw null; } }

            public int CompareTo(DateSpan other) { throw new NotImplementedException(); }
            public int CompareTo(object obj) { throw new NotImplementedException(); }
            public bool Equals(DateSpan other) { throw new NotImplementedException(); }
            public string ToString(string format, IFormatProvider formatProvider) { throw new NotImplementedException(); }

            public static DateSpan operator +(DateSpan ds1, DateSpan ds2) { throw null; }
            public static DateSpan operator -(DateSpan ds1, DateSpan ds2) { throw null; }

            public static implicit operator TimeSpan(DateSpan ds1) { throw null; } //something like this:  return new TimeSpan(ds1.TotalDays, 0, 0, 0, 0);
            public static implicit operator DateSpan(TimeSpan ts1) { throw null; }
        }

    }

Usage Examples

This API should allow this new operators

    public struct DateOnly
    {
        public static DateSpan operator -(DateOnly do1, DateOnly do2) { throw null; }

        public static DateOnly operator +(DateOnly do1, DateSpan ds1) { throw null; }
    }

    public struct DateTime
    {
        public static DateSpan operator -(DateTime dt1, DateTime dt2) { throw null; }
        public static DateTime operator +(DateTime dt1, DateSpan ds1) { throw null; }
    }

Risks

The one main risk I can see is the confusion of usage between TimeSpan and DateSpan. But I'm sure there are a lot I haven't thought.

Author:	DrkWzrd
Assignees:	-
Labels:	api-suggestion, area-System.Runtime, untriaged
Milestone:	-

[Clockwork-Muse]

In real world there are so many scenarios where we use larger time spans than just a few days.

The real concern isn't the length of time, it's the fact that years/months have a varying number of days (and thus hours/minutes/seconds). In contrast, TimeSpan represents an exact duration. NodaTime (and JodaTime/JSR310) refer to this as a Period, although the name isn't terribly important overall.

[DrkWzrd]

@Clockwork-Muse I know months and years are variable length elements, but that not invalidate my argument. In fact, 'Period' from NodaTime has APIs for 'Weeks', 'Months' and 'Years' for example. And I understand TimeSpan is a "not editable" API (that's why I suggest a new-not incompatible API), and the computations made by 'Period' and 'TimeSpan' are like night and day.

My point is "if we have a DateOnly API we should have a API representing Span between two DateOnlys, and TimeSpan for that case could be... not convenient in a lot of cases".

The name is irrelevant, I chose it because already exists something similar (but not equal) in .net: TimeSpan

[Clockwork-Muse]

public int TotalDays { get { throw null; } } 
public double TotalMonths { get { throw null; } }
public double TotalYears { get { throw null; } }

These rely heavily on normalization, and in particular any of them will give wildly incorrect values if any of the properties are large enough.

public static implicit operator TimeSpan(DateSpan ds1) { throw null; } //something like this:  return new TimeSpan(ds1.TotalDays, 0, 0, 0, 0);
public static implicit operator DateSpan(TimeSpan ts1) { throw null; }

These are actively dangerous, because the values you get this way can (and almost always will) be wildly different than the existing codepaths. You're essentially reinventing DB2's TIMESTAMPDIFF, and that has problems.

public struct DateTime
{
    public static DateSpan operator -(DateTime dt1, DateTime dt2) { throw null; }
}

This isn't possible to implement, since there's an existing subtraction operator with this signature.

I know months and years are variable length elements, but that not invalidate my argument.

I'm not disagreeing about that it's a useful type. What I'm getting at is that "amount in TimeSpan" is not a relevant argument in favor of the type, as opposed to more natural "relative" offsets.

[DrkWzrd]

@Clockwork-Muse Maybe the API can (or must) include a reference to a concrete Calendar or require it in one of the ctors and do the numbers around it (just like DateOnly).

[KalleOlaviNiemitalo]

Let's say you have

• DateTime dt2 for February 1, 2000
• DateSpan ds1m for one month
• DateSpan ds30d for 30 days

Then, I think the result of dt2 + ds1m should be March 1, 2000, because that's what dt2.AddMonths(1) returns. dt2 + ds30d should be is March 2, 2000, like dt2.AddDays(30). Right?

What should ds1m.TotalDays return? The difference between February 1 and March 1 is 29 days but ds1m does not know that the month is February and the year is a leap year. Perhaps TotalDays would have to always translate 1 month to the same number of days (e.g. 30 days). I doubt such a property would be useful for applications.

What should ds1m.Equals(ds30d) return? I think false because dt2 + ds1m is March 1 but dt2 + ds30d is March 2.

What should ds1m.CompareTo(ds30d) return? If it returns 0 just because both ds1m.TotalDays and ds30d.TotalDays are 30, that seems a bit inconsistent with Equals. Such a comparison could still be useful for sorting date spans in a user interface, though.

[Clockwork-Muse]

Basically, what @KalleOlaviNiemitalo is saying about the TotalX properties is what the problems end up being, and what the issue with TIMESTAMPDIFF ends up being for DB2.

Maybe the API can (or must) include a reference to a concrete Calendar or require it in one of the ctors and do the numbers around it (just like DateOnly).

Given ease of implementation, expected use patterns, and the rest of the shape of the API, I expect by default it wouldn't take Calendar.

What should ds1m.Equals(ds30d) return? I think false because dt2 + ds1m is March 1 but dt2 + ds30d is March 2.

What should ds1m.CompareTo(ds30d) return? If it returns 0 just because both ds1m.TotalDays and ds30d.TotalDays are 30, that seems a bit inconsistent with Equals. Such a comparison could still be useful for sorting date spans in a user interface, though.

The only "proper" way to implement a type like this is to have individual fields. Equals would work off the individual fields.
I didn't really think about it, but neither of the equivalent types in Java and NodaTime implement a comparing interface, which makes sense given the issue you mention. That aside, if it was implemented I'd probably just strictly sort on YMD, since in most cases this will return the expected ordering (since in most cases M < 12, D < 31).

[daiplusplus]

I agree that DateOnly should ship with DateSpan (or similar), otherwise it's going to leave another awkward void in the API (though I am very pleased that we finally have a real date type built-in to the framework, and hopefully 1:1 support for database date types too?)

In my own private utility library I have a Date struct that's similar to DateOnly in that it wraps a DateTime value (it also has an int ExcelSerial property that is aware of the 1904 problem...), and for my DateSpan type I implemented it as a simple tuple over Date from, Int32 daysLength representing the signed number of days from from. This does mean that it only offers simple operations over integral days - with no consideration towards weeks, months, or years (well, it does have an IsoWeeks count and float ApproxYears, but that's not what most people are after, I assume).

@DrkWzrd I like your idea to use require a Calendar reference to allow for month and year arithmetic, I think I'll steal that idea for my own library :)