[API Proposal]: DateTimeOffset and TimeSpan mod

[Thaina]

Background and motivation

For simplifying calculation of datetime and timespan without some fraction or calculate cron repeat I would like to suggest adding % operator for DateTimeOffset and TimeSpan (DateTime too ?)

API Proposal

namespace System;

public class DateTimeOffset
{
    public static DateTimeOffset operator %(DateTimeOffset dateTimeOffset, TimeSpan timeSpan)
    {
          return dateTimeOffset - TimeSpan.FromTicks(dateTimeOffset.Ticks % timeSpan.Ticks);
    }
}

public class TimeSpan 
{
    public static TimeSpan operator %(TimeSpan left, TimeSpan right)
    {
          return left - TimeSpan.FromTicks(left.Ticks % right.Ticks);
    }
}

API Usage

Console.WriteLine(DateTimeOffset.Now.TimeOfDay); // 08:53:12.4048276
Console.WriteLine((DateTimeOffset.Now % TimeSpan.FromSeconds(1))).TimeOfDay); // 08:53:12
Console.WriteLine((DateTimeOffset.Now % TimeSpan.FromSeconds(5))).TimeOfDay); // 08:53:10
Console.WriteLine((DateTimeOffset.Now % TimeSpan.FromMinutes(1))).TimeOfDay); // 08:53:00

Alternative Designs

var now = DateTimeOffset.Now;
now -= TimeSpan.FromTicks(now.Ticks % TimeSpan.FromSeconds(5).Ticks);

Risks

No response

[dotnet-policy-service]

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

[huoyaoyuan]

What if the TimeSpan is not a divisor of a day? Date&time is at interval scale, not ratio scale. There is no meaningful zero point of time. The year 0001 of Gregorian calendar or Jan 1 of each year is just an artificial point.

[Thaina]

@huoyaoyuan 1 - I don't think that kind of use case is of concerning since that was the very uncommon use case. It should not be used in general. Why you want to do that?

2 - I also don't think it could be a problem because in the end both struct was actually abstraction over long Tick And the date/month/year was just culture intepretation derived from Tick. If there is culture that has modulo arithmetic of other timescale then it's up to them to define timespan over it and intepret what time of them from the Ticks relative to common dateTime

[huoyaoyuan]

I don't think that kind of use case is of concerning since that was the very uncommon use case. It should not be used in general. Why you want to do that?

The value needs to be well defined.

I also don't think it could be a problem because in the end both struct was actually abstraction over long Tick And the date/month/year was just culture intepretation derived from Tick.

Tick is an implementation detail. It doesn't contribute to the semantic of DateTime. The zero point of tick is arbitrary and can differ among different time APIs, for example 1970-01-01 and 1601-01-01.

[Thaina]

@huoyaoyuan The zero point of tick is well defined under dotnet runtime system for DateTime and DateTimeOffSet object and unrelated to other system. It's up to other system to consider modulo arithmetic of their own object. And they better use mod of TimeSpan relative to their starting point instead of DateTime and DateTimeOffSet or implement their own object with specific starting point for 0 tick if it differ from 12:00:00 midnight, January 1, 0001 Anno Domini https://learn.microsoft.com/en-us/dotnet/api/system.datetimeoffset?view=net-10.0

[huoyaoyuan]

It's up to other system to consider modulo arithmetic of their own object.

Any system with modulo arithmetic can define the modulo operation. DateTimeOffset doesn't have modulo defined.

[Thaina]

@huoyaoyuan I am expecting people would defined their own modulo operation between their own datetime and TimeSpan. DateTimeOffset is basic system that would be a starting point

[hez2010]

% only has clear semantics on ratio‑scale values with a meaningful zero. TimeSpan is interval‑scale, and DateTimeOffset represents an absolute point in time, so there’s no single intuitive definition of modulo for these types.
Since built‑in operators must have unambiguous, broadly applicable behavior, it’s hard to justify adding % here. If a specific modulo interpretation is useful for your scenario, you can already define it using extensions for your own domain of use.

Console.WriteLine(DateTimeOffset.Now.TimeOfDay); // 08:53:12.4048276
Console.WriteLine((DateTimeOffset.Now % TimeSpan.FromSeconds(1)).TimeOfDay); // 08:53:12
Console.WriteLine((DateTimeOffset.Now % TimeSpan.FromSeconds(5)).TimeOfDay); // 08:53:10
Console.WriteLine((DateTimeOffset.Now % TimeSpan.FromMinutes(1)).TimeOfDay); // 08:53:00

public static class Extensions
{
    extension(DateTimeOffset)
    {
        public static DateTimeOffset operator %(DateTimeOffset dateTimeOffset, TimeSpan timeSpan)
        {
            return dateTimeOffset - TimeSpan.FromTicks(dateTimeOffset.Ticks % timeSpan.Ticks);
        }
    }

    extension(TimeSpan)
    {
        public static TimeSpan operator %(TimeSpan left, TimeSpan right)
        {
            return left - TimeSpan.FromTicks(left.Ticks % right.Ticks);
        }
    }
}

[Thaina]

As I have stated. DateTimeOffset clearly has a meaningful zero. new DateTimeOffset() is

No matter what other system define their own Zero, dotnet BCL always define zero of DateTimeOffset as 0 second of 01/01/0000

There is discussion that we should implement partially INumber interface to TimeSpan and DateTime #76225 And if there would be AdditionIdentity of DateTime that would be a new DateTime

[tarekgh]

DateTimeOffset represents an absolute point in time, so there’s no single intuitive definition of modulo for these types.

@Thaina I fully agree with @hez2010. Exposing an operation like this would be quite confusing in terms of what it actually means and what the result represents. As @hez2010 pointed out, you can always define your own extension method to support a specific scenario. If we ever decide to support a particular scenario directly, it should be exposed as an explicit method that clearly represents that operation to avoid any ambiguity. We can monitor demand for such scenarios and consider adding support if and when it becomes necessary.