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.

>> Download Source Code

The DateTime Data Type

So far in the C# Fundamentals tutorial we have considered the storage and manipulation of numeric and textual data. These two data types are essential to the C# developer. However, when it is necessary to process date or time information, neither provides a satisfactory solution. On the frequent occasions when this kind of data is required, C# and the .NET framework provide the DateTime structure.

The DateTime structure describes an instant in time, holding both a date and a time. The date part of the DateTime holds a date, month and year that can be any value between 1 January of year 1 to 31 December 9999, a period of ten thousand years. The time part of the DateTime stores hours, minutes, seconds and milliseconds.

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 dates available, it is usual for a specific date such as 1/1/1 or 31/12/9999 to be used to indicate that a date is undefined.

Co-ordinated Universal Time

Co-ordinated Universal Time (UTC) is a scientific standard for defining moments in time. Unlike local time, which varies between time zones and due to daylight savings time variations, a time defined in the UTC standard is the same at every position on the Earth simultaneously. For example, using local times it can be 9:00am in the UK whilst being 10:00am in France. Expressed in UTC, it could be 9:00am in both countries.

The UTC representation of time is ideal for software developers when storing the time at which events occur. If using local timings it is possible for a change in daylight savings time to falsely suggest that events occurred in the wrong order. Using UTC this problem does not occur. This situation is even more pronounced when a central application is used internationally.

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

Ticks

The smallest interval between two DateTime values that it is possible to define is one ten-millionth of a second, or one hundred nanoseconds. This period of time is known as a tick. This provides another, very accurate method of describing time in a DateTime variable by counting the number of ticks since 1 January 0001.

DateTime Assignment

Unlike the numeric and textual data types that have been discussed earlier in the tutorial, DateTime variables cannot be assigned to using any form of literal value. Instead, the DateTime structure includes several constructors that may be used to generate the date and time information required. DateTime values may also be assigned using conversion from strings or by using special values. Each of these methods is described in the following sections.

DateTime Constructors

Possibly the simplest constructor that can be used to generate a DateTime value 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 use invalid parameters. If this is attempted, an error occurs.

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 add a time to the DateTime value, further parameters can be used in the constructor. Three extra integer parameters can be added to represent hours, minutes and seconds. For greater accuracy a seventh integer parameter can be passed to the constructor 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

To enable the most accurate assignment of DateTime the value must be generated using a number of ticks. This is achieved by using a single 64-bit integer (or long) parameter. The parameter defines the number of 100 nanosecond intervals since midnight on 1 January of year 1. The number of ticks for an existing date may also be extracted from a DateTime by reading the value's 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

String Parsing

When accepting a date entered by a user as plain text, it can be difficult to ensure that the correct format of date is accepted, particularly for international applications where users in different countries use varying date formats. The Parse method of the DateTime class is provided to convert strings to DateTime values using the local computer settings to determine the date formats in use. The example below assumes the use of a UK-configured computer.

DateTime newDate;

newDate = DateTime.Parse("01/02/2006");         // Date = 1 Feb 2006 (midnight)
newDate = DateTime.Parse("02/01/2000 03:04");   // Date = 2 Jan 2000 03:04:00
newDate = DateTime.Parse("02/01/06");           // Date = 2 Jan 2006 (midnight)

NB: There are various overloaded variations of the Parse method to give finer control over the conversion of strings to DateTimes. There is also another method named ParseExact. These methods are beyond the scope of the C# Fundamentals tutorial.

Assigning the Current Date and Time

The DateTime structure provides three static properties that return the current date or date and time. The Now property returns the current date and time. If only the date is required, the Today property may be used. This returns the current date and a time of midnight. Finally, when storing system times using the Co-ordinated Universal Time standard, the UtcNow property provides the correct UTC date and time.

DateTime newDate;

newDate = DateTime.Now;                         // Current local time
newDate = DateTime.Today;                       // Current local date (midnight)
newDate = DateTime.UtcNow;                      // Current UTC time

MinValue and MaxValue

The last method to be considered for creating a DateTime value is to use one of two predefined DateTimes. These are retrieved from the static properties MinValue or MaxValue. These properties return the minimum or maximum possible DateTime values and are usually used to indicate that a date is undefined as the use of null is not permitted.

DateTime newDate;

newDate = DateTime.MinValue;                    // 01/01/0001 00:00:00
newDate = DateTime.MaxValue;                    // 31/12/9999 23:59:59

.NET 2.0 Nullable DateTime

Earlier in the C# Fundamentals tutorial we examined the nullable numeric data types that were introduced as part of the .NET Framework 2.0. The DateTime data type has a nullable equivalent with similar functionality.

DateTime? nullableDate;

nullableDate = DateTime.MinValue;               // Assign a non-null date
nullableDate = null;                            // Assign an undefined value

Prev << C# String Testing Functions

Next >> DateTime Information Extraction

Link to this Page20 December 2006

Twitter

RSS