DateTime Structure

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

• By calling any of the overloads of the DateTime constructor that 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.

  Dim date1 As New Date(2008, 5, 1, 8, 30, 52)
  

  DateTime date1 = new DateTime(2008, 5, 1, 8, 30, 52);
  

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

  Dim date1 As Date = #5/1/2008 8:30:52 AM#
  

• 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 Coordinated Universal Time (UTC) date and time, and the current date to three new DateTime variables.

  Dim date1 As Date = Date.Now
  Dim date2 As Date = Date.UtcNow
  Dim date3 As Date = Date.Today
  

  DateTime date1 = DateTime.Now;
  DateTime date2 = DateTime.UtcNow;
  DateTime date3 = DateTime.Today;
  

• 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 a string and convert it to a DateTime value.

  Dim dateString As String = "5/1/2008 8:30:52 AM"
  Dim date1 As Date = Date.Parse(dateString, _
                           System.Globalization.CultureInfo.InvariantCulture)
  

  string dateString = "5/1/2008 8:30:52 AM";
  DateTime date1 = DateTime.Parse(dateString, 
                            System.Globalization.CultureInfo.InvariantCulture);
  

  Note that the TryParse and TryParseExact methods indicate whether a particular string contains a valid representation of a DateTime value at the same time as they try the conversion.

• By calling the DateTime structure's implicit default constructor. An approximate equivalent, for compilers that support it, is declaring a DateTime value without explicitly assigning a date and time to it. The following example illustrates a call to the DateTime implicit default constructor in C# and Visual Basic, as well as a DateTime variable declaration with no assignment in Visual Basic.

  Dim dat1 As DateTime
  ' The following method call displays 1/1/0001 12:00:00 AM.
  outputBlock.Text &= dat1.ToString(System.Globalization.CultureInfo.InvariantCulture) & vbCrLf
  ' The following method call displays True.
  outputBlock.Text &= dat1.Equals(Date.MinValue) & vbCrLf
  
  Dim dat2 As New DateTime()
  ' The following method call displays 1/1/0001 12:00:00 AM.
  outputBlock.Text &= dat2.ToString(System.Globalization.CultureInfo.InvariantCulture) & vbCrLf
  ' The following method call displays True.
  outputBlock.Text &= dat2.Equals(Date.MinValue) & vbCrLf
  

  DateTime dat1 = new DateTime();
  // The following method call displays 1/1/0001 12:00:00 AM.
  outputBlock.Text += dat1.ToString(System.Globalization.CultureInfo.InvariantCulture) + "\n";
  // The following method call displays True.
  outputBlock.Text += dat1.Equals(DateTime.MinValue) + "\n";
  

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 that value's string representation or its appearance in a user interface element. 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 computer on which the example was run.

Dim date1 As Date = #3/1/2008 7:00:00 AM#
outputBlock.Text &= date1.ToString() & vbCrLf
' For en-US culture, displays 3/1/2008 7:00:00 AM

DateTime date1 = new DateTime(2008, 3, 1, 7, 0, 0);
outputBlock.Text += date1.ToString() + "\n";
// For en-US culture, displays 3/1/2008 7:00:00 AM

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.

Dim date1 As Date = #3/1/2008 7:00:00 AM#
outputBlock.Text &= date1.ToString(New System.Globalization.CultureInfo("fr-FR")) & vbCrLf
' Displays 01/03/2008 07:00:00

DateTime date1 = new DateTime(2008, 3, 1, 7, 0, 0);
outputBlock.Text += date1.ToString(new System.Globalization.CultureInfo("fr-FR")) + "\n";
// Displays 01/03/2008 07:00:00

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 computer on which the example was run.

Dim date1 As Date = #3/1/2008 7:00:00 AM#
outputBlock.Text &= date1.ToString("F") & vbCrLf
' Displays Saturday, March 01, 2008 7:00:00 AM

DateTime date1 = new DateTime(2008, 3, 1, 7, 0, 0);
outputBlock.Text += date1.ToString("F") + "\n";
// Displays Saturday, March 01, 2008 7:00:00 AM

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.

Dim date1 As Date = #3/1/2008 7:00:00 AM#
outputBlock.Text &= date1.ToString("F", New System.Globalization.CultureInfo("fr-FR")) & vbCrLf
' Displays samedi 1 mars 2008 07:00:00

DateTime date1 = new DateTime(2008, 3, 1, 7, 0, 0);
outputBlock.Text += date1.ToString("F", new System.Globalization.CultureInfo("fr-FR")) + "\n";
// Displays samedi 1 mars 2008 07:00:00

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.

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.

Note:
Calculations and comparisons of DateTime objects are meaningful only if the objects represent times in the same time zone.

Conversion operations between time zones (such as between UTC and local time, or between time in one time zone and local time) take the local time zone's 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 either UTC or local time.

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.

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 a TimeSpan object that represents the time interval between them. Or you could add a positive TimeSpan to the current DateTime to obtain a DateTime value that represents 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.

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