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

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

Синтаксис

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

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

• LOCALE_NAME_INVARIANT
• LOCALE_NAME_SYSTEM_DEFAULT
• LOCALE_NAME_USER_DEFAULT

[in] dwCmpFlags

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

[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.

• 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.

Примеры

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

Требования

См. также

CompareString

Пользовательские языковые стандарты

Обработка сортировки в приложениях

Поддержка национальных языков

Функции поддержки национальных языков

Вопросы безопасности: международные функции

Использование нормализации Юникода для представления строк