DateTime Structure
Represents an instant in time, typically expressed as a date and time of day.
For a list of all members of this type, see DateTime Members.
System.Object
System.ValueType
System.DateTime
[Visual Basic] <Serializable> Public Structure DateTime Implements IComparable, IFormattable, IConvertible [C#] [Serializable] public struct DateTime : IComparable, IFormattable, IConvertible [C++] [Serializable] public __value struct DateTime : public IComparable, IFormattable, IConvertible
[JScript] In JScript, you can use the structures in the .NET Framework, but you cannot define your own.
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.
Remarks
The DateTime value type represents dates and times with values ranging from 12:00:00 midnight, January 1, 0001 Anno Domini (Common Era) to 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, 1 A.D. (C.E.) in the GregorianCalendar calendar. 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.
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 the time interval between them. Or you could add a positive TimeSpan to the current DateTime to calculate a future date.
Time values can be added to, or subtracted from, an instance of DateTime. Time values can be negative or positive, and expressed in units such as ticks, seconds, or instances of TimeSpan. Methods and properties in this value type take into account details such as leap years and the number of days in a month.
Descriptions of time values in this type are often expressed using the coordinated universal time (UTC) standard, which was previously known as Greenwich mean time (GMT).
Calculations and comparisons of DateTime instances are only meaningful when the instances are created in the same time zone. For that reason, it is assumed that the developer has some external mechanism, such as an explicit variable or policy, to know in which time zone a DateTime was created. Methods and properties in this structure always use the local time zone when making calculations or comparisons.
A calculation on an instance of DateTime, such as Add or Subtract, does not modify the value of the instance. Instead, the calculation returns a new instance of DateTime whose value is the result of the calculation.
Each DateTime member implicitly uses the Gregorian calendar to perform its operation, with the exception of constructors that specify a calendar and methods that implicitly specify a calendar with a parameter derived from IFormatProvider, such as System.Globalization.DateTimeFormatInfo. Use the System.Globalization.Calendar class to perform date and time operations with a different calendar.
This type inherits from IComparable, IFormattable, and IConvertible. Use the Convert class for conversions instead of this type's explicit interface member implementation of IConvertible.
Example
[Visual Basic, C#, C++] The following example demonstrates how to compare roughly equivalent DateTime values, accepting a small margin of difference when declaring them "equal".
[Visual Basic] Class DateTimeTester Shared Function RoughlyEquals(time As DateTime, timeWithWindow As DateTime, windowInSeconds As Integer, 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 'RoughlyEquals Public Shared Sub Main() 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)) Console.WriteLine("d1 ~= d1 [true]: " + CStr(RoughlyEquals(d1, d1, window, freq))) Console.WriteLine("d1 ~= d2 [false]: " + CStr(RoughlyEquals(d1, d2, window, freq))) Console.WriteLine("d1 ~= d3 [false]: " + CStr(RoughlyEquals(d1, d3, window, freq))) Console.WriteLine("d1 ~= d4 [true]: " + CStr(RoughlyEquals(d1, d4, window, freq))) Console.WriteLine("d1 ~= d5 [true]: " + CStr(RoughlyEquals(d1, d5, window, freq))) Console.WriteLine("d1 ~= d6 [false]: " + CStr(RoughlyEquals(d1, d6, window, freq))) Console.WriteLine("d1 ~= d7 [false]: " + CStr(RoughlyEquals(d1, d7, window, freq))) Console.WriteLine("d1 ~= d8 [true]: " + CStr(RoughlyEquals(d1, d8, window, freq))) Console.WriteLine("d1 ~= d9 [true]: " + CStr(RoughlyEquals(d1, d9, window, freq))) End Sub 'Main End Class 'DateTimeTester [C#] class DateTimeTester { static bool RoughlyEquals(DateTime time, DateTime timeWithWindow, int windowInSeconds, int frequencyInSeconds) { long delta = (long)((TimeSpan)(timeWithWindow - time)).TotalSeconds % frequencyInSeconds; delta = delta > windowInSeconds ? frequencyInSeconds - delta : delta; return Math.Abs(delta) < windowInSeconds; } public static void Main() { int window = 10; int freq = 60 * 60 * 2; // 2 hours; DateTime d1 = DateTime.Now; DateTime d2 = d1.AddSeconds(2 * window); DateTime d3 = d1.AddSeconds(-2 * window); DateTime d4 = d1.AddSeconds(window / 2); DateTime d5 = d1.AddSeconds(-window / 2); DateTime d6 = (d1.AddHours(2)).AddSeconds(2 * window); DateTime d7 = (d1.AddHours(2)).AddSeconds(-2 * window); DateTime d8 = (d1.AddHours(2)).AddSeconds(window / 2); DateTime d9 = (d1.AddHours(2)).AddSeconds(-window / 2); Console.WriteLine("d1 ~= d1 [true]: " + RoughlyEquals(d1, d1, window, freq)); Console.WriteLine("d1 ~= d2 [false]: " + RoughlyEquals(d1, d2, window, freq)); Console.WriteLine("d1 ~= d3 [false]: " + RoughlyEquals(d1, d3, window, freq)); Console.WriteLine("d1 ~= d4 [true]: " + RoughlyEquals(d1, d4, window, freq)); Console.WriteLine("d1 ~= d5 [true]: " + RoughlyEquals(d1, d5, window, freq)); Console.WriteLine("d1 ~= d6 [false]: " + RoughlyEquals(d1, d6, window, freq)); Console.WriteLine("d1 ~= d7 [false]: " + RoughlyEquals(d1, d7, window, freq)); Console.WriteLine("d1 ~= d8 [true]: " + RoughlyEquals(d1, d8, window, freq)); Console.WriteLine("d1 ~= d9 [true]: " + RoughlyEquals(d1, d9, window, freq)); } } [C++] bool RoughlyEquals(DateTime time, DateTime timeWithWindow, int windowInSeconds, int frequencyInSeconds) { long delta = (long)((TimeSpan)(timeWithWindow - time)).TotalSeconds % frequencyInSeconds; delta = delta > windowInSeconds ? frequencyInSeconds - delta : delta; return Math::Abs(delta) < windowInSeconds; } int main() { int window = 10; int freq = 60 * 60 * 2; // 2 hours; DateTime d1 = DateTime::Now; DateTime d2 = d1.AddSeconds(2 * window); DateTime d3 = d1.AddSeconds(-2 * window); DateTime d4 = d1.AddSeconds(window / 2); DateTime d5 = d1.AddSeconds(-window / 2); DateTime d6 = (d1.AddHours(2)).AddSeconds(2 * window); DateTime d7 = (d1.AddHours(2)).AddSeconds(-2 * window); DateTime d8 = (d1.AddHours(2)).AddSeconds(window / 2); DateTime d9 = (d1.AddHours(2)).AddSeconds(-window / 2); Console::WriteLine(S"d1 ~= d1 [true]: {0}", __box(RoughlyEquals(d1, d1, window, freq))); Console::WriteLine(S"d1 ~= d2 [false]: {0}", __box(RoughlyEquals(d1, d2, window, freq))); Console::WriteLine(S"d1 ~= d3 [false]: {0}", __box(RoughlyEquals(d1, d3, window, freq))); Console::WriteLine(S"d1 ~= d4 [true]: {0}", __box(RoughlyEquals(d1, d4, window, freq))); Console::WriteLine(S"d1 ~= d5 [true]: {0}", __box(RoughlyEquals(d1, d5, window, freq))); Console::WriteLine(S"d1 ~= d6 [false]: {0}", __box(RoughlyEquals(d1, d6, window, freq))); Console::WriteLine(S"d1 ~= d7 [false]: {0}", __box(RoughlyEquals(d1, d7, window, freq))); Console::WriteLine(S"d1 ~= d8 [true]: {0}", __box(RoughlyEquals(d1, d8, window, freq))); Console::WriteLine(S"d1 ~= d9 [true]: {0}", __box(RoughlyEquals(d1, d9, window, freq))); }
[JScript] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button
in the upper-left corner of the page.
Requirements
Namespace: System
Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family, .NET Compact Framework
Assembly: Mscorlib (in Mscorlib.dll)
See Also
DateTime Members | System Namespace | TimeSpan | Calendar | GetUtcOffset