This documentation is archived and is not being maintained.

How to: Let Users Resolve Ambiguous Times

An ambiguous time is a time that maps to more than one Coordinated Universal Time (UTC). It occurs when the clock time is adjusted back in time, such as during the transition from a time zone's daylight saving time to its standard time. When handling an ambiguous time, you can do one of the following:

  • If the ambiguous time is an item of data entered by the user, you can leave it to the user to resolve the ambiguity.

  • Make an assumption about how the time maps to UTC. For example, you can assume that an ambiguous time is always expressed in the time zone's standard time.

This topic shows how to let a user resolve an ambiguous time.

To let a user resolve an ambiguous time

  1. Get the date and time input by the user.

  2. Call the IsAmbiguousTime method to determine whether the time is ambiguous.

  3. If the time is ambiguous, call the GetAmbiguousTimeOffsets method to retrieve an array of TimeSpan objects. Each element in the array contains a UTC offset that the ambiguous time can map to.

  4. Let the user select the desired offset.

  5. Get the UTC date and time by subtracting the offset selected by the user from the local time.

  6. Call the static (Shared in Visual Basic .NET) SpecifyKind method to set the UTC date and time value's Kind property to DateTimeKind.Utc.

The following example prompts the user to enter a date and time and, if it is ambiguous, lets the user select the UTC time that the ambiguous time maps to.

Private Sub GetUserDateInput()
   ' Get date and time from user
   Dim inputDate As Date = GetUserDateTime()
   Dim utcDate As Date

   ' Exit if date has no significant value
   If inputDate = Date.MinValue Then Exit Sub

   If TimeZoneInfo.Local.IsAmbiguousTime(inputDate) Then
      Console.WriteLine("The date you've entered is ambiguous.")
      Console.WriteLine("Please select the correct offset from Universal Coordinated Time:")
      Dim offsets() As TimeSpan = TimeZoneInfo.Local.GetAmbiguousTimeOffsets(inputDate)
      For ctr As Integer = 0 to offsets.Length - 1
         Dim zoneDescription As String
         If offsets(ctr).Equals(TimeZoneInfo.Local.BaseUtcOffset) Then 
            zoneDescription = TimeZoneInfo.Local.StandardName
            zoneDescription = TimeZoneInfo.Local.DaylightName
         End If
         Console.WriteLine("{0}.) {1} hours, {2} minutes ({3})", _
                           ctr, offsets(ctr).Hours, offsets(ctr).Minutes, zoneDescription)
      Console.Write("> ")
      Dim selection As Integer = CInt(Console.ReadLine())

      ' Convert local time to UTC, and set Kind property to DateTimeKind.Utc
      utcDate = Date.SpecifyKind(inputDate - offsets(selection), DateTimeKind.Utc)

      Console.WriteLine("{0} local time corresponds to {1} {2}.", inputDate, utcDate, utcDate.Kind.ToString())
      utcDate = inputDate.ToUniversalTime()
      Console.WriteLine("{0} local time corresponds to {1} {2}.", inputDate, utcDate, utcDate.Kind.ToString())    
   End If
End Sub

Private Function GetUserDateTime() As Date
   Dim exitFlag As Boolean = False            ' flag to exit loop if date is valid
   Dim dateString As String 
   Dim inputDate As Date = Date.MinValue

   Console.Write("Enter a local date and time: ")
   Do While Not exitFlag
      dateString = Console.ReadLine()
      If dateString.ToUpper = "E" Then exitFlag = True
      If Date.TryParse(dateString, inputDate) Then
         exitFlag = true
         Console.Write("Enter a valid date and time, or enter 'e' to exit: ")
      End If

   Return inputDate        
End Function

The core of the example code uses an array of TimeSpan objects to indicate possible offsets of the ambiguous time from UTC. However, these offsets are unlikely to be meaningful to the user. To clarify the meaning of the offsets, the code also notes whether an offset represents the local time zone's standard time or its daylight saving time. The code determines which time is standard and which time is daylight by comparing the offset with the value of the BaseUtcOffset property. This property indicates the difference between the UTC and the time zone's standard time.

In this example, all references to the local time zone are made through the TimeZoneInfo.Local property; the local time zone is never assigned to an object variable. This is a recommended practice because a call to the TimeZoneInfo.ClearCachedData method invalidates any objects that the local time zone is assigned to.

This example requires:

  • That a reference to System.Core.dll be added to the project.

  • That the System namespace be imported with the using statement (required in C# code).