TimeZone.ToLocalTime Method (System)

ToLocalTime Method

.NET Framework Class Library

TimeZone..::.ToLocalTime Method

Returns the local time that corresponds to a specified date and time value.

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

Syntax

Visual Basic (Declaration)

Public Overridable Function ToLocalTime ( _
    time As DateTime _
) As DateTime

Visual Basic (Usage)

Dim instance As TimeZone
Dim time As DateTime
Dim returnValue As DateTime

returnValue = instance.ToLocalTime(time)

public virtual DateTime ToLocalTime(
    DateTime time
)

Visual C++

public:
virtual DateTime ToLocalTime(
    DateTime time
)

JScript

public function ToLocalTime(
    time : DateTime
) : DateTime

Parameters

time: Type: System..::.DateTime
A Coordinated Universal Time (UTC) time.

Return Value

Type: System..::.DateTime
A DateTime object whose value is the local time that corresponds to time.

Remarks

The following table shows the relationship between the time parameter and the DateTime value returned by this method.

time parameter	Behavior	Return value
A Coordinated Universal Time (UTC) time (DateTimeKind..::.Utc).	Converts the time from UTC to the local time.	A DateTime object whose value is the local time that corresponds to time.
A local time (DateTimeKind..::.Local).	No conversion necessary.	The same DateTime value represented by the time parameter.
An unspecified time (DateTimeKind..::.Unspecified).	Assumes that the time is UTC and converts it from UTC to the local time.	A DateTime object whose value is the local time that corresponds to time.

If the local time zone observes daylight saving time, ToLocalTime applies the current adjustment rule to time when performing the conversion.

Note:
The ToLocalTime method recognizes only the current daylight saving time adjustment rule for the local time zone. As a result, it is guaranteed to accurately return the local time corresponding to a particular UTC time only during the period in which the latest adjustment rule is in effect. It may return inaccurate results if time is a historic date and time value that was subject to a previous adjustment rule.

Note:

The ToLocalTime method recognizes only the current daylight saving time adjustment rule for the local time zone. As a result, it is guaranteed to accurately return the local time corresponding to a particular UTC time only during the period in which the latest adjustment rule is in effect. It may return inaccurate results if time is a historic date and time value that was subject to a previous adjustment rule.

The ToLocalTime method corresponds to the TimeZoneInfo..::.ConvertTimeFromUtc method with its destinationTimeZone parameter set to TimeZoneInfo..::.Local.

Notes to Inheritors:

Although it is not required, in most cases derived classes running under the .NET Framework version 2.0 should override the default implementation of this method. In the .NET Framework versions 1.0 and 1.1, the ToLocalTime method called the GetUtcOffset method and adjusted for daylight saving time when returning the local time. However, starting with the .NET Framework 2.0, the behavior of the default implementation depends on the Kind property of the time parameter. If its value is DateTimeKind..::.Local, this method returns time unchanged. If its value is either DateTimeKind..::.Utc or DateTimeKind..::.Unspecified, this method assumes time is UTC and converts it to the local system time without calling the GetUtcOffset method.

The following code provides a simple override of the default implementation of the ToLocalTime method. In this code, the internalTimeZone variable represents a private instance of the TimeZone class:

Visual Basic

Public Overrides Function ToLocalTime(time As Date) As Date
   If time.Kind = DateTimeKind.Local Then
      Return time
   ElseIf time.Kind = DateTimeKind.Utc Then
      Dim returnTime As New Date(time.Ticks, DateTimeKind.Local)
      returnTime += me.GetUtcOffset(returnTime)
      if internalTimeZone.IsDaylightSavingTime(returnTime) Then
         returnTime -= New TimeSpan(1, 0, 0)
      End If
      Return returnTime      
   Else
      Throw New ArgumentException("The source time zone cannot be determined.")
   End If      
End Function

public override DateTime ToLocalTime(DateTime time)
{
   if (time.Kind == DateTimeKind.Local)
   {
      return time;
   }
   else if (time.Kind == DateTimeKind.Utc)
   {
      DateTime returnTime = new DateTime(time.Ticks, DateTimeKind.Local);
      returnTime += this.GetUtcOffset(returnTime);
      if (internalTimeZone.IsDaylightSavingTime(returnTime))
         returnTime -= new TimeSpan(1, 0, 0);
      return returnTime;
   }      
   else
   {
      throw new ArgumentException("The source time zone cannot be determined.");
   }      
}

Examples

The following example uses the ToLocalTime method to return the local times that correspond to several Coordinated Universal Time (UTC) times.

Visual Basic

' Example of the TimeZone.ToLocalTime( DateTime ) and 
' TimeZone.GetUtcOffset( DateTime ) methods.
Imports System
Imports Microsoft.VisualBasic

Module UTCTimeDemo

    Sub Main( )

        Const headFmt As String = "{0,-20}{1,-20}{2,-12}{3}"

        ' Get the local time zone and a base Coordinated Universal 
        ' Time (UTC).
        Dim localZone As TimeZone = TimeZone.CurrentTimeZone
        Dim baseUTC As DateTime = new DateTime( 2000, 1, 1 )

        Console.WriteLine( "This example of " & vbCrLf & _
            "   TimeZone.ToLocalTime( DateTime ) and" & vbCrLf & _
            "   TimeZone.GetUtcOffset( DateTime ) " & vbCrLf & _
            "generates the following output, which varies " & _
            "depending on the time zone " & vbCrLf & "in which " & _
            "it is run. The example creates several Coordinated " & _
            "Universal " & vbCrLf & "Times (UTC), displays the " & _
            "corresponding local times and UTC offsets, " & _
            vbCrLf & "and shows if the times occur in daylight " & _
            "saving time (DST)." & vbCrLf )
        Console.WriteLine( "Local time: {0}" & vbCrLf, _
            localZone.StandardName )

        Console.WriteLine( headFmt, "UTC", "Local Time", _
            " Offset", "DST?" )
        Console.WriteLine( headFmt, "---", "----------", _
            " ------", "----" )

        ' Generate several UTC times.
        Dim loopX As Integer
        For loopX = 0 to 10

            ' Calculate the local time and UTC offset.
            Dim localTime As DateTime = _
                localZone.ToLocalTime( baseUTC )
            Dim localOffset As TimeSpan = _
                localZone.GetUtcOffset( localTime )

            Console.WriteLine( "{0,-20:yyyy-MM-dd HH:mm}" & _
                "{1,-20:yyyy-MM-dd HH:mm}{2,-12}{3}", _
                baseUTC, localTime, localOffset, _
                localZone.IsDaylightSavingTime( localTime ) )

            ' Advance to another UTC.
            baseUTC = baseUTC.AddDays( 155.55 )
        Next loopX
    End Sub 
End Module 

' This example of
'    TimeZone.ToLocalTime( DateTime ) and
'    TimeZone.GetUtcOffset( DateTime )
' generates the following output, which varies depending on the time zone
' in which it is run. The example creates several Coordinated Universal
' Times (UTC), displays the corresponding local times and UTC offsets,
' and shows if the times occur in daylight saving time (DST).
' 
' Local time: Pacific Standard Time
' 
' UTC                 Local Time           Offset     DST?
' ---                 ----------           ------     ----
' 2000-01-01 00:00    1999-12-31 16:00    -08:00:00   False
' 2000-06-04 13:12    2000-06-04 06:12    -07:00:00   True
' 2000-11-07 02:24    2000-11-06 18:24    -08:00:00   False
' 2001-04-11 15:36    2001-04-11 08:36    -07:00:00   True
' 2001-09-14 04:48    2001-09-13 21:48    -07:00:00   True
' 2002-02-16 18:00    2002-02-16 10:00    -08:00:00   False
' 2002-07-22 07:12    2002-07-22 00:12    -07:00:00   True
' 2002-12-24 20:24    2002-12-24 12:24    -08:00:00   False
' 2003-05-29 09:36    2003-05-29 02:36    -07:00:00   True
' 2003-10-31 22:48    2003-10-31 14:48    -08:00:00   False
' 2004-04-04 12:00    2004-04-04 05:00    -07:00:00   True

// Example of the TimeZone.ToLocalTime( DateTime ) and 
// TimeZone.GetUtcOffset( DateTime ) methods.
using System;

class UTCTimeDemo
{
    static void Main( )
    {
        const string headFmt = "{0,-20}{1,-20}{2,-12}{3}";

        // Get the local time zone and a base Coordinated Universal 
        // Time (UTC).
        TimeZone localZone = TimeZone.CurrentTimeZone;
        DateTime baseUTC = new DateTime( 2000, 1, 1 );

        Console.WriteLine( "This example of \n" +
            "   TimeZone.ToLocalTime( DateTime ) and\n" +
            "   TimeZone.GetUtcOffset( DateTime ) \ngenerates the " +
            "following output, which varies depending on the time " +
            "zone \nin which it is run. The example creates several " +
            "Coordinated Universal \nTimes (UTC), displays the " +
            "corresponding local times and UTC offsets, \nand shows " +
            "if the times occur in daylight saving time (DST)." );
        Console.WriteLine( "\nLocal time: {0}\n", 
            localZone.StandardName );

        Console.WriteLine( headFmt, "UTC", "Local Time", 
            " Offset", "DST?" );
        Console.WriteLine( headFmt, "---", "----------", 
            " ------", "----" );

        // Generate several UTC times.
        for( int loopX = 0; loopX <= 10; loopX++ )
        {
            // Calculate the local time and UTC offset.
            DateTime localTime = localZone.ToLocalTime( baseUTC );
            TimeSpan localOffset = 
                localZone.GetUtcOffset( localTime );

            Console.WriteLine( "{0,-20:yyyy-MM-dd HH:mm}" +
                "{1,-20:yyyy-MM-dd HH:mm}{2,-12}{3}", 
                baseUTC, localTime, localOffset, 
                localZone.IsDaylightSavingTime( localTime ) );

            // Advance to another UTC.
            baseUTC = baseUTC.AddDays( 155.55 );
        }
    } 
} 

/*
This example of
   TimeZone.ToLocalTime( DateTime ) and
   TimeZone.GetUtcOffset( DateTime )
generates the following output, which varies depending on the time zone
in which it is run. The example creates several Coordinated Universal
Times (UTC), displays the corresponding local times and UTC offsets,
and shows if the times occur in daylight saving time (DST).

Local time: Pacific Standard Time

UTC                 Local Time           Offset     DST?
---                 ----------           ------     ----
2000-01-01 00:00    1999-12-31 16:00    -08:00:00   False
2000-06-04 13:12    2000-06-04 06:12    -07:00:00   True
2000-11-07 02:24    2000-11-06 18:24    -08:00:00   False
2001-04-11 15:36    2001-04-11 08:36    -07:00:00   True
2001-09-14 04:48    2001-09-13 21:48    -07:00:00   True
2002-02-16 18:00    2002-02-16 10:00    -08:00:00   False
2002-07-22 07:12    2002-07-22 00:12    -07:00:00   True
2002-12-24 20:24    2002-12-24 12:24    -08:00:00   False
2003-05-29 09:36    2003-05-29 02:36    -07:00:00   True
2003-10-31 22:48    2003-10-31 14:48    -08:00:00   False
2004-04-04 12:00    2004-04-04 05:00    -07:00:00   True
*/

Visual C++

// Example of the TimeZone::ToLocalTime( DateTime ) and 
// TimeZone::GetUtcOffset( DateTime ) methods.
using namespace System;
int main()
{
   String^ headFmt = "{0,-20}{1,-20}{2,-12}{3}";

   // Get the local time zone and a base Coordinated Universal 
   // Time (UTC).
   TimeZone^ localZone = TimeZone::CurrentTimeZone;
   DateTime baseUTC = DateTime(2000,1,1);
   Console::WriteLine( "This example of \n"
   "   TimeZone::ToLocalTime( DateTime ) and\n"
   "   TimeZone::GetUtcOffset( DateTime ) \ngenerates the "
   "following output, which varies depending on the time "
   "zone \nin which it is run. The example creates several "
   "Coordinated Universal \nTimes (UTC), displays the "
   "corresponding local times and UTC offsets, \nand shows "
   "if the times occur in daylight saving time (DST)." );
   Console::WriteLine( "\nLocal time: {0}\n", localZone->StandardName );
   Console::WriteLine( headFmt, "UTC", "Local Time", " Offset", "DST?" );
   Console::WriteLine( headFmt, "---", "----------", " ------", "----" );

   // Generate several UTC times.
   for ( int loopX = 0; loopX <= 10; loopX++ )
   {

      // Calculate the local time and UTC offset.
      DateTime localTime = localZone->ToLocalTime( baseUTC );
      TimeSpan localOffset = localZone->GetUtcOffset( localTime );
      Console::WriteLine( "{0,-20:yyyy-MM-dd HH:mm}"
      "{1,-20:yyyy-MM-dd HH:mm}{2,-12}{3}", baseUTC, localTime, localOffset, localZone->IsDaylightSavingTime( localTime ) );

      // Advance to another UTC.
      baseUTC = baseUTC.AddDays( 155.55 );

   }
}

/*
This example of
   TimeZone::ToLocalTime( DateTime ) and
   TimeZone::GetUtcOffset( DateTime )
generates the following output, which varies depending on the time zone
in which it is run. The example creates several Coordinated Universal
Times (UTC), displays the corresponding local times and UTC offsets,
and shows if the times occur in daylight saving time (DST).

Local time: Pacific Standard Time

UTC                 Local Time           Offset     DST?
---                 ----------           ------     ----
2000-01-01 00:00    1999-12-31 16:00    -08:00:00   False
2000-06-04 13:12    2000-06-04 06:12    -07:00:00   True
2000-11-07 02:24    2000-11-06 18:24    -08:00:00   False
2001-04-11 15:36    2001-04-11 08:36    -07:00:00   True
2001-09-14 04:48    2001-09-13 21:48    -07:00:00   True
2002-02-16 18:00    2002-02-16 10:00    -08:00:00   False
2002-07-22 07:12    2002-07-22 00:12    -07:00:00   True
2002-12-24 20:24    2002-12-24 12:24    -08:00:00   False
2003-05-29 09:36    2003-05-29 02:36    -07:00:00   True
2003-10-31 22:48    2003-10-31 14:48    -08:00:00   False
2004-04-04 12:00    2004-04-04 05:00    -07:00:00   True
*/

Platforms

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98, Windows CE, Windows Mobile for Smartphone, Windows Mobile for Pocket PC, Xbox 360, Zune

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

Version Information

.NET Framework

Supported in: 3.5, 3.0, 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 3.5, 2.0, 1.0

XNA Framework

Supported in: 3.0, 2.0, 1.0

Reference