Add BaseUtcOffset to TimeZoneInfo.AdjustmentRule.

[tarekgh]

This proposal edited to address the feedback we got in the design review

Background and Motivation

TimeZoneInfo.Adjustment provides information about a time zone adjustment, such as the transition to and from daylight saving time. every adjustment rule has a start and end dates to describe at what date and time the rule can apply. Although the rule provides the information that help convert from the local time to UTC and vice versa, but it lacks an essential information which is what is the base UTC offset for the time zone during the rule period. TimeZoneInfo originally assumed that the base UTC offset for the zone is constant and never change which is incorrect. There are zones changed the UTC offset at some point.

The proposal here is have the AdjustmentRule class provide a property telling what the base UTC offset delta of the zone during the rule start and end date is.

Proposed API

    public sealed partial class TimeZoneInfo
    {
        public sealed class AdjustmentRule : IEquatable<AdjustmentRule?>, ISerializable, IDeserializationCallback
        {
             public TimeSpan BaseUtcOffsetDelta { get; }

             public static TimeZoneInfo.AdjustmentRule CreateAdjustmentRule(
                              DateTime dateStart, 
                              DateTime dateEnd, 
                              TimeSpan daylightDelta, 
                              TimeZoneInfo.TransitionTime daylightTransitionStart, 
                              TimeZoneInfo.TransitionTime daylightTransitionEnd, 
                              TimeSpan baseUtcOffsetDelta); // this is the only added parameter compared to the other overload.
        }
    }

Usage Examples

    // On 27 March 2011, Russia moved to year-round daylight-saving time. Instead of switching between UTC+09:00 in winter and UTC+10:00 in summer, 
    // Yakutsk Time became fixed at UTC+10:00 until 2014, when it was reset back to UTC+09:00 year-round.
    TimeZoneInfo tzi = TimeZoneInfo.FindSystemTimeZoneById("Asia/Yakutsk");
    foreach (TimeZoneInfo.AdjustmentRule rule in tzi.GetAdjustmentRules())
    {
        Console.WriteLine($"Base Utc offset during the time {rule.DateStart} and {rule.DateEnd} is {tzi.BaseUtcOffset + rule.BaseUtcOffsetDelta}");
    }

[tarekgh]

CC @mattjohnsonpint

[Clockwork-Muse]

TimeZoneInfo originally assumed that the base UTC offset for the zone is constant and never change which is incorrect. There are zones changed the UTC offset at some point.

Heh. Pretty much every timezone has an offset change from local solar noon to the first discrete offset. How are you anticipating these being represented?

[tarekgh]

@Clockwork-Muse we just read the rules data from the OS. Whatever offsets giving there we'll use it. We just expose that data we read.

[terrajobst]

Video

• We probably want an overload for CreateAdjustmentRule that allows people to construct an instance with an offset
• We need to think about what this means for instances that were created without an offset. Should it be nullable?

namespace System
{
   public partial class TimeZoneInfo
   {
        public partial class AdjustmentRule
        {
            public TimeSpan BaseUtcOffset { get; }
            public static AdjustmentRule CreateAdjustmentRule(
                DateTime dateStart,
                DateTime dateEnd,
                TimeSpan daylightDelta,
                TransitionTime daylightTransitionStart,
                TransitionTime daylightTransitionEnd,
                TimeSpan baseUtcOffset
            );
         }
    }
}

[mattjohnsonpint]

Agree we need parameter on CreateAdjustmentRule. Options are either TimeSpan? baseUtcOffset or TimeSpan baseUtcOffsetDelta.

[terrajobst]

• Looks good as proposed

namespace System
{
   public partial class TimeZoneInfo
   {
        public partial class AdjustmentRule
        {
            public TimeSpan BaseUtcOffsetDelta { get; }

            // Existing method:
            // public static AdjustmentRule CreateAdjustmentRule(
            //     DateTime dateStart,
            //     DateTime dateEnd,
            //     TimeSpan daylightDelta,
            //     TransitionTime daylightTransitionStart,
            //     TransitionTime daylightTransitionEnd
            // );

            public static AdjustmentRule CreateAdjustmentRule(
                DateTime dateStart,
                DateTime dateEnd,
                TimeSpan daylightDelta,
                TransitionTime daylightTransitionStart,
                TransitionTime daylightTransitionEnd,
                TimeSpan baseUtcOffsetDelta
            );
         }
    }
}