String.CompareTo Method (Object) (System)

.NET Framework Class Library

String..::.CompareTo Method (Object)

Compares this instance with a specified Object and indicates whether this instance precedes, follows, or appears in the same position in the sort order as the specified Object.

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

Syntax

Public Function CompareTo ( _
	value As Object _
) As Integer

public int CompareTo(
	Object value
)

public:
virtual int CompareTo(
	Object^ value
) sealed

abstract CompareTo : 
        value:Object -> int 
override CompareTo : 
        value:Object -> int

Parameters

value: Type: System..::.Object
An object that evaluates to a String.

Return Value

Type: System..::.Int32
A 32-bit signed integer that indicates whether this instance precedes, follows, or appears in the same position in the sort order as the value parameter.

Value	Condition
Less than zero	This instance precedes value.
Zero	This instance has the same position in the sort order as value.
Greater than zero	This instance follows value. -or- value is nullNothingnullptra null reference (Nothing in Visual Basic).

Value

Condition

Less than zero

This instance precedes value.

Zero

This instance has the same position in the sort order as value.

Greater than zero

This instance follows value.

-or-

value is nullNothingnullptra null reference (Nothing in Visual Basic).

Implements

IComparable..::.CompareTo(Object)

Exceptions

Exception	Condition
ArgumentException	value is not a String.

Remarks

value must be a String object.

Caution
The CompareTo method was designed primarily for use in sorting or alphabetizing operations. It should not be used when the primary purpose of the method call is to determine whether two strings are equivalent. To determine whether two strings are equivalent, call the Equals method.

This method performs a word (case-sensitive and culture-sensitive) comparison using the current culture. For more information about word, string, and ordinal sorts, see System.Globalization..::.CompareOptions.

For more information about the behavior of this method, see the Remarks section of the String..::.Compare(String, String) method.

Examples

The following example demonstrates how you can use the CompareTo method with an Object.


Imports System

Public Class [MyClass]
End Class '[MyClass]

Public Class ArgExceptionExample

   Public Shared Sub Main()
      Dim my As New [MyClass]()
      Dim s As String = "sometext"
      Try
         Dim i As Integer = s.CompareTo(my)
      Catch e As Exception
         Console.WriteLine("Error: {0}", e.ToString())
      End Try
   End Sub 'Main
End Class 'ArgExceptionExample


using System;

public class MyClass {}
public class ArgExceptionExample 
   {
   public static void Main()
      {
      MyClass my = new MyClass();
      string s = "sometext";
      try 
         {
         int i = s.CompareTo(my);
         }
            catch (Exception e) 
            {
            Console.WriteLine("Error: {0}",e.ToString());
            }
      }
}


using namespace System;
public ref class MyClass{};

int main()
{
   MyClass^ my = gcnew MyClass;
   String^ s = "sometext";
   try
   {
      int i = s->CompareTo( my );
   }
   catch ( Exception^ e ) 
   {
      Console::WriteLine( "Error: {0}", e->ToString() );
   }

}

Version Information

.NET Framework

Supported in: 4, 3.5, 3.0, 2.0, 1.1, 1.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Platforms

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Reference