It’s no secret that daylight savings time can wreak havoc on systems that rely heavily on dates. The system I work on is centered around recording dates and times, so naturally my co-workers and I have seen our fair share of date-related bugs. From time to time, however, we come across something that we haven’t seen before. A few weeks ago the following error message started showing up in our logs:

“The supplied DateTime represents an invalid time. For example, when the clock is adjusted forward, any time in the period that is skipped is invalid.”

This seemed very cryptic, especially since it was coming from areas of our application that are typically only concerned with capturing date-only (no explicit time component) from the user, like reports that take a “start date” and “end date” parameter. For these types of parameters we just leave off the time component when capturing the date values, so midnight is used as a “placeholder” time. How is midnight an “invalid time”?

Globalization Is Hard

Over the last couple of years our software has been rolled out to users in several countries outside of the United States, including Brazil. Brazil begins and ends daylight savings time at midnight on pre-determined days of the year. On October 16, 2011 at midnight many areas in Brazil began observing daylight savings time at which time their clocks were set forward one hour. This means that at the instant it became midnight on October 16, it actually became 1:00 AM, so any time between 12:00 AM and 12:59:59 AM never actually happened.

Because we store all date values in the database in UTC, always adjust any “local” dates provided by a user to UTC before using them as filters in a query. The error we saw was thrown by .NET when trying to convert the Brazilian local time of 2011-10-16 12:00 AM to UTC since that local time never actually existed. We hadn’t experienced this same issue with any of our US customers because the daylight savings time changes in the US occur at 2:00 AM which doesn’t conflict with our “placeholder” time of midnight.

Detecting Invalid Times

In .NET you might use code similar to the following for converting a local time to UTC:

  var localDate = new DateTime(2011, 10, 16); //2011-10-16 @ midnight
  const string timeZoneId = "E. South America Standard Time"; //Windows system timezone Id for "Brasilia" timezone.
  var localTimeZone = TimeZoneInfo.FindSystemTimeZoneById(timeZoneId);
  var convertedDate =  TimeZoneInfo.ConvertTimeToUtc(localDate, localTimeZone);

The code above throws the “invalid time” exception referenced above. We could try to detect whether or not the local time is invalid with something like this:

  var localDate = new DateTime(2011, 10, 16); //2011-10-16 @ midnight
  const string timeZoneId = "E. South America Standard Time"; //Windows system timezone Id for "Brasilia" timezone.
  var localTimeZone = TimeZoneInfo.FindSystemTimeZoneById(timeZoneId);
  if (localTimeZone.IsInvalidTime(localDate))
    localDate = localDate.AddHours(1);
  var convertedDate =  TimeZoneInfo.ConvertTimeToUtc(localDate, localTimeZone);

This code works in this particular scenario, but it hardly seems robust. It also does nothing to address the issue that can arise when dealing with the ambiguous times that fall around the end of daylight savings. When we roll the clocks back an hour they record the same hour on the same day twice in a row. To continue on with our Brazil example, on February 19, 2012 at 12:00 AM, it will immediately become February 18, 2012 at 11:00 PM all over again. In this scenario, how should we interpret February 18, 2011 11:30 PM?

Enter Noda Time

I heard about Noda Time, the .NET port of the Java library Joda Time, a little while back and filed it away in the back of my mind under the “sounds-like-it-might-be-useful-someday” category.  Let’s see how we might deal with the issue of invalid and ambiguous local times using Noda Time (note that as of this writing the samples below will only work using the latest code available from the Noda Time repo on Google Code. The NuGet package version 0.1.0 published 2011-08-19 will incorrectly report unambiguous times as being ambiguous) :

    var localDateTime = new LocalDateTime(2011, 10, 16, 0, 0); 
    const string timeZoneId = "Brazil/East";
    var timezone = DateTimeZone.ForId(timeZoneId);
    var localDateTimeMaping = timezone.MapLocalDateTime(localDateTime);

    ZonedDateTime unambiguousLocalDateTime;
    switch (localDateTimeMaping.Type)
    {
        case ZoneLocalMapping.ResultType.Unambiguous:
            unambiguousLocalDateTime = localDateTimeMaping.UnambiguousMapping;
            break;
        case ZoneLocalMapping.ResultType.Ambiguous:
            unambiguousLocalDateTime = localDateTimeMaping.EarlierMapping;
            break;
        case ZoneLocalMapping.ResultType.Skipped:
            unambiguousLocalDateTime = new ZonedDateTime(
                localDateTimeMaping.ZoneIntervalAfterTransition.Start, timezone);
            break;
        default:
            throw new InvalidOperationException(string.Format("Unexpected mapping result type: {0}", localDateTimeMaping.Type));
    }
    var convertedDateTime = unambiguousLocalDateTime.ToInstant().ToDateTimeUtc();

Let’s break this sample down:

This sample is admittedly contrived and could certainly use some refactoring, but I think it captures the general approach needed to take a local date and time and convert it to UTC with Noda Time. At first glance it might seem that Noda Time makes this “simple” code more complicated and verbose because it forces you to explicitly deal with the local date disambiguation, but I feel that the length and complexity of the Noda Time sample is proportionate to the complexity of the problem. Using TimeZoneInfo leaves you susceptible to overlooking ambiguous and skipped times that could result in run-time errors or (even worse) run-time data corruption in the form of a local date and time being adjusted to UTC incorrectly.

I should point out that this research is my first look at Noda Time and I know that I’ve only scratched the surface of its full capabilities. I also think it’s safe to say that it’s still beta software for the time being so I’m not rushing out to use it production systems just yet, but I will definitely be tinkering with it more and keeping an eye on it as it progresses.