Функция CompareStringEx (stringapiset.h)

Статья
08/26/2023

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

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

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

Синтаксис

int CompareStringEx(
  [in, optional] LPCWSTR                          lpLocaleName,
  [in]           DWORD                            dwCmpFlags,
  [in]           _In_NLS_string_(cchCount1)LPCWCH lpString1,
  [in]           int                              cchCount1,
  [in]           _In_NLS_string_(cchCount2)LPCWCH lpString2,
  [in]           int                              cchCount2,
  [in, optional] LPNLSVERSIONINFO                 lpVersionInformation,
  [in, optional] LPVOID                           lpReserved,
  [in, optional] LPARAM                           lParam
);

Параметры

[in, optional] lpLocaleName

Указатель на имя языкового стандарта или одно из следующих предопределенных значений.

[in] dwCmpFlags

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

Flag	Значение
LINGUISTIC_IGNORECASE	Игнорируйте регистр в соответствии с лингвистическим подходом.
LINGUISTIC_IGNOREDIACRITIC	Игнорируйте символы, не относящиеся к лингвистическому значению. Примечание Этот флаг не всегда дает прогнозируемые результаты при использовании с разложенными символами, т. е. символами, в которых базовый символ и один или несколько символов без знака имеют отдельные значения кодовых точек.
NORM_IGNORECASE	Игнорировать регистр. Для многих сценариев (особенно латинских) NORM_IGNORECASE совпадает с LINGUISTIC_IGNORECASE. Примечание NORM_IGNORECASE игнорирует любое третичное различие, независимо от того, является ли это на самом деле лингвистическим случаем или нет. Например, в арабском и индическом письмах это различает альтернативные формы символа, но различия не соответствуют лингвистическому регистру. LINGUISTIC_IGNORECASE приводит к тому, что функция игнорирует только фактические лингвистические регистры вместо игнорирования третьего веса сортировки. Примечание При наборе этого флага функция игнорирует различие между широкими и узкими формами символов совместимости CJK.
NORM_IGNOREKANATYPE	Не следует различать символы хираганы и катаканы. Соответствующие символы хираганы и катаканы сравниваются как равные.
NORM_IGNORENONSPACE	Пропускать символы, не относящиеся к разделу. Для многих сценариев (в частности, латинских) NORM_IGNORENONSPACE совпадает с LINGUISTIC_IGNOREDIACRITIC. Примечание NORM_IGNORENONSPACE игнорирует любые вторичные различия, будь то диакритические или нет. В письмах для корейского, японского, китайского и индического языков, среди прочего, это различие используется для целей, отличных от диакритических. LINGUISTIC_IGNOREDIACRITIC приводит к тому, что функция игнорирует только фактические диакритические значения вместо игнорирования второго веса сортировки. Примечание NORM_IGNORENONSPACE влияет только на языковые стандарты, в которых символы с диакритических знаков сортируются по второму проходу из main символов. Обычно все символы в строке сначала сравниваются без учета диакритических знаков, а если строки равны, выполняется второй проход по строкам для сравнения акцентов. Этот флаг приводит к тому, что второй проход не выполняется. Для языковых стандартов, которые сортируют символы с диакритических знаков в первом проходе, этот флаг не имеет никакого влияния.
NORM_IGNORESYMBOLS	Игнорируйте символы и знаки препинания.
NORM_IGNOREWIDTH	Игнорируйте разницу между полуширинными и полноширинными символами, например C a t == cat. Полноширинная форма — это различие форматирования, используемое в китайских и японских письмах.
NORM_LINGUISTIC_CASING	Используйте лингвистические правила по умолчанию для регистра вместо правил файловой системы. Обратите внимание, что в большинстве сценариев для CompareStringEx используется этот флаг. Этот флаг не требуется использовать при вызове приложением CompareStringOrdinal.
SORT_DIGITSASNUMBERS	Windows 7: Рассматривайте цифры как числа во время сортировки, например сортируйте "2" перед "10".
SORT_STRINGSORT	Знаки препинания обрабатываются так же, как символы.

[in] lpString1

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

[in] cchCount1

Длина строки, указанной lpString1, за исключением завершающего символа NULL. Приложение может предоставить отрицательное значение, если строка завершается null. В этом случае функция определяет длину автоматически.

[in] lpString2

Указатель на вторую строку для сравнения.

[in] cchCount2

Длина строки, указываемой lpString2, за исключением завершающего символа NULL. Приложение может предоставить отрицательное значение, если строка завершается null. В этом случае функция определяет длину автоматически.

[in, optional] lpVersionInformation

Указатель на структуру NLSVERSIONINFOEX , содержащую сведения о версии соответствующей возможности NLS; обычно извлекается из GetNLSVersionEx.

Windows Vista, Windows 7: Защищены; параметр должен иметь значение NULL.

[in, optional] lpReserved

Защищены; параметр должен иметь значение NULL.

[in, optional] lParam

Защищены; значение должно иметь значение 0.

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

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

CSTR_LESS_THAN. Строка, указываемая lpString1 , меньше по лексическому значению, чем строка, указанная lpString2.
CSTR_EQUAL. Строка, указываемая lpString1 , эквивалентна лексическому значению строки, указанной lpString2. Две строки эквивалентны для целей сортировки, хотя и не обязательно идентичны.
CSTR_GREATER_THAN. Строка, указываемая lpString1 , больше по лексическому значению, чем строка, указанная lpString2.

Функция возвращает значение 0, если не удалось. Чтобы получить расширенные сведения об ошибке, приложение может вызвать Метод GetLastError, который может возвращать один из следующих кодов ошибок:

ERROR_INVALID_FLAGS. Значения, указанные для флагов, были недопустимыми.
ERROR_INVALID_PARAMETER. Любое из значений параметров было недопустимым.

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

И CompareString, и CompareStringEx игнорируют арабские кашиды во время сравнения. Таким образом, если две строки идентичны, за исключением наличия kashidas, функция возвращает CSTR_EQUAL.

Если приложение использует флаги NORM_IGNORENONSPACE и NORM_IGNORECASE с функцией сортировки, флаги иногда могут мешать сравнениям строк. Эта ситуация может привести к языковому стандарту, который не поддерживает символы без интервалов или регистр, но использует эквивалентные уровни веса для обработки других важных операций. В таких случаях приложение должно использовать флаги LINGUISTIC_IGNOREDIACRITIC и LINGUISTIC_IGNORECASE. Эти флаги предоставляют лингвистически подходящие результаты для сортировки кодовых точек, которые используют варианты использования и диакритические метки, и не влияют на другие кодовые точки.

Начиная с Windows Vista: И CompareString, и CompareStringEx могут извлекать данные из пользовательских языковых стандартов. Данные не обязательно будут одинаковыми с компьютера на компьютер или между запусками приложения. Если приложение должно сохранять или передавать данные, см. статью Использование данных сохраняемого языкового стандарта.

Начиная с Windows 8. Если приложение передает языковые теги в эту функцию из пространства имен Windows.Globalization, оно должно сначала преобразовать теги, вызвав ResolveLocaleName.

Начиная с Windows 8: CompareStringEx объявляется в Stringapiset.h. До Windows 8 он был объявлен в Winnls.h.

Примечание Поведение сортировки может меняться между выпусками Windows. Например, могут быть созданы новые кодовые точки Юникода. Используйте GetNlsVersionEx , чтобы определить, изменилась ли версия сортировки.

Примеры

Пример использования этой функции можно найти в разделе Пример API на основе имен NLS.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2008 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	stringapiset.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll