.NET 1.1+

DateTime Data Type

The twenty-fifth part of the C# Fundamentals tutorial starts an examination of the DateTime data type. The structure allows storage and manipulation of date and time information with a range of thousands of years but accuracy in fractions of microseconds.

The DateTime Data Type

So far in the C# Fundamentals tutorial we have considered the storage and manipulation of numeric and textual data. When you wish to process date and time information, neither provides a satisfactory solution. A much better option is the DateTime structure.

The DateTime structure describes an instant in time, holding both a date and a time. The date part holds a date, month and year that can represent dates between 1 January 0001 to 31 December 9999, a period of almost ten thousand years. The time part stores times with millisecond accuracy.

As the DateTime data type is a structure rather than an object, it is not possible for variables of this type to hold null values. However, with such a wide range of values available, it is common for a specific date such as 1/1/1 or 31/12/9999 to be used to indicate an undefined date.

Co-ordinated Universal Time

Co-ordinated Universal Time (UTC) is a worldwide standard for defining time. Unlike local times, which vary between time zones and with daylight savings time variations, a UTC time is the same everywhere on the Earth simultaneously. For example, using local times it can be 9:00am in the UK and 10:00am in France. Expressed in UTC, it could be 9:00am in both countries.

UTC time is ideal when storing the time at which events occur. If using local time it is possible for a change in daylight savings time to falsely suggest that events occurred in the wrong order. Using UTC this problem disappears. This is more pronounced when a central application is used internationally.

The DateTime structure allows the creation of date and time values using either local time or UTC. It permits conversion between the two times so that information can be stored accurately and displayed using the user's preference.

Ticks

The smallest definable time interval is one ten-millionth of a second, or one hundred nanoseconds. This period of time is known as a tick. Ticks provide an accurate method of describing the time in a DateTime by counting the number of ticks since 1 January 0001.

DateTime Assignment

Unlike numeric and textual data types, DateTime variables cannot be assigned using a literal value. Instead, the DateTime structure includes constructors that generate the date and time information required. DateTime values may also be assigned by parsing strings or using special values. Each method is described below.

DateTime Constructors

Possibly the simplest DateTime constructor requires three integer parameters. These represent the year, month and date parts of a date. All DateTime values include both a date part and a time part so for this constructor, the time defaults to midnight. As the range of the integer values is greater than the possible values for the date parts, it is possible to provide invalid arguments and cause an exception.

DateTime newDate;

newDate = new DateTime(2006, 12, 20);           // Date is 20 Dec 2006 (midnight)
newDate = new DateTime(2006, 13, 20);           // Causes an error to occur

To include a time in a DateTime value, further parameters can be used . Three extra integer parameters can be added to represent hours, minutes and seconds. For greater accuracy a seventh integer parameter can be specified to represent a number of milliseconds.

DateTime newDate;

newDate = new DateTime(2000, 1, 2, 3, 4, 5);    // Date = 2 Jan 2000 03:04:05
newDate = new DateTime(2000, 1, 2, 3, 4, 5, 6); // Date = 2 Jan 2000 03:04:05.0006

The most accurate assignment of DateTime uses a number of ticks in a 64-bit integer (or long) parameter. The parameter defines the number of ticks since midnight on 1 January 0001. The number of ticks for an existing date may also be extracted from a DateTime by reading the Ticks property.

DateTime newDate;

newDate = new DateTime(0);                      // Date = 1 Jan 0001 (midnight)
newDate = new DateTime(630823790450000000);     // Date = 2 Jan 2000 03:04:05
long numTicks = newDate.Ticks;                  // Result = 630823790450000000