CompareString Function

Declare Function CompareString Lib "kernel32.dll" Alias "CompareStringA" (ByVal Locale As Long, ByVal dwCmpFlags As Long, ByVal lpString1 As String, ByVal cchCount1 As Long, ByVal lpString2 As String, ByVal cchCount2 As Long) As Long

Platforms

Description & Usage

CompareString compares two strings and determines which one would come first in an alphabetic sort. Although this function can use a number of different comparisons, by default it conducts a case-sensitive word sort. In a word sort, all symbols except hyphens and apostrophes come before the letter "a" (hyphens and apostrophes are treated differently). The function compares strings by first comparing their first characters, then their second characters, etc. until an unequal pair of characters is found.

Return Value

If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns one of the following flags specifying the result of the comparison:

CSTR_LESS_THAN
The first string is less than the second string (i.e., the first string comes before the second string in alphabetical order).
CSTR_EQUAL
The first string is equal to (but not necessarily identical to) the second string.
CSTR_GREATER_THAN
The first string is greater than the second string.

Visual Basic-Specific Issues

None.

Parameters

Locale
The locale identifier of the locale to use to compare the strings. This could also be one of the following flags:
LOCALE_SYSTEM_DEFAULT
The system's default locale.
LOCALE_USER_DEFAULT
The user's default locale.
dwCmpFlags
A combination of the following flags specifying options for the comparison. To use the default comparison, set this parameter to 0.
NORM_IGNORECASE
Conduct a case-insensitive search.
NORM_IGNOREKANATYPE
For Japanese characters, do not differentiate between Hiragana and Katakana characters.
NORM_IGNORENONSPACE
Ignore nonspacing characters.
NORM_IGNORESYMBOLS
Ignore symbols.
NORM_IGNOREWIDTH
Do not differentiate between equivalent single-byte and double-byte characters.
SORT_STRINGSORT
Use a string sort instead of a word sort. In a string sort, all symbols, including hyphens and apostrophes, come before the letter "a".
lpString1
The first string to compare.
cchCount1
The length of lpString1. If this is -1, lpString1 must end in a terminating null character.
lpString2
The second string to compare.
cchCount2
The length of lpString2. If this is -1, lpString2 must end in a terminating null character.

Constant Definitions

Const CSTR_LESS_THAN = 1
Const CSTR_EQUAL = 2
Const CSTR_GREATER_THAN = 3
Const LOCALE_SYSTEM_DEFAULT = &H400
Const LOCALE_USER_DEFAULT = &H800
Const NORM_IGNORECASE = &H1
Const NORM_IGNOREKANATYPE = &H10000
Const NORM_IGNORENONSPACE = &H2
Const NORM_IGNORESYMBOLS = &H4
Const NORM_IGNOREWIDTH = &H20000
Const SORT_STRINGSORT = &H1000

Example

' This code is licensed according to the terms and conditions listed here.

' Use a case-senitive, string sort comparison method to alphabetically
' sort nine words.  The sorting method simply compares each possible
' pair of words; if a pair is out of alphabetical order, they are switched.
' (Compare these results to those from using lstrcmp for the comparison.)
Dim words(1 To 9) As String  ' the words to sort
Dim tempstr As String  ' buffer used to swap strings
Dim oc As Integer, ic As Integer  ' counter variables
Dim compval As Long  ' result of comparison
Dim threadlocale As Long  ' locale ID of this thread

' Get the locale of this thread (i.e., of this program).
threadlocale = GetThreadLocale()

' Load the nine strings into the array.
words(1) = "can't"
words(2) = "cant"
words(3) = "cannot"
words(4) = "pants"
words(5) = "co-op"
words(6) = "coop"
words(7) = "Denver"
words(8) = "denver"
words(9) = "denveR"

' Sort the strings, swapping any pairs which are out of order.
For oc = 1 To 8  ' first string of the pair
  For ic = oc + 1 To 9  ' second string of the pair
    ' Compare the two strings.
    compval = CompareString(threadlocale, SORT_STRINGSORT, words(oc), Len(words(oc)), words(ic), Len(words(ic)))
    ' If words(oc) is greater, swap them.
    If compval = CSTR_GREATER_THAN Then
      tempstr = words(oc)
      words(oc) = words(ic)
      words(ic) = tempstr
    End If
  Next ic
Next oc

' Display the list of sorted words.
For oc = 1 To 9
  Debug.Print words(oc)
Next oc

See Also

lstrcmp, lstrcmpi

Category

Strings

Go back to the alphabetical Function listing.
Go back to the Reference section index.


Last Modified: December 30, 1999
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000
Go back to the Windows API Guide home page.
E-mail: vbapi@vbapi.com Send Encrypted E-Mail
This page is at http://www.vbapi.com/ref/c/comparestring.html