Export (0) Print
Expand All

TimeZoneInfo.GetAmbiguousTimeOffsets Method (DateTime)

Returns information about the possible dates and times that an ambiguous date and time can be mapped to.

Namespace:  System
Assembly:  mscorlib (in mscorlib.dll)

public TimeSpan[] GetAmbiguousTimeOffsets(
	DateTime dateTime
)

Parameters

dateTime
Type: System.DateTime

A date and time.

Return Value

Type: System.TimeSpan[]
An array of objects that represents possible Coordinated Universal Time (UTC) offsets that a particular date and time can be mapped to.

ExceptionCondition
ArgumentException

dateTime is not an ambiguous time.

The precise behavior of this method depends on the relationship between the Kind property and the TimeZoneInfo object, as the following table shows.

TimeZoneInfo object type

Kind property value

Behavior

TimeZoneInfo.Local

DateTimeKind.Local or DateTimeKind.Unspecified

Returns ambiguous time offsets for dateTime.

TimeZoneInfo.Local

DateTimeKind.Utc

Converts dateTime to the local time, and then returns ambiguous time offsets for that time.

TimeZoneInfo.Utc

Any value.

Throws an ArgumentException.

Any other time zone.

Local or DateTimeKind.Utc

Converts dateTime to the specified time zone, and then determines whether that time is ambiguous.

Any other time zone.

DateTimeKind.Unspecified

Determines whether dateTime is ambiguous in the specified time zone.

The order of TimeSpan objects in the array returned by this method is undefined. However, you can determine which element represents an offset from the time zone's standard time by comparing its value with the time zone's BaseUtcOffset property. To map an ambiguous time to a time zone's standard time, see How to: Resolve Ambiguous Times.

Notes to Callers

On Windows XP systems, this method applies only the current adjustment rule when determining whether dateTime is ambiguous if the current instance is TimeZoneInfo.Local. As a result, the method may not accurately report ambiguous time offsets for periods before the current adjustment rule came into effect. For more information, see the Notes for Callers section in the Local property.

The following example defines a method named ShowPossibleUtcTimes that uses the GetAmbiguousTimeOffsets(DateTime) method to map an ambiguous time to its possible corresponding Coordinated Universal Time (UTC) times.

private void ShowPossibleUtcTimes(DateTime ambiguousTime, TimeZoneInfo timeZone)
{
   // Determine if time is ambiguous in target time zone 
   if (! timeZone.IsAmbiguousTime(ambiguousTime))
   {
      Console.WriteLine("{0} is not ambiguous in time zone {1}.", 
                        ambiguousTime, 
                        timeZone.DisplayName);
   }
   else
   {
      // Display time and its time zone (local, UTC, or indicated by timeZone argument) 
      string originalTimeZoneName; 
      if (ambiguousTime.Kind == DateTimeKind.Utc)
         originalTimeZoneName = "UTC";
      else if (ambiguousTime.Kind == DateTimeKind.Local)
         originalTimeZoneName = "local time";
      else
         originalTimeZoneName = timeZone.DisplayName;

      Console.WriteLine("{0} {1} maps to the following possible times:", 
                        ambiguousTime, originalTimeZoneName);
      // Get ambiguous offsets 
      TimeSpan[] offsets = timeZone.GetAmbiguousTimeOffsets(ambiguousTime);
      // Handle times not in time zone of timeZone argument 
      // Local time where timeZone is not local zone 
      if ((ambiguousTime.Kind == DateTimeKind.Local) && ! timeZone.Equals(TimeZoneInfo.Local)) 
         ambiguousTime = TimeZoneInfo.ConvertTime(ambiguousTime, TimeZoneInfo.Local, timeZone);
      // UTC time where timeZone is not UTC zone    
      else if ((ambiguousTime.Kind == DateTimeKind.Utc) && ! timeZone.Equals(TimeZoneInfo.Utc))
         ambiguousTime = TimeZoneInfo.ConvertTime(ambiguousTime, TimeZoneInfo.Utc, timeZone);

      // Display each offset and its mapping to UTC 
      foreach (TimeSpan offset in offsets)
      {
         if (offset.Equals(timeZone.BaseUtcOffset))
            Console.WriteLine("If {0} is {1}, {2} UTC", ambiguousTime, timeZone.StandardName, ambiguousTime - offset);
         else
            Console.WriteLine("If {0} is {1}, {2} UTC", ambiguousTime, timeZone.DaylightName, ambiguousTime - offset);
      }
   }            
}

The method can then be called using code such as the following:

Console.WriteLine();
ShowPossibleUtcTimes(new DateTime(2007, 11, 4, 1, 0, 0), 
                     TimeZoneInfo.FindSystemTimeZoneById("Central Standard Time"));
Console.WriteLine();
ShowPossibleUtcTimes(new DateTime(2007, 11, 4, 01, 00, 00, DateTimeKind.Local), 
                     TimeZoneInfo.FindSystemTimeZoneById("Central Standard Time"));
Console.WriteLine();
ShowPossibleUtcTimes(new DateTime(2007, 11, 4, 00, 00, 00, DateTimeKind.Local), 
                     TimeZoneInfo.FindSystemTimeZoneById("Central Standard Time"));
Console.WriteLine();                     
ShowPossibleUtcTimes(new DateTime(2007, 11, 4, 01, 00, 00, DateTimeKind.Unspecified), 
                     TimeZoneInfo.FindSystemTimeZoneById("Central Standard Time"));
Console.WriteLine();
ShowPossibleUtcTimes(new DateTime(2007, 11, 4, 07, 00, 00, DateTimeKind.Utc), 
                     TimeZoneInfo.FindSystemTimeZoneById("Central Standard Time"));
//  
// This example produces the following output if run in the Pacific time zone: 
// 
//    11/4/2007 1:00:00 AM (GMT-06:00) Central Time (US & Canada) maps to the following possible times: 
//    If 11/4/2007 1:00:00 AM is Central Standard Time, 11/4/2007 7:00:00 AM UTC 
//    If 11/4/2007 1:00:00 AM is Central Daylight Time, 11/4/2007 6:00:00 AM UTC 
//        
//    11/4/2007 1:00:00 AM Pacific Standard Time is not ambiguous in time zone (GMT-06:00) Central Time (US & Canada). 
//      
//    11/4/2007 12:00:00 AM local time maps to the following possible times: 
//    If 11/4/2007 1:00:00 AM is Central Standard Time, 11/4/2007 7:00:00 AM UTC 
//    If 11/4/2007 1:00:00 AM is Central Daylight Time, 11/4/2007 6:00:00 AM UTC 
//     
//    11/4/2007 1:00:00 AM (GMT-06:00) Central Time (US & Canada) maps to the following possible times: 
//    If 11/4/2007 1:00:00 AM is Central Standard Time, 11/4/2007 7:00:00 AM UTC 
//    If 11/4/2007 1:00:00 AM is Central Daylight Time, 11/4/2007 6:00:00 AM UTC 
//        
//    11/4/2007 7:00:00 AM UTC maps to the following possible times: 
//    If 11/4/2007 1:00:00 AM is Central Standard Time, 11/4/2007 7:00:00 AM UTC 
//    If 11/4/2007 1:00:00 AM is Central Daylight Time, 11/4/2007 6:00:00 AM UTC 
//

.NET Framework

Supported in: 4.6, 4.5, 4, 3.5

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Portable Class Library

Supported in: Portable Class Library

.NET for Windows Store apps

Supported in: Windows 8

Supported in: Windows Phone 8.1

Supported in: Windows Phone Silverlight 8.1

Supported in: Windows Phone Silverlight 8

Windows Phone 8.1, Windows Phone 8, Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Show:
© 2014 Microsoft