Функция CompareStringEx

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

Синтаксис

Параметры

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

Значение	Предназначение
LOCALE_NAME_SYSTEM_DEFAULT	Язык страны (местности) системы - значение по умолчанию.
LOCALE_NAME_USER_DEFAULT	Язык страны (местности) текущего пользователя - значение по умолчанию.

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

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

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

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

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

[in] Зарезервирован. Должен быть NULL.

[in] Зарезервирован. Должен быть NULL.

[in] Зарезервирован. Должен быть нуль.

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

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

Чтобы поддержать соглашение времени выполнения C при  сравнении строк, значение 2 может быть вычтено из возвращаемого значения отличного от нуля. Тогда значение <0, == 0 и > 0 являются совместимыми с параметрами времени выполнения программы C.

Замечания

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

Обычно, функции CompareStringEx, CompareString, lstrcmp и lstrcmpi оценивают в строке символ за символом. Однако, у многих языков есть многосимвольные элементы, такие как двухсимвольная пара 'CH' в традиционном испанском языке. Функция CompareStringEx используя язык страны (местности) обозначает параметром 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, CompareStringEx, LCMapString, FindNLSString, LCMapStringEx и FindNLSStringEx по умолчанию используют сортировку слов, но если их вызывающая программа устанавливает флажок SORT_STRINGSORT, то используется сортировка строк.

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

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

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

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

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

  CompareStringEx(LOCALE_INVARIANT, NORM_IGNORECASE, mystr, -1, L"InLap", -1, NULL, NULL, 0);

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

Выполнение

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

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

Флажок 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; то есть строки считаются "равными" в смысле сопоставления, хотя они не обязательно идентичны.

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

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

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

Пример

Пример, показывающий использование этой функции, может быть найден в статье Поддержка национальных языков (NLS): Примеры API основанных на названиях местности.

Смотри также

Обзор Строки, Функции, используемые строками, Информация о пользовательском языке страны (местности), Контроль версий сопоставления,  FoldString, CompareString, CompareStringOrdinal, GetSystemDefaultLocaleName, GetUserDefaultLocaleName, IsNLSDefinedString, LCMapStringEx, FindNLSStringEx, lstrcmp, lstrcmpi