[API Proposal]: method overload `DateTimeOffset.Equals(DateTimeOffset other, TimeSpan margin)`

[alexandrehtrb]

Background and motivation

Currently, it is difficult in .NET to compare equality of DateTime(Offset) when parts need to be ignored, such as milliseconds and seconds. Check this Stack Overflow question.

API Proposal

Same for TimeSpan, DateTime and DateTimeOffset. EqualsExact would also have this overload, but considering TimeZoneOffset / DateTimeKind too.

namespace System;

public readonly struct DateTimeOffset
{
    public bool Equals(DateTimeOffset other, TimeSpan margin);
}

API Usage

var dt = DateTime.Parse("Wed, 21 Oct 2015 07:28:00 GMT");
TimeSpan margin1ms = TimeSpan.FromMilliseconds(1.0),
         margin1s = TimeSpan.FromSeconds(1.0),
         margin1min = TimeSpan.FromMinutes(1.0);

if (DateTime.Now.Equals(dt, margin1ms))
{
  Console.WriteLine("Same date and time, up to milliseconds precision");
}
else if (DateTime.Now.Equals(dt, margin1s))
{
  Console.WriteLine("Same date and time, up to seconds precision");
}
else if (DateTime.Now.Equals(dt, margin1min))
{
  Console.WriteLine("Same date and time, up to minutes precision");
}

Alternative Designs

Open for suggestions.

Risks

I don't see any, at first sight.

[dotnet-policy-service]

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

[MichalPetryka]

I wonder if exposing some DateTimeOffset.Truncate method for this instead would make more sense.

[Clockwork-Muse]

...As a point of personal preference, date/time values should generally be considered equivalent to floating point (yes, it's generally exactly representable, but due to the measurement nature you can still end up with odd values). This tends to make me want to encourage one of two general behaviors:

• Explicit range comparisons and striding, especially for bucketing. Instead of performing an equality comparison as here, in many cases it will be preferrable to construct ranges (of the form lower-bound inclusive, upper-bound exclusive), and checking whether a value is in that range. Especially at larger units this is generally how the domain is actually being used (eg, bucketing for an hourly report) - and note that it works correctly for all units, including years.
• Equals with an "ulp", as how floats are compared. In some small number of cases (possibly only when dealing with smaller units), it may be more beneficial to compare with an ulp; consider that at smaller units especially there is a high likelihood the values you're interested in may be on the "wrong side" of the unit boundary.

[alexandrehtrb]

checking whether a value is in that range

I think this is already covered by today, isn't it? Like:

var dt = DateTime.Parse("Wed, 21 Oct 2015 07:28:00 GMT");
bool isToday = DateTime.Today <= dt && dt < DateTime.Today.AddDays(1.0);

Equals with an "ulp"

Is an "ulp" an error margin? Then the API would be something like:

public readonly struct DateTimeOffset
{
    public bool Equals(DateTimeOffset other, TimeSpan margin);
}

I like this latter option too.

[Clockwork-Muse]

Yes... but I'm hesitant to use a type that would exclude years or months, just on general principle.

[alexandrehtrb]

Yes... but I'm hesitant to use a type that would exclude years or months, just on general principle.

I think that using a DateTimeComparison enum would be a better option for most cases. If we use adopt a method with TimeSpan margin, the programmer would have to allocate this margin, which is more work for him / her; but if we adopt an enum, then no need for that. The enum also would solve the problem you mentioned - considering up to years, months, etc.

[Clockwork-Muse]

The problem is that the proposed enum is generally too coarse. For instance, it doesn't allow for comparisons at a 10ms boundary... and that assumes that, especially at smaller measurements, truncation is the desired behavior. For instance, the historical "step" of consumer computer clocks was ~15ms, and there wasn't much control over when the value was for. Certain historical file times are limited to 2s precision. Things like that.

[julealgon]

What about providing both overloads @Clockwork-Muse ? The enum-based one for simpler, more common scenarios, and the TimeSpan one for more advanced, specific ones?

[Clockwork-Muse]

The problem is that the "more advanced" one has different behavior.

The proposed one truncates and buckets to the specified (very coarse) precision.
The "more advanced" one actually does an absolute difference comparison (since the other value may be on the other side of the boundary).

Again, if the truncating/bucketing behavior is what you want, then from an application/domain design perspective probably you should be starting from the bucket (Eg, as if from an SQL calendar table) and stride the ranges. Note that in the majority of such cases, you're going to have the bounds anyways (you're not going to be comparing two arbitrary precision values).

If you want "close to" values for arbitrary precision values, then you need an "error range", which means you need an absolute difference comparison, which this does not provide.

the programmer would have to allocate this margin, which is more work for him / her; but if we adopt an enum, then no need for that.

This is mostly a non-issue.

1. The type is a struct, so there are no literal allocations (although there are constructor costs).
2. At scale, the value can be allocated outside a loop or as a readonly static value, so the call will look effectively identical, eg;

someValue.Equals(other, TimeDifference.Within10Milliseconds);

[alexandrehtrb]

@Clockwork-Muse , what do you think of the proposal below? @julealgon said we can have both overloads.

namespace System;

public enum DateTimeComparison
{
  UpToDate,
  UpToHour,
  UpToMinutes,
  UpToSeconds,
  UpToMilliseconds,
  UpToMicroseconds,
  UpToNanoseconds
}

public readonly struct DateTimeOffset
{
    public bool Equals(DateTimeOffset other, DateTimeComparison comparisonType)
    {
        var thisTruncated = this.Truncate(comparisonType);
        var otherTruncated = other.Truncate(comparisonType);
        return thisTruncated == otherTruncated;
    }

    public bool Equals(DateTimeOffset other, TimeSpan margin)
    {
        var diffTicks = Math.Abs((this - other).Ticks);
        var marginTicks = Math.Abs(margin.Ticks);
        return diffTicks <= marginTicks;
    }
}