Export (0) Print
Expand All

String.CompareTo Method (String)

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

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

Public Function CompareTo ( _
	strB As String _
) As Integer


Type: System.String

The string to compare with this instance.

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.



Less than zero

This instance precedes strB.


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

Greater than zero

This instance follows strB.


strB is Nothing.


IComparable(Of T).CompareTo(T)

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.

Caution noteCaution

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.

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

This method implements the System.IComparable(Of T) interface and performs slightly better than the String.CompareTo(Object) method, because it does not have to determine whether the value argument is a mutable value type that must be boxed, and it does not have to cast its parameter from an Object to a String.

Notes to Callers

Character sets include ignorable characters. The CompareTo(String) method does not consider such characters when it performs a culture-sensitive comparison. For example, if the following code is run on the .NET Framework 4 or later, a comparison of "animal" with "ani-mal" (using a soft hyphen, or U+00AD) indicates that the two strings are equivalent.

Module Example
   Public Sub Main()
      Dim s1 As String = "ani" + ChrW(&h00AD) + "mal" 
      Dim s2 As String = "animal"

      Console.WriteLine("Comparison of '{0}' and '{1}': {2}", 
                        s1, s2, s1.CompareTo(s2))
  End Sub 
End Module 
' The example displays the following output: 
'       Comparison of 'ani-mal' and 'animal': 0

To recognize ignorable characters in a string comparison, call the CompareOrdinal(String, String) method.

The following example demonstrates how you can use the CompareTo method with another String.

Imports System

Public Class CompareToTest

    Public Shared Sub Main()
        Dim strFirst As String = "Goodbye" 
        Dim strSecond As String = "Hello" 
        Dim strThird As String = "a small string" 
        Dim strFourth As String = "goodbye" 

        ' compare a string to itself
        Console.WriteLine(CompareStrings(strFirst, strFirst))

        Console.WriteLine(CompareStrings(strFirst, strSecond))
        Console.WriteLine(CompareStrings(strFirst, strThird))

        ' compare a string to another string that varies only by case
        Console.WriteLine(CompareStrings(strFirst, strFourth))
        Console.WriteLine(CompareStrings(strFourth, strFirst))
    End Sub 'Main

    Private Shared Function CompareStrings(str1 As String, str2 As String) As String 
        Dim cmpVal As Integer = str1.CompareTo(str2)
        If cmpVal = 0 Then 

            ' compare the values, using the CompareTo method on the first string 

            ' the values are the same 
            Return "The strings have the same value!" 
            If cmpVal > 0 Then 

                ' the first value is greater than the second value 
                Return "The first string is greater than the second string!" 

                ' the second string is greater than the first string 
                Return "The second string is greater than the first string!" 
            End If 
        End If 
    End Function 'CompareStrings
End Class 'CompareToTest

' This code example displays the following: 

' The strings have the same value! 
' The second string is greater than the first string! 
' The first string is greater than the second string! 
' The first string is greater than the second string! 
' The second string is greater than the first string!

The following example demonstrates generic and non-generic versions of the CompareTo method for several value and reference types.

' This example demonstrates the generic and non-generic versions of the  
' CompareTo method for several base types. 
' The non-generic version takes a parameter of type Object, while the generic 
' version takes a type-specific parameter, such as Boolean, Int32, or Double. 

Imports System

Class Sample
   Public Shared Sub Main()
      Dim nl As String = Environment.NewLine
      Dim msg As String = _
          "{0}The following is the result of using the generic and non-generic{0}" & _
          "versions of the CompareTo method for several base types:{0}" 

      Dim now As DateTime = DateTime.Now
      ' Time span = 11 days, 22 hours, 33 minutes, 44 seconds 
      Dim tsX As New TimeSpan(11, 22, 33, 44)
      ' Version = 1.2.333.4 
      Dim versX As New Version("1.2.333.4")
      ' Guid = CA761232-ED42-11CE-BACD-00AA0057B223 
      Dim guidX As New Guid("{CA761232-ED42-11CE-BACD-00AA0057B223}")

      Dim a1 As [Boolean] = True,    a2 As [Boolean] = True 
      Dim b1 As [Byte] = 1,          b2 As [Byte] = 1
      Dim c1 As Int16 = -2,          c2 As Int16 = 2
      Dim d1 As Int32 = 3,           d2 As Int32 = 3
      Dim e1 As Int64 = 4,           e2 As Int64 = -4
      Dim f1 As [Decimal] = -5.5D,   f2 As [Decimal] = 5.5D
      Dim g1 As [Single] = 6.6F,     g2 As [Single] = 6.6F
      Dim h1 As [Double] = 7.7,      h2 As [Double] = -7.7
      Dim i1 As [Char] = "A"c,       i2 As [Char] = "A"c
      Dim j1 As String = "abc",      j2 As String = "abc" 
      Dim k1 As DateTime = now,      k2 As DateTime = now
      Dim l1 As TimeSpan = tsX,      l2 As TimeSpan = tsX
      Dim m1 As Version = versX,     m2 As New Version("2.0")
      Dim n1 As Guid = guidX,        n2 As Guid = guidX

      ' The following types are not CLS-compliant. 
      ' SByte, UInt16, UInt32, UInt64

      Console.WriteLine(msg, nl)
         ' The second and third Show method call parameters are automatically boxed because 
         ' the second and third Show method declaration arguments expect type Object.

         Show("Boolean:  ", a1, a2, a1.CompareTo(a2), a1.CompareTo(CObj(a2)))
         Show("Byte:     ", b1, b2, b1.CompareTo(b2), b1.CompareTo(CObj(b2)))
         Show("Int16:    ", c1, c2, c1.CompareTo(c2), c1.CompareTo(CObj(c2)))
         Show("Int32:    ", d1, d2, d1.CompareTo(d2), d1.CompareTo(CObj(d2)))
         Show("Int64:    ", e1, e2, e1.CompareTo(e2), e1.CompareTo(CObj(e2)))
         Show("Decimal:  ", f1, f2, f1.CompareTo(f2), f1.CompareTo(CObj(f2)))
         Show("Single:   ", g1, g2, g1.CompareTo(g2), g1.CompareTo(CObj(g2)))
         Show("Double:   ", h1, h2, h1.CompareTo(h2), h1.CompareTo(CObj(h2)))
         Show("Char:     ", i1, i2, i1.CompareTo(i2), i1.CompareTo(CObj(i2)))
         Show("String:   ", j1, j2, j1.CompareTo(j2), j1.CompareTo(CObj(j2)))
         Show("DateTime: ", k1, k2, k1.CompareTo(k2), k1.CompareTo(CObj(k2)))
         Show("TimeSpan: ", l1, l2, l1.CompareTo(l2), l1.CompareTo(CObj(l2)))
         Show("Version:  ", m1, m2, m1.CompareTo(m2), m1.CompareTo(CObj(m2)))
         Show("Guid:     ", n1, n2, n1.CompareTo(n2), n1.CompareTo(CObj(n2)))
         Console.WriteLine("{0}The following types are not CLS-compliant:", nl)
         Console.WriteLine("SByte, UInt16, UInt32, UInt64")

      Catch e As Exception
      End Try 
   End Sub 'Main

   Public Shared Sub Show(caption As String, var1 As [Object], var2 As [Object], _
                          resultGeneric As Integer, resultNonGeneric As Integer)
      Dim relation As String

      If resultGeneric = resultNonGeneric Then 
         If resultGeneric < 0 Then
            relation = "less than" 
         ElseIf resultGeneric > 0 Then
            relation = "greater than" 
            relation = "equal to" 
         End If
         Console.WriteLine("{0} is {1} {2}", var1, relation, var2)

      ' The following condition will never occur because the generic and non-generic 
      ' CompareTo methods are equivalent. 

         Console.WriteLine("Generic CompareTo = {0}; non-generic CompareTo = {1}", _
                            resultGeneric, resultNonGeneric)
      End If 
   End Sub 'Show
End Class 'Sample

'This example produces the following results: 

'The following is the result of using the generic and non-generic versions of the 
'CompareTo method for several base types: 

'Boolean:  True is equal to True 
'Byte:     1 is equal to 1 
'Int16:    -2 is less than 2 
'Int32:    3 is equal to 3 
'Int64:    4 is greater than -4 
'Decimal:  -5.5 is less than 5.5 
'Single:   6.6 is equal to 6.6 
'Double:   7.7 is greater than -7.7 
'Char:     A is equal to A 
'String:   abc is equal to abc 
'DateTime: 12/1/2003 5:37:46 PM is equal to 12/1/2003 5:37:46 PM 
'TimeSpan: 11.22:33:44 is equal to 11.22:33:44 
'Version:  1.2.333.4 is less than 2.0 
'Guid:     ca761232-ed42-11ce-bacd-00aa0057b223 is equal to ca761232-ed42-11ce-bacd-00 

'The following types are not CLS-compliant: 
'SByte, UInt16, UInt32, UInt64 

.NET Framework

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

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Portable Class Library

Supported in: Portable Class Library

.NET for Windows Store apps

Supported in: Windows 8

Supported in: Windows Phone 8.1

Supported in: Windows Phone Silverlight 8.1

Supported in: Windows Phone Silverlight 8

Windows Phone 8.1, Windows Phone 8, Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

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

© 2014 Microsoft