DateTime Structure

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

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

Syntax

public struct DateTime

Remarks

The DateTime value type represents dates and times with values ranging from 00:00:00.0, January 1, 1601 Anno Domini, or A.D. (also known as Common Era, or C.E.) through 11:59:59 P.M., December 31, 9999 A.D. (C.E.) These limits are stored as read-only values in the MinValue and MaxValue fields.

Time values are measured in 100-nanosecond units called ticks, and a particular date is expressed as the number of ticks that have elapsed since 12:00 midnight, January 1, 1601 A.D. (C.E.) in the Gregorian calendar. For example, a tick value of 31241376000000000L represents Friday, January 01, 0100 12:00:00 midnight.

DateTime Values

Descriptions of DateTime time values 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 0 (zero) degrees longitude, the UTC origin point. Note that daylight saving time is not applicable to UTC.

Local time is relative to a particular time zone. Each time zone is associated with a specific time zone offset, which is the displacement of that time zone measured in hours of temporal distance from the UTC origin point. In addition, local time is optionally affected by daylight saving time, which is a widely used system of adjusting the official local time forward, usually by one hour from its official standard time, for the summer months. 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 0 (zero).

UTC time is suitable for making calculations and comparisons and for storing dates and time in files. Local time is appropriate for displaying the current date and time in user interfaces.

DateTime Operations

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

Operations by members of the DateTime type take into account such details as leap years and the number of days in a particular month. Conversion operations between local time and UTC time take daylight saving time into account, but arithmetic and comparison operations do not make this daylight saving time adjustment.

Calculations and comparisons of DateTime objects are meaningful only if the objects represent times in the same time zone. 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 particular DateTime object was created.

DateTime vs. TimeSpan

The DateTime and TimeSpan value types differ in that a DateTime value represents a specific instant in time, whereas a TimeSpan value represents a specific period of time. This means, for example, that you can subtract one DateTime value from another to obtain the time interval between the two. Similarly, you can either add a positive TimeSpan value to the current DateTime value to calculate a future date or subtract a positive TimeSpan value from the current DateTime value to calculate a past date.

Version Information

Available in the .NET Micro Framework versions 2.0, 2.5, 3.0, 4.0, 4.1, and 4.2.

See Also

Reference

DateTime Members
System Namespace