Export (0) Print
Expand All

String.Compare Method (String, String, StringComparison)

Note: This method is new in the .NET Framework version 2.0.

Compares two specified String objects. A parameter specifies whether the comparison uses the current or invariant culture, honors or ignores case, and uses word or ordinal sort rules.

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

public:
static int Compare (
	String^ strA, 
	String^ strB, 
	StringComparison comparisonType
)
public static int Compare (
	String strA, 
	String strB, 
	StringComparison comparisonType
)
public static function Compare (
	strA : String, 
	strB : String, 
	comparisonType : StringComparison
) : int

Parameters

strA

The first String object.

strB

The second String object.

comparisonType

One of the System.StringComparison values.

Return Value

A 32-bit signed integer indicating the lexical relationship between the two comparands.

Value

Condition

Less than zero

strA is less than strB.

Zero

strA equals strB.

Greater than zero

strA is greater than strB.

Exception typeCondition

ArgumentException

comparisonType is not a StringComparison value.

The comparisonType parameter indicates whether the comparison should use the current or invariant culture, honor or ignore the case of the comparands, or use word (culture-sensitive) or ordinal (culture-insensitive) sort rules.

One or both comparands can be a null reference (Nothing in Visual Basic). By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other.

The comparison terminates when an inequality is discovered or both strings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, the string with remaining characters is considered greater. The return value is the result of the last comparison performed.

Unexpected results can occur when comparisons are affected by culture-specific casing rules. For example, in Turkish, the following example yields the wrong results because the file system in Turkish does not use linguistic casing rules for the letter 'i' in "file".

static String IsFileURI(String path) { 
    return (String.Compare(path, 0, "file:", 0, 5, true)== 0); }

Compare the path name to "file" using an ordinal comparison. The correct code to do this is as follows:

 static String IsFileURI(String path) { 
    return (String.Compare(path, 0, "file:", 0, 5, true, StringComparison.OrdinalIgnoreCase)== 0); }

The following code example compares three versions of the letter 'I'. The results are affected by the choice of culture, whether case is ignored, and whether an ordinal comparison is performed.

// This example demonstrates the
// System.String.Compare(String, String, StringComparison) method.

using namespace System;
using namespace System::Threading;

void Test(int testStringIndex, int searchStringIndex, 
          StringComparison comparison, array<String^>^ testI, 
          array<String^>^ testNames)
{
    String^ resultFormat = "{0} is {1} {2}";
    String^ resultString = "equal to";
    int comparisonValue = 0;

    comparisonValue = String::Compare(testI[testStringIndex],
        testI[searchStringIndex], comparison);
    if (comparisonValue < 0)
    {
        resultString = "less than";
    }
    else if (comparisonValue > 0)
    {
        resultString = "greater than";
    }
    Console::WriteLine(resultFormat, testNames[testStringIndex], resultString,
        testNames[searchStringIndex]);
}

int main()
{
    String^ introMessage =
        "Compare three versions of the letter I using different " +
        "values of StringComparison.";

    // Define an array of strings where each element contains a version of
    // the letter I. (An array of strings is used so you can easily modify
    // this code example to test additional or different combinations of
    // strings.)

    array<String^>^ letterVariation = gcnew array<String^>(3);
    // LATIN SMALL LETTER I (U+0069)
    letterVariation[0] = "i";
    // LATIN SMALL LETTER DOTLESS I (U+0131)
    letterVariation[1] = L"\u0131";
    // LATIN CAPITAL LETTER I (U+0049)
    letterVariation[2] = "I";

    array<String^>^ unicodeNames = {
        "LATIN SMALL LETTER I (U+0069)",
        "LATIN SMALL LETTER DOTLESS I (U+0131)",
        "LATIN CAPITAL LETTER I (U+0049)"};

    array<StringComparison>^ comparisonValues = {
        StringComparison::CurrentCulture,
        StringComparison::CurrentCultureIgnoreCase,
        StringComparison::InvariantCulture,
        StringComparison::InvariantCultureIgnoreCase,
        StringComparison::Ordinal,
        StringComparison::OrdinalIgnoreCase};

    Console::Clear();
    Console::WriteLine(introMessage);

    // Display the current culture because the culture-specific comparisons
    // can produce different results with different cultures.
    Console::WriteLine("The current culture is {0}.{1}",
        Thread::CurrentThread->CurrentCulture->Name, Environment::NewLine);

    // Determine the relative sort order of three versions of the letter I.
    for each (StringComparison stringCmp in comparisonValues)
    {
        Console::WriteLine("StringComparison.{0}:", stringCmp);

        // LATIN SMALL LETTER I (U+0069) : LATIN SMALL LETTER DOTLESS I
        // (U+0131)
        Test(0, 1, stringCmp, letterVariation, unicodeNames);

        // LATIN SMALL LETTER I (U+0069) : LATIN CAPITAL LETTER I (U+0049)
        Test(0, 2, stringCmp, letterVariation, unicodeNames);

        // LATIN SMALL LETTER DOTLESS I (U+0131) : LATIN CAPITAL LETTER I
        // (U+0049)
        Test(1, 2, stringCmp, letterVariation, unicodeNames);

        Console::WriteLine();
    }
}

/*
This code example produces the following results:

Compare three versions of the letter I using different values of 
StringComparison.
The current culture is en-US.

StringComparison.CurrentCulture:
LATIN SMALL LETTER I (U+0069) is less than LATIN SMALL LETTER 
  DOTLESS I (U+0131)
LATIN SMALL LETTER I (U+0069) is less than LATIN CAPITAL LETTER I (U+0049)
LATIN SMALL LETTER DOTLESS I (U+0131) is greater than LATIN 
  CAPITAL LETTER I (U+0049)

StringComparison.CurrentCultureIgnoreCase:
LATIN SMALL LETTER I (U+0069) is less than LATIN SMALL LETTER 
  DOTLESS I (U+0131)
LATIN SMALL LETTER I (U+0069) is equal to LATIN CAPITAL LETTER I (U+0049)
LATIN SMALL LETTER DOTLESS I (U+0131) is greater than LATIN 
  CAPITAL LETTER I (U+0049)

StringComparison.InvariantCulture:
LATIN SMALL LETTER I (U+0069) is less than LATIN SMALL LETTER 
  DOTLESS I (U+0131)
LATIN SMALL LETTER I (U+0069) is less than LATIN CAPITAL LETTER I (U+0049)
LATIN SMALL LETTER DOTLESS I (U+0131) is greater than LATIN 
  CAPITAL LETTER I (U+0049)

StringComparison.InvariantCultureIgnoreCase:
LATIN SMALL LETTER I (U+0069) is less than LATIN SMALL LETTER 
  DOTLESS I (U+0131)
LATIN SMALL LETTER I (U+0069) is equal to LATIN CAPITAL LETTER I (U+0049)
LATIN SMALL LETTER DOTLESS I (U+0131) is greater than LATIN 
  CAPITAL LETTER I (U+0049)

StringComparison.Ordinal:
LATIN SMALL LETTER I (U+0069) is less than LATIN SMALL LETTER 
  DOTLESS I (U+0131)
LATIN SMALL LETTER I (U+0069) is greater than LATIN CAPITAL LETTER I (U+0049)
LATIN SMALL LETTER DOTLESS I (U+0131) is greater than LATIN 
  CAPITAL LETTER I (U+0049)

StringComparison.OrdinalIgnoreCase:
LATIN SMALL LETTER I (U+0069) is less than LATIN SMALL LETTER 
  DOTLESS I (U+0131)
LATIN SMALL LETTER I (U+0069) is equal to LATIN CAPITAL LETTER I (U+0049)
LATIN SMALL LETTER DOTLESS I (U+0131) is greater than LATIN 
  CAPITAL LETTER I (U+0049)

*/

Windows 98, Windows 2000 SP4, Windows Millennium Edition, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

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

.NET Framework

Supported in: 2.0

.NET Compact Framework

Supported in: 2.0

Community Additions

ADD
Show:
© 2014 Microsoft