API Proposal: Add OffsetMinutes to DateTimeOffset

[JeremyKuhne]

Background and Motivation

In advanced DateTimeOffset scenarios, getting fast access to whether or not the DateTimeOffset has an offset and what it is in minutes is very useful.

Proposed API

namespace System
{
    public readonly struct DateTimeOffset
	{
	   // Existing field
	   private readonly short _offsetMinutes;
	   
           // Not adding per discussion below
+	   // public bool IsUtc => _offsetMinutes == 0;
+	   public int TotalOffsetMinutes => _offsetMinutes; 
	}
}

Usage Examples

Before

        public Value(DateTimeOffset value)
        {
            this = default;
            TimeSpan offset = value.Offset;
            if (offset.Ticks == 0)
            {
                // This is a UTC time
                _union.Ticks = value.Ticks;
                _object = TypeFlags.DateTimeOffset;
            }
            else if (PackedDateTimeOffset.TryCreate(value, offset, out var packed))
            {
                _union.PackedDateTimeOffset = packed;
                _object = TypeFlags.PackedDateTimeOffset;
            }
            else
            {
                _object = value;
            }
        }

After

        public Value(DateTimeOffset value)
        {
            this = default;
            int offset = value.TotalOffsetMinutes;
            if (offset == 0)
            {
                // This is a UTC time
                _union.Ticks = value.Ticks;
                _object = TypeFlags.DateTimeOffset;
            }
            else if (PackedDateTimeOffset.TryCreate(value, offset, out var packed))
            {
                _union.PackedDateTimeOffset = packed;
                _object = TypeFlags.PackedDateTimeOffset;
            }
            else
            {
                _object = value;
            }
        }

Related to this, DateTimeOffset.Ticks could be calling an internal constructor to avoid the checks in DateTime. That isn't public surface area, but worth mentioning.

cc: @KrzysztofCwalina, @tarekgh, @lonitra

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.

[GrabYourPitchforks]

FWIW, if we did this, I'd want OffsetMinutes to be typed as int, not short. Makes the API a bit easier to use, and it allows us to change the internal implementation to int in the future as a perf optimization.

Tagging subscribers to this area: @tannergooding
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and Motivation

In advanced DateTimeOffset scenarios, getting fast access to whether or not the DateTimeOffset has an offset and what it is in minutes is very useful.

Proposed API

namespace System
{
    public readonly struct DateTimeOffset
	{
	   // Existing field
	   private readonly short _offsetMinutes;
	   
+	   public bool IsUTC => _offsetMinutes == 0;
+	   public short OffsetMinutes => _offsetMinutes; 
	}
}

Usage Examples

Before

        public Value(DateTimeOffset value)
        {
            this = default;
            TimeSpan offset = value.Offset;
            if (offset.Ticks == 0)
            {
                // This is a UTC time
                _union.Ticks = value.Ticks;
                _object = TypeFlags.DateTimeOffset;
            }
            else if (PackedDateTimeOffset.TryCreate(value, offset, out var packed))
            {
                _union.PackedDateTimeOffset = packed;
                _object = TypeFlags.PackedDateTimeOffset;
            }
            else
            {
                _object = value;
            }
        }

After

        public Value(DateTimeOffset value)
        {
            this = default;
            if (value.IsUTC)
            {
                // This is a UTC time
                _union.Ticks = value.Ticks;
                _object = TypeFlags.DateTimeOffset;
            }
            else if (PackedDateTimeOffset.TryCreate(value, value.OffsetMinutes, out var packed))
            {
                _union.PackedDateTimeOffset = packed;
                _object = TypeFlags.PackedDateTimeOffset;
            }
            else
            {
                _object = value;
            }
        }

Related to this, DateTimeOffset.Ticks could be calling an internal constructor to avoid the checks in DateTime. That isn't public surface area, but worth mentioning.

cc: @KrzysztofCwalina, @tarekgh, @lonitra

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

[tarekgh]

I think if we expose OffsetMinutes, we'll not need IsUtc.

[tarekgh]

Also, why thinking using DateTimeOffset.Offset would not be good here? the check will be if (value.Offset == TimeSpan.Zero)`.

I am not seeing much value exposing Offset.Minutes as we already have DateTimeOffset.Offset property which is giving everything we need.

[JeremyKuhne]

I am not seeing much value exposing Offset.Minutes as we already have DateTimeOffset.Offset property which is giving everything we need.

It is about performance, not functionality. Creating a TimeSpan is a significant amount of work:

        public TimeSpan(int hours, int minutes, int seconds)
        {
            _ticks = TimeToTicks(hours, minutes, seconds);
        }

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        internal static long TimeToTicks(int hour, int minute, int second)
        {
            // totalSeconds is bounded by 2^31 * 2^12 + 2^31 * 2^8 + 2^31,
            // which is less than 2^44, meaning we won't overflow totalSeconds.
            long totalSeconds = (long)hour * 3600 + (long)minute * 60 + (long)second;
            if (totalSeconds > MaxSeconds || totalSeconds < MinSeconds)
                ThrowHelper.ThrowArgumentOutOfRange_TimeSpanTooLong();
            return totalSeconds * TicksPerSecond;
        }

That is a lot of work for checking _offsetMinutes == 0. In my case I'm also trying to pack the raw data and I need minutes, not ticks. It is quite measurable in my Value prototype which is currently being used by Azure.

[tarekgh]

That is a lot of work for checking _offsetMinutes == 0. In my case I'm also trying to pack the raw data and I need minutes, not ticks. It is quite measurable in my Value prototype which is currently being used by Azure.

This can be optimized in the implementation by creating TimeSpan(_offsetMinutes * TicksPerMinute) and bypass all checks.

[JeremyKuhne]

This can be optimized in the implementation by creating TimeSpan(_offsetMinutes * TicksPerMinute) and bypass all checks.

That is better, but still suboptimal, as I'm still getting out the minutes again.

[Clockwork-Muse]

It is about performance, not functionality. Creating a TimeSpan is a significant amount of work

... but TimeSpan.Zero is a static property... ?

As an aside DateTimeOffset.Offset == TimeSpan.Zero does not mean that that particular DateTimeOffset actually represents a date/time value in Utc. An equivalent instant, sure. However there are other time zones that have zero offsets.

[tarekgh]

but still suboptimal, as I'm still getting out the minutes again.

Accessing the minutes from the offset is not that expensive I guess public int Minutes => (int)((_ticks / TicksPerMinute) % 60);. you can cache the minutes from the offset if you are going to use it more than one time.

[GrabYourPitchforks]

FWIW, here's the current codegen for static int TotalMinutes(DateTimeOffset o) => (int)o.Offset.TotalMinutes;:

C.TotalMinutes(System.DateTimeOffset)
    L0000: sub rsp, 0x28
    L0004: vzeroupper
    L0007: movsx rax, word ptr [rcx]
    L000b: movsxd rax, eax
    L000e: imul rax, 0x3c
    L0012: mov rdx, 0xd6bf94d5e5
    L001c: cmp rax, rdx
    L001f: jg short L0051
    L0021: mov rdx, 0xffffff29406b2a1b
    L002b: cmp rax, rdx
    L002e: jl short L0051
    L0030: imul rax, 0x989680
    L0037: vxorps xmm0, xmm0, xmm0
    L003b: vcvtsi2sd xmm0, xmm0, rax
    L0040: vdivsd xmm0, xmm0, [C.TotalMinutes(System.DateTimeOffset)]
    L0048: vcvttsd2si eax, xmm0
    L004c: add rsp, 0x28
    L0050: ret
    L0051: call 

Edit: Had to fix my codegen above since I was calling get_Minutes instead of get_TotalMinutes.

[JeremyKuhne]

Accessing the minutes from the offset is not that expensive I guess public int Minutes => (int)((_ticks / TicksPerMinute) % 60);. you can cache the minutes from the offset if you are going to use it more than one time.

The issue I have is not getting it out multiple times, it is getting it out for many DateTimeOffset instances. This is code that is already in Azure and is intended to be used more broadly there.