This documentation is archived and is not being maintained.

DateTime.CompareTo Method

Compares this instance to a specified object and returns an indication of their relative values.

[Visual Basic]
Public Overridable Function CompareTo( _
   ByVal value As Object _
) As Integer
[C#]
public virtual int CompareTo(
 object value
);
[C++]
public: virtual int CompareTo(
 Object* value
);
[JScript]
public function CompareTo(
   value : Object
) : int;

Parameters

value
An object to compare, or a null reference (Nothing in Visual Basic).

Return Value

A signed number indicating the relative values of this instance and value.

Value Description
Less than zero This instance is less than value.
Zero This instance is equal to value.
Greater than zero This instance is greater than value, or value is a null reference (Nothing in Visual Basic).

Exceptions

Exception Type Condition
ArgumentException value is not a DateTime.

Remarks

Any instance of DateTime, regardless of its value, is considered greater than a null reference (Nothing in Visual Basic).

value must be an instance of DateTime or a null reference (Nothing); otherwise, an exception is thrown.

Example

[Visual Basic, C#, C++] The following sample demonstrates the CompareTo method.

[Visual Basic] 
Dim thDay As New System.DateTime(System.DateTime.Today.Year, 7, 28)

Dim compareValue As Integer
Try
   compareValue = thDay.CompareTo(System.DateTime.Today)
Catch exp As ArgumentException
   System.Console.WriteLine("Value is not a DateTime")
End Try

If compareValue < 0 Then
   System.Console.WriteLine("{0:d} is in the past.", thDay)
ElseIf compareValue = 0 Then
   System.Console.WriteLine("{0:d} is today!", thDay)
ElseIf compareValue = 1 Then
   System.Console.WriteLine("Value is null")
Else ' compareValue > 0 && compareValue != 1
   System.Console.WriteLine("{0:d} has not come yet.", thDay)
End If

[C#] 
System.DateTime theDay = 
          new System.DateTime(System.DateTime.Today.Year, 7, 28);

int compareValue;
try {
    compareValue = theDay.CompareTo(System.DateTime.Today);
} 
catch (ArgumentException) {
    System.Console.WriteLine("Value is not a DateTime");
    return;
}

if (compareValue < 0) {
    System.Console.WriteLine("{0:d} is in the past.", theDay);
} 
else if (compareValue == 0) {
    System.Console.WriteLine("{0:d} is today!", theDay);
}
else if (compareValue == 1) {
    System.Console.WriteLine("Value is null");
}
// compareValue > 0 && compareValue != 1
else { 
    System.Console.WriteLine("{0:d} has not come yet.", theDay);
}

[C++] 
System::DateTime theDay(System::DateTime::Today.Year, 7, 28);

int compareValue;
try {
   compareValue = theDay.CompareTo(__box(System::DateTime::Today));
} catch (ArgumentException*) {
   System::Console::WriteLine(S"Value is not a DateTime");
   return;
}

if (compareValue < 0) {
   System::Console::WriteLine(S"{0:d} is in the past.", __box(theDay));
} else if (compareValue == 0) {
   System::Console::WriteLine(S"{0:d} is today!", __box(theDay));
} else if (compareValue == 1) {
   System::Console::WriteLine(S"Value is 0");
}
// compareValue > 0 && compareValue != 1
else {
   System::Console::WriteLine(S"{0:d} has not come yet.", __box(theDay));
}

[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

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, Common Language Infrastructure (CLI) Standard

See Also

DateTime Structure | DateTime Members | System Namespace | Compare | Equals

Show: