DateTime Structure

Article
01/16/2013

[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]

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

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

Syntax

'Declaration
<SerializableAttribute> _
Public Structure DateTime

[SerializableAttribute]
public struct DateTime

[SerializableAttribute]
public value class DateTime

[<Sealed>]
[<SerializableAttribute>]
type DateTime =  struct end

JScript supports the use of structures, but not the declaration of new ones.

The DateTime type exposes the following members.

Constructors

	Name	Description
	DateTime(Int64)	Initializes a new instance of the DateTime structure to a specified number of ticks.
	DateTime(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.
	DateTime(Int32, Int32, Int32)	Initializes a new instance of the DateTime structure to the specified year, month, and day.
	DateTime(Int32, Int32, Int32, Int32, Int32, Int32)	Initializes a new instance of the DateTime structure to the specified year, month, day, hour, minute, and second.
	DateTime(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.

Top

Properties

	Name	Description
	Date	Gets the date component of this instance.
	Day	Gets the day of the month represented by this instance.
	DayOfWeek	Gets the day of the week represented by this instance.
	DayOfYear	Gets the day of the year represented by this instance.
	Hour	Gets the hour component of the date represented by this instance.
	Kind	Gets a value that indicates whether the time represented by this instance is based on local time, Coordinated Universal Time (UTC), or neither.
	Millisecond	Gets the milliseconds component of the date represented by this instance.
	Minute	Gets the minute component of the date represented by this instance.
	Month	Gets the month component of the date represented by this instance.
	Now	Gets a DateTime object that is set to the current date and time on this computer, expressed as the local time.
	Second	Gets the seconds component of the date represented by this instance.
	Ticks	Gets the number of ticks that represent the date and time of this instance.
	TimeOfDay	Gets the time of day for this instance.
	Today	Gets the current date.
	UtcNow	Gets a DateTime object that is set to the current date and time on this computer, expressed as the Coordinated Universal Time (UTC).
	Year	Gets the year component of the date represented by this instance.

Top

Methods

	Name	Description
	Add	Returns a new DateTime that adds the value of the specified TimeSpan to the value of this instance.
	AddDays	Returns a new DateTime that adds the specified number of days to the value of this instance.
	AddHours	Returns a new DateTime that adds the specified number of hours to the value of this instance.
	AddMilliseconds	Returns a new DateTime that adds the specified number of milliseconds to the value of this instance.
	AddMinutes	Returns a new DateTime that adds the specified number of minutes to the value of this instance.
	AddSeconds	Returns a new DateTime that adds the specified number of seconds to the value of this instance.
	AddTicks	Returns a new DateTime that adds the specified number of ticks to the value of this instance.
	Compare	Compares two instances of DateTime and returns an integer that indicates whether the first instance is earlier than, the same as, or later than the second instance.
	CompareTo	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.
	DaysInMonth	Returns the number of days in the specified month and year.
	Equals(Object)	Returns a value indicating whether this instance is equal to a specified object. (Overrides ValueType. . :: . .Equals(Object).)
	Equals(DateTime, DateTime)	Returns a value indicating whether two DateTime instances have the same date and time value.
	GetHashCode	Serves as a hash function for a particular type. (Inherited from Object.)
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	SpecifyKind	Creates 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.
	Subtract(DateTime)	Subtracts the specified date and time from this instance.
	Subtract(TimeSpan)	Subtracts the specified duration from this instance.
	ToLocalTime	Converts the value of the current DateTime object to local time.
	ToString() () () ()	Converts the value of the current DateTime object to its equivalent string representation. (Overrides Object. . :: . .ToString() () () ().)
	ToString(String)	Converts the value of the current DateTime object to its equivalent string representation using the specified format.
	ToUniversalTime	Converts the value of the current DateTime object to Coordinated Universal Time (UTC).

Top

Operators

	Name	Description
	Addition	Adds a specified time interval to a specified date and time, yielding a new date and time.
	Equality	Determines whether two specified instances of DateTime are equal.
	GreaterThan	Determines whether one specified DateTime is greater than another specified DateTime.
	GreaterThanOrEqual	Determines whether one specified DateTime is greater than or equal to another specified DateTime.
	Inequality	Determines whether two specified instances of DateTime are not equal.
	LessThan	Determines whether one specified DateTime is less than another specified DateTime.
	LessThanOrEqual	Determines whether one specified DateTime is less than or equal to another specified DateTime.
	Subtraction(DateTime, DateTime)	Subtracts a specified date and time from another specified date and time and returns a time interval.
	Subtraction(DateTime, TimeSpan)	Subtracts a specified time interval from a specified date and time and returns a new date and time.

Top

Fields

	Name	Description
	MaxValue	Represents the largest possible value of DateTime. This field is read-only.
	MinValue	Represents the smallest possible value of DateTime. This field is read-only.

Top

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

Conversion operations between time zones (such as between UTC and local time, or between one time zone and another) take daylight saving time into account, but arithmetic and comparison operations do not.

Calculations and comparisons of DateTime objects are meaningful only if the objects represent times in the same time zone. You can use a TimeZoneInfo object to represent a DateTime value's time zone, although the two are loosely coupled. (That is, a DateTime object does not have a property that returns an object that represents that date and time value's time zone other than the Kind property.) For this reason, in a time zone-aware application, you must rely on some external mechanism to determine the time zone in which a DateTime object was created. For example, you could use a structure that wraps both the DateTime value and the TimeZoneInfo object that represents the DateTime value's time zone. For details on using UTC in calculations and comparisons with DateTime values, see Performing Arithmetic Operations with Dates and Times.

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.

COM Interop Considerations

A DateTime value that is transferred to a COM application, then is transferred back to a managed application, is said to round-trip. However, a DateTime value that specifies only a time does not round-trip as you might expect.

If you round-trip only a time, such as 3 P.M., the final date and time is December 30, 1899 C.E. at 3:00 P.M., instead of January, 1, 0001 C.E. at 3:00 P.M. This happens because the .NET Framework and COM assume a default date when only a time is specified. However, the COM system assumes a base date of December 30, 1899 C.E. while the .NET Framework assumes a base date of January, 1, 0001 C.E.

When only a time is passed from the .NET Framework to COM, special processing is performed that converts the time to the format used by COM. When only a time is passed from COM to the .NET Framework, no special processing is performed because that would corrupt legitimate dates and times on or before December 30, 1899. This also means if a date starts its round-trip from COM, the .NET Framework and COM preserve the date.

The behavior of the .NET Framework and COM means that if your application round-trips a DateTime that only specifies a time, your application must remember to modify or ignore the erroneous date from the final DateTime object.

Examples

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

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Share via