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

Windows 95: Supported.
Windows 98: Supported.
Windows NT: Requires Windows NT 3.1 or later.
Windows 2000: Supported.
Windows CE: Requires Windows CE 1.0 or later.

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