Функция CompareString

Функция CompareString сравнивает две строки символов, используя указанный язык страны (местности).

Синтаксис

Параметры

[in] Указывает язык страны (местности), используемый для сопоставления. Этот параметр может быть одним из нижеследующих предопределенных локализующих идентификаторов. Этот параметр может также быть локализующим идентификатором, созданным макрокомандой MAKELCID. Для получения дополнительной информации об идентификаторах территорий, см. раздел Языки стран (местностей).

[in] Набор флажков, которые указывают, как функция сравнивает две строки. По умолчанию, эти флажки не устанавливаются. Этот параметр может быть установлен в нуль, чтобы получить поведение по умолчанию, или это может быть любая комбинация нижеследующих значений.

[in] Указатель на первую строку, которая будет сравниваться.

[in] Указывает, что число TCHARs в строке указано при помощи параметра lpString1. Это относится к байтам для версий функции ANSI или WCHARs для версий Unicode. Подсчет не включает в себя символ конца строки ("0"). Если этот параметр - какое-либо отрицательное значение, то предполагается, что строка завершается нулем, а длина вычисляется автоматически.

[in] Указатель на вторую строку, которая будет сравниваться.

[in] Указывает, что число TCHARs в строке указано при помощи параметра lpString2. Подсчет не включает в себя символ конца строки ("0"). Если этот параметр - какое-либо отрицательное значение, то предполагается, что строка завершается нулем, а длина вычисляется автоматически.

Возвращаемое значение

Если функция завершается успешно, возвращаемое значение - одно из ниже перечисленных значений.

Замечания

Эквивалентные строки

Обычно, функции CompareString, CompareStringEx, lstrcmp и lstrcmpi оценивают в строке символ за символом. Однако, у многих языков есть многосимвольные элементы, такие как двухсимвольная пара 'CH' в традиционном испанском языке. Функция CompareString и CompareStringEx используя язык страны (местности) передает в параметр Locale (или lpLocaleName) идентификаторы многосимвольных элементов, в то время как функции lstrcmp и lstrcmpi, используют язык страны (местности) установленные для потока.

Другой пример - вьетнамский язык, который содержит много двухсимвольных элементов, таких как допустимый класс прописных букв, стиль заголовка и формы нижнего регистра 'GI', которые являются 'GI', 'Gi', и 'gi' соответственно. Любая из этих форм обрабатывается как единичный элемент сопоставления и, если регистр игнорируется, сравнивает как эквивалентные. Однако, поскольку элемент 'gI' не имеет силы, как единичный элемент, функции CompareString, CompareStringEx, lstrcmp и lstrcmpi обрабатывают 'gI' как два отдельных элемента.

Напротив, функция CompareStringOrdinal, включенная в Windows Vista, выполняет строго двоичное (бинарное) сравнение: исключая вариант выбора нечувствительности к регистру, это опция игнорирует все недвоичные эквивалентности, и (в отличие от CompareString) она проверяет все точки кодирования на равенство, включая и те, которые не дают какой-либо нагрузки в лингвистических схемах сопоставления.

Оценка строк

Как правило, строки сравниваются, используя, что называется методикой "сортировки слова". При сортировке слов, все знаки препинания и другие неалфавитно-цифровые символы, за исключением дефиса и апострофа, приходят прежде какого-либо буквенно-цифрового символа. Дефис и апостроф обрабатываются по-другому, а не как другие небуквенно-цифровые символы по порядку, для того, чтобы гарантировать, что слова такие как "coop" и "co-op" остались вместе внутри отсортированного списка.

Если флажок SORT_STRINGSORT установлен, то строки сравниваются, используя то, что называется методикой "сортировки строк". При сортировке строки дефис и апостроф обрабатываются точно так же, как и любые другие небуквенно-цифровые символы: они приходят перед буквенно-цифровыми символами.

Нижеследующая таблица показывает список слов, отсортированных этими способами.

Функции lstrcmp и lstrcmpi используют сортировку слов. Функции CompareString, LCMapString и FindNLSString (и, соответственно,  базирующиеся на наименовании территорий функции CompareStringEx, LCMapStringEx и FindNLSStringEx) по умолчанию используют сортировку слов, но если их вызывающая программа устанавливает флажок SORT_STRINGSORT, то используется сортировка строк.

Когда используются функции CompareString, lstrcmp, и lstrcmpi

Когда сравнение должно следовать за персональными языковыми настройками пользователя, например, когда сортируются по порядку элементы органа управления Одноуровневого просмотрщика (ListView), сделайте одно из нижеследующего:

• Вызовите функцию lstrcmp или lstrcmpi, которые используют пользовательский язык страны, или
• Вызовите функцию CompareString или CompareStringEx, чтобы определить язык страны для сравнения, передать дополнительные флажки, встроить нулевые (пустые) символы, или передать точные длины, чтобы было соответствие частям строки.

Когда результаты сравнения должны быть непротиворечивыми независимо от языка страны (местности), например при сравнении извлеченных данных, опираясь на предопределенный список или внутреннее значение, то используется CompareString. Любой из нижеследующих вызовов будет соответствовать даже тогда, когда параметр mystr - "INLAP", тогда как чувствительный к языку страны (местности) вызов функции lstrcmpi завершается ошибкой, если текущий язык страны (местности) - вьетнамский язык.

• в среде Windows XP и позже:

  CompareString(LOCALE_INVARIANT, NORM_IGNORECASE, mystr, -1, _T("InLap"), -1);

   

• для более ранних операционных систем:

  DWORD lcid = MAKELCID(MAKELANGID(LANG_ENGLISH, SUBLANG_ENGLISH_US), SORT_DEFAULT); CompareString(lcid, NORM_IGNORECASE, mystr, -1, _T("InLap"), -1);

Функция CompareString может возвратить данные из пользовательских языков страны (custom locales). Пользовательские языки страны дают возможность администраторам изменять любые аспекты форматов местного языка, но это не будет изменять поведение операции сравнения.

Программы, которые предназначаются для того, чтобы выполняться только в среде Windows Vista и позже должны использовать CompareStringEx в предпочтении к этой функции. CompareStringEx оказывает хорошую поддержку для дополнительных местных языков (supplemental locales). Однако, CompareStringEx не поддерживается в версиях Windows до Windows Vista.

Выполнение

Функция CompareString оптимизирована так, чтобы выполняться с самой высокой скоростью, когда параметр dwCmpFlags установлен в 0 или со значением NORM_IGNORECASE, а у параметров cchCount1 и  cchCount2 установлены значения -(минус)1, а заданный язык страны (местности) не поддерживает какие-либо лингвистические свертки (типа того, когда в традиционном испанском языке сравнение рассматривает "ch" как единичный символ).

Заметки об особенностях языка

Если Вы вызываете версию ASCII (CompareStringA), то, функция делает преобразование не через системную кодовую страницу по умолчанию, а преобразует параметры через кодовую страницу языка страны (местности) по умолчанию, который Вы определили. Между прочим, это означает, что Вы никогда не сможете использовать CompareStringA, чтобы обработать 8-битовый текст формата (UTF-8) Unicode.

Флажок NORM_IGNORENONSPACE влияет только на языки стран, в которых, диакритические знаки сортируются при повтором проходе основных символов. Все символы в строке сначала сравниваются не принимая во внимание диакритические знаки и (если строки равны) при втором проходе по строкам, выполняется сравнение диакритических знаков. В этом случае, этот флажок заставляет второй проход не выполнять. Для языков, которые сортируют диакритические знаки символов при первом проходе, этот флажок не имеет никакого действия.

Для многих систем письма флажок NORM_IGNORENONSPACE совпадает с действием флажка LINGUISTIC_IGNOREDIACRITIC, а NORM_IGNORECASE совпадает с флажком LINGUISTIC_IGNORECASE. Особенно это правдиво для латинских алфавитов. Однако:

• NORM_IGNORENONSPACE игнорирует любое "второе распознавание", является ли это фактически диакритическим знаком или нет. Системы письма для корейского, японского, китайского языка и относящиеся к Индии языки (в том числе) используют это распознавание для других целей, а не для диакритических знаков. Флажок LINGUISTIC_IGNOREDIACRITIC игнорирует только фактические диакритические знаки, вместо того, чтобы просто игнорировать второе по значимости сопоставление.
• NORM_IGNORECASE игнорирует любое "третье распознавание", является ли это фактически лингвистическим случаем или нет. Например, в арабских и относящихся к Индии письменностях флажок помогает отличать дополнительные формы символа, но различия не соответствуют лингвистическому случаю. LINGUISTIC_IGNORECASE игнорирует только фактический лингвистический регистр, вместо того, чтобы просто игнорировать третье по важности сравнение.

Обычно, для не чувствительного к регистру сравнения, эта функция устанавливает соответствие символов нижнего регистра "i" символам верхнего регистра "I", даже тогда, когда параметр Locale устанавливает турецкий или азербайджанский язык. Флажок NORM_LINGUISTIC_CASING не принимает во внимание это для турецкого или азербайджанского языков. Если этот флажок определяется, в соединении со значением для параметра Locale, который служит признаком турецкого или азербайджанского языка, то ЛАТИНСКАЯ СТРОЧНАЯ БУКВА БЕЗ ТОЧКИ I (U+0131) является формой нижнего регистра ЛАТИНСКОЙ ЗАГЛАВНОЙ БУКВЫ I (U+0049), а ЛАТИНСКАЯ СТРОЧНАЯ БУКВА I (U+0069),  является формой нижнего регистра ЛАТИНСКАЯ ЗАГЛАВНАЯ БУКВА I С ТОЧКОЙ ВЫШЕ (U+0130).

Для набора двухбайтовых символов (DBCS) местных языков флажок NORM_IGNORECASE влияет на все "широкие" (двухбайтовые) символы, а также на "узкие" (однобайтовые) символы. Это включает в себя "широкие" символы греческого языка и кириллицы.

Функция CompareString в ходе сравнения игнорирует арабские кашиды. Таким образом, если две строки идентичны, содержат наличие кашид, функция CompareString возвращает значение 2; то есть строки считаются "равными" в смысле сопоставления, хотя они не обязательно идентичны.

Специфические языки страны (местности)

Windows Vista и позже. Обратите внимание! на то, что тот эта API может возвратить  данные от пользовательских (специальных) языков страны (местности) (см. Пользовательскую информацию о языке страны). Пользовательские языки страны дают возможность администраторам изменять много аспектов форматов языка страны, но они не будет изменять поведение сравнения.

Предупреждение защиты  Используя эту функцию неправильно вы может поставить под угрозу обеспечение безопасности Вашего приложения. Строки, которые сравниваются не правильно, могут создать недопустимые вводимые данные. Проверяйте строки, чтобы гарантировать, что они допустимы, перед использованием их и предусматривайте обработчики ошибок. Для получения дополнительной информации, см. статью Рассмотрения вопроса обеспечения безопасности: Функции интернационализации.

Windows 95/98/Me:  Функция CompareStringW поддерживается Microsoft Layer for Unicode (MSLU). Чтобы использовать MLSU, Вы должны добавить некоторые файлы к своему приложению, как это определено в Microsoft Layer для Unicode для системной среды Windows 95/98/Me.

Смотри также

Обзор Строки, Функции, используемые строками, Информация о пользовательском языке страны (местности), FoldString, CompareStringEx, CompareStringOrdinal, GetSystemDefaultLCID, GetUserDefaultLCID, IsNLSDefinedString, LCMapString, FindNLSString, lstrcmp, lstrcmpi, MAKELCID