DateTime Structure

Represents an instant in time, typically expressed as a date and time of day.

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

<SerializableAttribute> _
Public Structure DateTime
	Implements IComparable, IFormattable, IConvertible, ISerializable, _
	IComparable(Of DateTime), IEquatable(Of DateTime)
Dim instance As DateTime

/** @attribute SerializableAttribute() */ 
public final class DateTime extends ValueType implements IComparable, IFormattable, 
	IConvertible, ISerializable, IComparable<DateTime>, IEquatable<DateTime>
Not applicable.

The DateTime value type represents dates and times with values ranging from 12:00:00 midnight, January 1, 0001 Anno Domini (Common Era) through 11:59:59 P.M., December 31, 9999 A.D. (C.E.)

Time values are measured in 100-nanosecond units called ticks, and a particular date is the number of ticks since 12:00 midnight, January 1, 0001 A.D. (C.E.) in the GregorianCalendar calendar. For example, a ticks value of 31241376000000000L represents the date, Friday, January 01, 0100 12:00:00 midnight. A DateTime value is always expressed in the context of an explicit or default calendar.

Instantiating a DateTime Object

You can create a new DateTime value in any of the following ways:

  • By calling any of the overloads of the DateTime constructor. which allow you to specify specific elements of the date and time value (such as the year, month, and day, or the number of ticks). The following statement illustrates a call to one of the DateTime constructors to create a date with a specific year, month, day, hour, minute, and second.

  • By using any compiler-specific syntax for declaring date and time values. For example, the following Visual Basic statement initializes a new DateTime value.

  • By assigning the DateTime object a date and time value returned by a property or method. The following example assigns the current date and time, the current UTC date and time, and the current date to three new DateTime variables.

  • By parsing the string representation of a date and time value. The Parse, ParseExact, TryParse, and TryParseExact methods all convert a string to its equivalent date and time value. The following example uses the Parse method to parse and string and convert it to a DateTime value.

DateTime Values and Their String Representations

Internally, all DateTime values are represented as the number of ticks (the number of 100-nanosecond intervals) that have elapsed since 12:00:00 midnight, January 1, 0001. The actual DateTime value is independent of the way in which that value appears when displayed in a user interface element or when written to a file. The appearance of a DateTime value is the result of a formatting operation. Formatting is the process of converting a value to its string representation.

Because the appearance of date and time values is dependent on such factors as culture, international standards, application requirements, and personal preference, the DateTime structure offers a great deal of flexibility in formatting date and time values through the overloads of its ToString method. The default DateTime.ToString method returns the string representation of a date and time value using the current culture's short date and long time pattern. The following example uses the default DateTime.ToString method to display the date and time using the short date and long time pattern for the en-US culture, the current culture on the system on which the example was run.

The DateTime.ToString(IFormatProvider) method returns the string representation of a date and time value using the short date and long time pattern of a specific culture. The following example uses the DateTime.ToString(IFormatProvider) method to display the date and time using the short date and long time pattern for the fr-FR culture.

The DateTime.ToString(String) method returns the string representation of the date and time in a format defined by a standard or custom format specifier and using the formatting conventions of the current culture. The following example uses the DateTime.ToString(String) method to display the full date and time pattern for the en-US culture, the current culture on the system on which the example was run.

The DateTime.ToString(String,IFormatProvider) method returns the string representation of the date and time in a format defined by a specific format specifier and using the formatting conventions of a specific culture. The following example uses the DateTime.ToString(String,IFormatProvider) method to display the full date and time pattern for the fr-FR culture.

Version Considerations

Prior to the .NET Framework version 2.0, the DateTime structure contains a 64-bit field composed of an unused 2-bit field concatenated with a private Ticks field, which is a 62-bit unsigned field that contains the number of ticks that represent the date and time. The value of the Ticks field can be obtained with the Ticks property.

Starting with the .NET Framework 2.0, the DateTime structure contains a 64-bit field composed of a private Kind field concatenated with the Ticks field. The Kind field is a 2-bit field that indicates whether the DateTime structure represents a local time, a Coordinated Universal Time (UTC), or the time in an unspecified time zone. The Kind field is used when performing time conversions between time zones, but not for time comparisons or arithmetic. The value of the Kind field can be obtained with the Kind property.


An alternative to the DateTime structure for working with date and time values in particular time zones is the DateTimeOffset structure. The DateTimeOffset structure stores date and time information in a private DateTime field and the number of minutes by which that date and time differs from UTC in a private Int16 field. This makes it possible for a DateTimeOffset value to reflect the time in a particular time zone, whereas a DateTime value can unambiguously reflect only UTC and the local time zone's time. For a discussion about when to use the DateTime structure or the DateTimeOffset structure when working with date and time values, see Choosing Between DateTime, DateTimeOffset, and TimeZoneInfo.

DateTime Values

Descriptions of time values in the DateTime type are often expressed using the Coordinated Universal Time (UTC) standard, which is the internationally recognized name for Greenwich Mean Time (GMT). Coordinated Universal Time is the time as measured at zero degrees longitude, the UTC origin point. Daylight saving time is not applicable to UTC.

Local time is relative to a particular time zone. A time zone is associated with a time zone offset, which is the displacement of the time zone measured in hours from the UTC origin point. In addition, local time is optionally affected by daylight saving time, which adds or subtracts an hour from the length of a day. Consequently, local time is calculated by adding the time zone offset to UTC and adjusting for daylight saving time if necessary. The time zone offset at the UTC origin point is zero.

UTC time is suitable for calculations, comparisons, and storing dates and time in files. Local time is appropriate for display in user interfaces of desktop applications. Time zone-aware applications (such as many Web applications) also need to work with a number of other time zones.

If the Kind property of a DateTime object is DateTimeKind.Unspecified, it is unspecified whether the time represented is local time, UTC time, or a time in some other time zone.

DateTime Operations

A calculation using a DateTime structure, such as Add or Subtract, does not modify the value of the structure. Instead, the calculation returns a new DateTime structure whose value is the result of the calculation.

Conversion operations between time zones (such as between UTC and local time, or between one time zone and another) take daylight saving time into account, but arithmetic and comparison operations do not.

The DateTime structure itself offers limited support for converting from one time zone to another. You can use the ToLocalTime method to convert UTC to local time, or you can use the ToUniversalTime method to convert from local time to UTC. However, a full set of time zone conversion methods is available in the TimeZoneInfo class. Using these methods, you can convert the time in any one of the world's time zones to the time in any other time zone.

Calculations and comparisons of DateTime objects are meaningful only if the objects represent times in the same time zone. You can use a TimeZoneInfo object to represent a DateTime value's time zone, although the two are loosely coupled. (That is, a DateTime object does not have a property that returns an object that represents that date and time value's time zone other than the Kind property.) For this reason, in a time zone-aware application, you must rely on some external mechanism to determine the time zone in which a DateTime object was created. For example, you could use a structure that wraps both the DateTime value and the TimeZoneInfo object that represents the DateTime value's time zone.

Each DateTime member implicitly uses the Gregorian calendar to perform its operation, with the exception of constructors that specify a calendar, and methods with a parameter derived from IFormatProvider, such as System.Globalization.DateTimeFormatInfo, that implicitly specifies a calendar.

Operations by members of the DateTime type take into account details such as leap years and the number of days in a month.

DateTime vs. TimeSpan

The DateTime and TimeSpan value types differ in that a DateTime represents an instant in time whereas a TimeSpan represents a time interval. This means, for example, that you can subtract one instance of DateTime from another to obtain the time interval between them. Or you could add a positive TimeSpan to the current DateTime to calculate a future date.

You can add or subtract a time interval from a DateTime object. Time intervals can be negative or positive, can be expressed in units such as ticks or seconds, or can be expressed as a TimeSpan object.

COM Interop Considerations

A DateTime value that is transferred to a COM application, then is transferred back to a managed application, is said to round-trip. However, a DateTime value that specifies only a time does not round-trip as you might expect.

If you round-trip only a time, such as 3 P.M., the final date and time is December 30, 1899 C.E. at 3:00 P.M., instead of January, 1, 0001 C.E. at 3:00 P.M. This happens because the .NET Framework and COM assume a default date when only a time is specified. However, the COM system assumes a base date of December 30, 1899 C.E. while the .NET Framework assumes a base date of January, 1, 0001 C.E.

When only a time is passed from the .NET Framework to COM, special processing is performed that converts the time to the format used by COM. When only a time is passed from COM to the .NET Framework, no special processing is performed because that would corrupt legitimate dates and times on or before December 30, 1899. This also means if a date starts its round-trip from COM, the .NET Framework and COM preserve the date.

The behavior of the .NET Framework and COM means that if your application round-trips a DateTime that only specifies a time, your application must remember to modify or ignore the erroneous date from the final DateTime object.

Implemented Interfaces

This type implements interfaces IComparable, IComparable, IFormattable, and IConvertible. Use the Convert class for conversions instead of this type's explicit interface member implementation of IConvertible.

The following code example demonstrates how to compare roughly equivalent DateTime values, accepting a small margin of difference when declaring them equal.

Class DateTimeTester
   Shared Function RoughlyEquals(time As DateTime, timeWithWindow As DateTime, windowInSeconds As Integer, frequencyInSeconds As Integer) As Boolean
      Dim delta As Long = (timeWithWindow.Subtract(time)).TotalSeconds Mod frequencyInSeconds
      If delta > windowInSeconds Then 
	delta = frequencyInSeconds - delta 
      End If
      Return Math.Abs(delta) < windowInSeconds

   End Function 'RoughlyEquals
   Public Shared Sub Main()

      Dim window As Integer = 10
      Dim freq As Integer = 60 * 60 * 2 ' 2 hours;
      Dim d1 As DateTime = DateTime.Now
      Dim d2 As DateTime = d1.AddSeconds((2 * window))
      Dim d3 As DateTime = d1.AddSeconds((- 2 * window))
      Dim d4 As DateTime = d1.AddSeconds((window / 2))
      Dim d5 As DateTime = d1.AddSeconds((- window / 2))
      Dim d6 As DateTime = d1.AddHours(2).AddSeconds((2 * window))
      Dim d7 As DateTime = d1.AddHours(2).AddSeconds((- 2 * window))
      Dim d8 As DateTime = d1.AddHours(2).AddSeconds((window / 2))
      Dim d9 As DateTime = d1.AddHours(2).AddSeconds((- window / 2))
      Console.WriteLine("d1 ~= d1 [true]: " + CStr(RoughlyEquals(d1, d1, window, freq)))
      Console.WriteLine("d1 ~= d2 [false]: " + CStr(RoughlyEquals(d1, d2, window, freq)))
      Console.WriteLine("d1 ~= d3 [false]: " + CStr(RoughlyEquals(d1, d3, window, freq)))
      Console.WriteLine("d1 ~= d4 [true]: " + CStr(RoughlyEquals(d1, d4, window, freq)))
      Console.WriteLine("d1 ~= d5 [true]: " + CStr(RoughlyEquals(d1, d5, window, freq)))
      Console.WriteLine("d1 ~= d6 [false]: " + CStr(RoughlyEquals(d1, d6, window, freq)))
      Console.WriteLine("d1 ~= d7 [false]: " + CStr(RoughlyEquals(d1, d7, window, freq)))
      Console.WriteLine("d1 ~= d8 [true]: " + CStr(RoughlyEquals(d1, d8, window, freq)))
      Console.WriteLine("d1 ~= d9 [true]: " + CStr(RoughlyEquals(d1, d9, window, freq)))

   End Sub 'Main 

End Class 'DateTimeTester 

class DateTimeTester
    public static boolean RoughlyEquals(DateTime time, 
        DateTime timeWithWindow, int windowInSeconds, int frequencyInSeconds)
        long delta = (long)((TimeSpan)timeWithWindow.Subtract(time)).
            get_TotalSeconds() % frequencyInSeconds;
        delta = delta > windowInSeconds ? frequencyInSeconds - delta : delta;
        return (System.Convert.ToBoolean(System.Math.Abs(delta) 
            < windowInSeconds));
    } //RoughlyEquals

    public static void main(String[] args)
        int window = 10;
        int freq = 60 * 60 * 2; // 2 hours;
        DateTime d1 = DateTime.get_Now();
        DateTime d2 = d1.AddSeconds(2 * window);
        DateTime d3 = d1.AddSeconds(-2 * window);
        DateTime d4 = d1.AddSeconds(window / 2);
        DateTime d5 = d1.AddSeconds(-window / 2);

        DateTime d6 = d1.AddHours(2).AddSeconds(2 * window);
        DateTime d7 = d1.AddHours(2).AddSeconds(-2 * window);
        DateTime d8 = d1.AddHours(2).AddSeconds(window / 2);
        DateTime d9 = d1.AddHours(2).AddSeconds(-window / 2);

        Console.WriteLine("d1 ~= d1 [true]: " 
            + RoughlyEquals(d1, d1, window, freq));
        Console.WriteLine("d1 ~= d2 [false]: " 
            + RoughlyEquals(d1, d2, window, freq));
        Console.WriteLine("d1 ~= d3 [false]: " 
            + RoughlyEquals(d1, d3, window, freq));
        Console.WriteLine("d1 ~= d4 [true]: " 
            + RoughlyEquals(d1, d4, window, freq));
        Console.WriteLine("d1 ~= d5 [true]: " 
            + RoughlyEquals(d1, d5, window, freq));
        Console.WriteLine("d1 ~= d6 [false]: " 
            + RoughlyEquals(d1, d6, window, freq));
        Console.WriteLine("d1 ~= d7 [false]: " 
            + RoughlyEquals(d1, d7, window, freq));
        Console.WriteLine("d1 ~= d8 [true]: " 
            + RoughlyEquals(d1, d8, window, freq));
        Console.WriteLine("d1 ~= d9 [true]: " 
            + RoughlyEquals(d1, d9, window, freq));
    } //main 
} //DateTimeTester 

All members of this type are thread safe. Members that appear to modify instance state actually return a new instance initialized with the new value. As with any other type, reading and writing to a shared variable that contains an instance of this type must be protected by a lock to guarantee thread safety.

Caution noteCaution:

Assigning an instance of this type is not thread safe on all hardware platforms because the binary representation of that instance might be too large to assign in a single atomic operation.

Windows 98, Windows Server 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.

.NET Framework

Supported in: 3.0, 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 2.0, 1.0

XNA Framework

Supported in: 1.0

Community Additions