Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

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 Language Filter 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

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft