This documentation is archived and is not being maintained.

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>
JScript suports the use of structures, but not the declaration of new ones.

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.

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 whether UTC or local time is not specified. The Kind field is used to handle conversions between local and UTC time, but not time comparisons or arithmetic. The value of the Kind field can be obtained with the Kind property.

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.

If the Kind property of a DateTime object is Unspecified, it is unspecified whether the time represented is local time or UTC time. Individual DateTime members treat unspecified time appropriately for that member.

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 local time and UTC time take daylight saving time into account, but arithmetic and comparison operations do not.

Calculations and comparisons of DateTime objects are only meaningful if the objects represent times in the same time zone. For that reason, if no time zone is specified for the objects, it is assumed that the developer has some external mechanism, such as an explicit variable or policy, that can be used to determine the time zone in which a DateTime object was created.

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 

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Windows 98, Windows 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 .NET Framework does not support all versions of every platform. For a list of the supported versions, see System Requirements.

.NET Framework

Supported in: 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 2.0, 1.0