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

Статья
08/26/2023

Сравнивает две символьные строки для языкового стандарта , заданного идентификатором.

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

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

Синтаксис

int CompareStringW(
  [in] LCID                              Locale,
  [in] DWORD                             dwCmpFlags,
  [in] _In_NLS_string_(cchCount1)PCNZWCH lpString1,
  [in] int                               cchCount1,
  [in] _In_NLS_string_(cchCount2)PCNZWCH lpString2,
  [in] int                               cchCount2
);

Параметры

[in] Locale

Идентификатор языкового стандарта, используемого для сравнения. Макрос MAKELCID можно использовать для создания идентификатора языкового стандарта или одного из следующих предопределенных значений.

[in] dwCmpFlags

Флаги, указывающие, как функция сравнивает две строки. Подробные определения см. в параметре dwCmpFlagsобъекта CompareStringEx.

[in] lpString1

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

[in] cchCount1

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

[in] lpString2

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

[in] cchCount2

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

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

Возвращает значения, описанные для CompareStringEx.

Если приложение вызывает версию ANSI CompareString, функция преобразует параметры с помощью кодовой страницы по умолчанию указанного языкового стандарта. Таким образом, приложение никогда не может использовать CompareString для обработки текста UTF-8.

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

Начиная с Windows 8: версия функции ANSI объявляется в Winnls.h, а версия Юникода — в Stringapiset.h. До Windows 8 обе версии объявлялись в Winnls.h.

Требования

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