Export (0) Print
Expand All

DateTime Structure

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

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

'Declaration
Public Structure DateTime _
	Implements IComparable, IFormattable, IConvertible, IComparable(Of DateTime),  _
	IEquatable(Of DateTime)

The DateTime type exposes the following members.

  NameDescription
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360DateTime(Int64)Initializes a new instance of the DateTime structure to a specified number of ticks.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360DateTime(Int64, DateTimeKind)Initializes a new instance of the DateTime structure to a specified number of ticks and to Coordinated Universal Time (UTC) or local time.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360DateTime(Int32, Int32, Int32)Initializes a new instance of the DateTime structure to the specified year, month, and day.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360DateTime(Int32, Int32, Int32, Calendar)Initializes a new instance of the DateTime structure to the specified year, month, and day for the specified calendar.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360DateTime(Int32, Int32, Int32, Int32, Int32, Int32)Initializes a new instance of the DateTime structure to the specified year, month, day, hour, minute, and second.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360DateTime(Int32, Int32, Int32, Int32, Int32, Int32, DateTimeKind)Initializes a new instance of the DateTime structure to the specified year, month, day, hour, minute, second, and Coordinated Universal Time (UTC) or local time.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360DateTime(Int32, Int32, Int32, Int32, Int32, Int32, Calendar)Initializes a new instance of the DateTime structure to the specified year, month, day, hour, minute, and second for the specified calendar.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360DateTime(Int32, Int32, Int32, Int32, Int32, Int32, Int32)Initializes a new instance of the DateTime structure to the specified year, month, day, hour, minute, second, and millisecond.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360DateTime(Int32, Int32, Int32, Int32, Int32, Int32, Int32, DateTimeKind)Initializes a new instance of the DateTime structure to the specified year, month, day, hour, minute, second, millisecond, and Coordinated Universal Time (UTC) or local time.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360DateTime(Int32, Int32, Int32, Int32, Int32, Int32, Int32, Calendar)Initializes a new instance of the DateTime structure to the specified year, month, day, hour, minute, second, and millisecond for the specified calendar.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360DateTime(Int32, Int32, Int32, Int32, Int32, Int32, Int32, Calendar, DateTimeKind)Initializes a new instance of the DateTime structure to the specified year, month, day, hour, minute, second, millisecond, and Coordinated Universal Time (UTC) or local time for the specified calendar.
Top

  NameDescription
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360DateGets the date component of this instance.
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360DayGets the day of the month represented by this instance.
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360DayOfWeekGets the day of the week represented by this instance.
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360DayOfYearGets the day of the year represented by this instance.
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360HourGets the hour component of the date represented by this instance.
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360KindGets a value that indicates whether the time represented by this instance is based on local time, Coordinated Universal Time (UTC), or neither.
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360MillisecondGets the milliseconds component of the date represented by this instance.
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360MinuteGets the minute component of the date represented by this instance.
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360MonthGets the month component of the date represented by this instance.
Public propertyStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360NowGets a DateTime object that is set to the current date and time on this computer, expressed as the local time.
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360SecondGets the seconds component of the date represented by this instance.
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360TicksGets the number of ticks that represent the date and time of this instance.
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360TimeOfDayGets the time of day for this instance.
Public propertyStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360TodayGets the current date.
Public propertyStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360UtcNowGets a DateTime object that is set to the current date and time on this computer, expressed as the Coordinated Universal Time (UTC).
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360YearGets the year component of the date represented by this instance.
Top

  NameDescription
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360AddReturns a new DateTime that adds the value of the specified TimeSpan to the value of this instance.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360AddDaysReturns a new DateTime that adds the specified number of days to the value of this instance.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360AddHoursReturns a new DateTime that adds the specified number of hours to the value of this instance.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360AddMillisecondsReturns a new DateTime that adds the specified number of milliseconds to the value of this instance.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360AddMinutesReturns a new DateTime that adds the specified number of minutes to the value of this instance.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360AddMonthsReturns a new DateTime that adds the specified number of months to the value of this instance.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360AddSecondsReturns a new DateTime that adds the specified number of seconds to the value of this instance.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360AddTicksReturns a new DateTime that adds the specified number of ticks to the value of this instance.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360AddYearsReturns a new DateTime that adds the specified number of years to the value of this instance.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360CompareCompares two instances of DateTime and returns an integer that indicates whether the first DateTime instance is earlier than, the same as, or later than the second DateTime instance.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360CompareTo(DateTime)Compares the value of this instance to a specified DateTime value and returns an integer that indicates whether this instance is earlier than, the same as, or later than the specified DateTime value.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360CompareTo(Object)Compares the value of this instance to a specified object that contains a specified DateTime value, and returns an integer that indicates whether this instance is earlier than, the same as, or later than the specified DateTime value.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360DaysInMonthReturns the number of days in the specified month and year.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360Equals(DateTime)Returns a value indicating whether the value of this instance is equal to the value of the specified DateTime instance.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360Equals(Object)Returns a value indicating whether this instance is equal to a specified object. (Overrides ValueType.Equals(Object).)
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360Equals(DateTime, DateTime)Returns a value indicating whether two DateTime instances have the same date and time value.
Protected methodSupported by Silverlight for Windows PhoneSupported by Xbox 360FinalizeAllows an object to try to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. (Inherited from Object.)
Public methodStatic memberFromBinaryDeserializes a 64-bit binary value and recreates an original serialized DateTime object.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360FromFileTimeConverts the specified Windows file time to an equivalent local time.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360FromFileTimeUtcConverts the specified Windows file time to an equivalent UTC time.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360FromOADateReturns a DateTime equivalent to the specified OLE Automation date.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360GetHashCodeReturns the hash code for this instance. (Overrides ValueType.GetHashCode.)
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360GetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360GetTypeCodeReturns the TypeCode for value type DateTime.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360IsDaylightSavingTimeIndicates whether this instance of DateTime is within the Daylight Saving Time range for the current time zone.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360IsLeapYearReturns an indication whether the specified year is a leap year.
Protected methodSupported by Silverlight for Windows PhoneSupported by Xbox 360MemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360Parse(String)Converts the specified string representation of a date and time to its DateTime equivalent.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360Parse(String, IFormatProvider)Converts the specified string representation of a date and time to its DateTime equivalent using the specified culture-specific format information.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360Parse(String, IFormatProvider, DateTimeStyles)Converts the specified string representation of a date and time to its DateTime equivalent using the specified culture-specific format information and formatting style.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360ParseExact(String, String, IFormatProvider)Converts the specified string representation of a date and time to its DateTime equivalent using the specified format and culture-specific format information. The format of the string representation must match the specified format exactly.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360ParseExact(String, String, IFormatProvider, DateTimeStyles)Converts the specified string representation of a date and time to its DateTime equivalent using the specified format, culture-specific format information, and style. The format of the string representation must match the specified format exactly or an exception is thrown.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360ParseExact(String, String(), IFormatProvider, DateTimeStyles)Converts the specified string representation of a date and time to its DateTime equivalent using the specified array of formats, culture-specific format information, and style. The format of the string representation must match at least one of the specified formats exactly or an exception is thrown.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360SpecifyKindCreates a new DateTime object that has the same number of ticks as the specified DateTime, but is designated as either local time, Coordinated Universal Time (UTC), or neither, as indicated by the specified DateTimeKind value.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360Subtract(DateTime)Subtracts the specified date and time from this instance.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360Subtract(TimeSpan)Subtracts the specified duration from this instance.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360ToFileTimeConverts the value of the current DateTime object to a Windows file time.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360ToFileTimeUtcConverts the value of the current DateTime object to a Windows file time.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360ToLocalTimeConverts the value of the current DateTime object to local time.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360ToLongDateStringConverts the value of the current DateTime object to its equivalent long date string representation.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360ToLongTimeStringConverts the value of the current DateTime object to its equivalent long time string representation.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360ToOADateConverts the value of this instance to the equivalent OLE Automation date.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360ToShortDateStringConverts the value of the current DateTime object to its equivalent short date string representation.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360ToShortTimeStringConverts the value of the current DateTime object to its equivalent short time string representation.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360ToStringConverts the value of the current DateTime object to its equivalent string representation. (Overrides ValueType.ToString.)
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360ToString(IFormatProvider)Converts the value of the current DateTime object to its equivalent string representation using the specified culture-specific format information.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360ToString(String)Converts the value of the current DateTime object to its equivalent string representation using the specified format.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360ToString(String, IFormatProvider)Converts the value of the current DateTime object to its equivalent string representation using the specified format and culture-specific format information.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360ToUniversalTimeConverts the value of the current DateTime object to Coordinated Universal Time (UTC).
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360TryParse(String, DateTime)Converts the specified string representation of a date and time to its DateTime equivalent and returns a value that indicates whether the conversion succeeded.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360TryParse(String, IFormatProvider, DateTimeStyles, DateTime)Converts the specified string representation of a date and time to its DateTime equivalent using the specified culture-specific format information and formatting style, and returns a value that indicates whether the conversion succeeded.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360TryParseExact(String, String, IFormatProvider, DateTimeStyles, DateTime)Converts the specified string representation of a date and time to its DateTime equivalent using the specified format, culture-specific format information, and style. The format of the string representation must match the specified format exactly. The method returns a value that indicates whether the conversion succeeded.
Public methodStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360TryParseExact(String, String(), IFormatProvider, DateTimeStyles, DateTime)Converts the specified string representation of a date and time to its DateTime equivalent using the specified array of formats, culture-specific format information, and style. The format of the string representation must match at least one of the specified formats exactly. The method returns a value that indicates whether the conversion succeeded.
Top

  NameDescription
Public operatorStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360AdditionAdds a specified time interval to a specified date and time, yielding a new date and time.
Public operatorStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360EqualityDetermines whether two specified instances of DateTime are equal.
Public operatorStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360GreaterThanDetermines whether one specified DateTime is greater than another specified DateTime.
Public operatorStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360GreaterThanOrEqualDetermines whether one specified DateTime is greater than or equal to another specified DateTime.
Public operatorStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360InequalityDetermines whether two specified instances of DateTime are not equal.
Public operatorStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360LessThanDetermines whether one specified DateTime is less than another specified DateTime.
Public operatorStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360LessThanOrEqualDetermines whether one specified DateTime is less than or equal to another specified DateTime.
Public operatorStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360Subtraction(DateTime, DateTime)Subtracts a specified date and time from another specified date and time and returns a time interval.
Public operatorStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360Subtraction(DateTime, TimeSpan)Subtracts a specified time interval from a specified date and time and returns a new date and time.
Top

  NameDescription
Public fieldStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360MaxValueRepresents the largest possible value of DateTime. This field is read-only.
Public fieldStatic memberSupported by Silverlight for Windows PhoneSupported by Xbox 360MinValueRepresents the smallest possible value of DateTime. This field is read-only.
Top

  NameDescription
Explicit interface implemetationPrivate methodSupported by Silverlight for Windows PhoneSupported by Xbox 360IConvertible.ToBooleanInfrastructure. This conversion is not supported. Attempting to use this method throws an InvalidCastException.
Explicit interface implemetationPrivate methodSupported by Silverlight for Windows PhoneSupported by Xbox 360IConvertible.ToByteInfrastructure. This conversion is not supported. Attempting to use this method throws an InvalidCastException.
Explicit interface implemetationPrivate methodSupported by Silverlight for Windows PhoneSupported by Xbox 360IConvertible.ToCharInfrastructure. This conversion is not supported. Attempting to use this method throws an InvalidCastException.
Explicit interface implemetationPrivate methodSupported by Silverlight for Windows PhoneSupported by Xbox 360IConvertible.ToDateTimeInfrastructure. Returns the current DateTime object.
Explicit interface implemetationPrivate methodSupported by Silverlight for Windows PhoneSupported by Xbox 360IConvertible.ToDecimalInfrastructure. This conversion is not supported. Attempting to use this method throws an InvalidCastException.
Explicit interface implemetationPrivate methodSupported by Silverlight for Windows PhoneSupported by Xbox 360IConvertible.ToDoubleInfrastructure. This conversion is not supported. Attempting to use this method throws an InvalidCastException.
Explicit interface implemetationPrivate methodSupported by Silverlight for Windows PhoneSupported by Xbox 360IConvertible.ToInt16Infrastructure. This conversion is not supported. Attempting to use this method throws an InvalidCastException.
Explicit interface implemetationPrivate methodSupported by Silverlight for Windows PhoneSupported by Xbox 360IConvertible.ToInt32Infrastructure. This conversion is not supported. Attempting to use this method throws an InvalidCastException.
Explicit interface implemetationPrivate methodSupported by Silverlight for Windows PhoneSupported by Xbox 360IConvertible.ToInt64Infrastructure. This conversion is not supported. Attempting to use this method throws an InvalidCastException.
Explicit interface implemetationPrivate methodSupported by Silverlight for Windows PhoneSupported by Xbox 360IConvertible.ToSByteInfrastructure. This conversion is not supported. Attempting to use this method throws an InvalidCastException.
Explicit interface implemetationPrivate methodSupported by Silverlight for Windows PhoneSupported by Xbox 360IConvertible.ToSingleInfrastructure. This conversion is not supported. Attempting to use this method throws an InvalidCastException.
Explicit interface implemetationPrivate methodSupported by Silverlight for Windows PhoneSupported by Xbox 360IConvertible.ToTypeInfrastructure. Converts the current DateTime object to an object of a specified type.
Explicit interface implemetationPrivate methodSupported by Silverlight for Windows PhoneSupported by Xbox 360IConvertible.ToUInt16Infrastructure. This conversion is not supported. Attempting to use this method throws an InvalidCastException.
Explicit interface implemetationPrivate methodSupported by Silverlight for Windows PhoneSupported by Xbox 360IConvertible.ToUInt32Infrastructure. This conversion is not supported. Attempting to use this method throws an InvalidCastException.
Explicit interface implemetationPrivate methodSupported by Silverlight for Windows PhoneSupported by Xbox 360IConvertible.ToUInt64Infrastructure. This conversion is not supported. Attempting to use this method throws an InvalidCastException.
Top

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 (excluding ticks that would be added by leap seconds)

. 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.

NoteNote:

   If you are working with a ticks value that you need to convert to some other time interval, such as minutes or seconds, you should use the TimeSpan.TicksPerDay, TimeSpan.TicksPerHour, TimeSpan.TicksPerMinute, TimeSpan.TicksPerSecond, or TimeSpan.TicksPerMillisecond constant to perform the conversion. For example, to add the number of seconds represented by a specified number of ticks to the Second component of a DateTime value, you can use the expression dateValue.Second + nTicks/Timespan.TicksPerSecond.

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 the time in an unspecified time zone. The Kind field is used when performing time conversions between time zones, but not for time comparisons or arithmetic. The value of the Kind field can be obtained with the Kind property.

NoteNote:

An alternative to the DateTime structure for working with date and time values that have a degree of time zone awareness is the DateTimeOffset structure. The DateTimeOffset structure stores date and time information in a private DateTime field and the number of minutes by which that date and time differs from UTC in a private Int16 field. This makes it possible for a DateTimeOffset value to reflect the time in a particular time zone, whereas a DateTime value can unambiguously reflect only UTC and the local time zone's time.

Instantiating a DateTime Object

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)
    
    
    
  • 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
    
    
    
  • 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)
    
    
    

    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 Values and Their String Representations

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


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


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


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 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 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.

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.

NoteNote:

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.

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 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.

Implemented Interfaces

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

The following example demonstrates how to compare roughly equivalent DateTime values, accepting a small margin of difference when declaring them equal.


Class Example
   Shared Function RoughlyEquals(ByVal time As DateTime, ByVal timeWithWindow As DateTime, ByVal windowInSeconds As Integer, ByVal 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

   Public Shared Sub Demo(ByVal outputBlock As System.Windows.Controls.TextBlock)
      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))

      outputBlock.Text += String.Format("d1 ({0}) ~= d1 ({1}): {2}", _
                        d1, d1, RoughlyEquals(d1, d1, window, freq)) + vbCrLf
      outputBlock.Text += String.Format("d1 ({0}) ~= d2 ({1}): {2}", _
                        d1, d2, RoughlyEquals(d1, d2, window, freq)) + vbCrLf
      outputBlock.Text += String.Format("d1 ({0}) ~= d3 ({1}): {2}", _
                        d1, d3, RoughlyEquals(d1, d3, window, freq)) + vbCrLf
      outputBlock.Text += String.Format("d1 ({0}) ~= d4 ({1}): {2}", _
                        d1, d4, RoughlyEquals(d1, d4, window, freq)) + vbCrLf
      outputBlock.Text += String.Format("d1 ({0}) ~= d5 ({1}): {2}", _
                        d1, d5, RoughlyEquals(d1, d5, window, freq)) + vbCrLf

      outputBlock.Text += String.Format("d1 ({0}) ~= d6 ({1}): {2}", _
                        d1, d6, RoughlyEquals(d1, d6, window, freq)) + vbCrLf
      outputBlock.Text += String.Format("d1 ({0}) ~= d7 ({1}): {2}", _
                        d1, d7, RoughlyEquals(d1, d7, window, freq)) + vbCrLf
      outputBlock.Text += String.Format("d1 ({0}) ~= d8 ({1}): {2}", _
                        d1, d8, RoughlyEquals(d1, d8, window, freq)) + vbCrLf
      outputBlock.Text += String.Format("d1 ({0}) ~= d9 ({1}): {2}", _
                        d1, d9, RoughlyEquals(d1, d9, window, freq)) + vbCrLf
   End Sub
End Class 
' The example displays output similar to the following:
'    d1 (1/28/2010 9:01:26 PM) ~= d1 (1/28/2010 9:01:26 PM): True
'    d1 (1/28/2010 9:01:26 PM) ~= d2 (1/28/2010 9:01:46 PM): False
'    d1 (1/28/2010 9:01:26 PM) ~= d3 (1/28/2010 9:01:06 PM): False
'    d1 (1/28/2010 9:01:26 PM) ~= d4 (1/28/2010 9:01:31 PM): True
'    d1 (1/28/2010 9:01:26 PM) ~= d5 (1/28/2010 9:01:21 PM): True
'    d1 (1/28/2010 9:01:26 PM) ~= d6 (1/28/2010 11:01:46 PM): False
'    d1 (1/28/2010 9:01:26 PM) ~= d7 (1/28/2010 11:01:06 PM): False
'    d1 (1/28/2010 9:01:26 PM) ~= d8 (1/28/2010 11:01:31 PM): True
'    d1 (1/28/2010 9:01:26 PM) ~= d9 (1/28/2010 11:01:21 PM): True


Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

XNA Framework

Supported in: Xbox 360, Windows Phone OS 7.0

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

All members of this type are thread safe. Members that appear to modify instance state actually return a new instance initialized with the new value. As with any other type, reading and writing to a shared variable that contains an instance of this type must be protected by a lock to guarantee thread safety.

Caution noteCaution:

Assigning an instance of this type is not thread safe on all hardware platforms because the binary representation of that instance might be too large to assign in a single atomic operation.

Community Additions

ADD
Show:
© 2014 Microsoft