Функция FindNLSStringEx (winnls.h)

Статья
08/27/2023

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

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

Синтаксис

int FindNLSStringEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwFindNLSStringFlags,
  [in]            LPCWSTR          lpStringSource,
  [in]            int              cchSource,
  [in]            LPCWSTR          lpStringValue,
  [in]            int              cchValue,
  [out, optional] LPINT            pcchFound,
  [in, optional]  LPNLSVERSIONINFO lpVersionInformation,
  [in, optional]  LPVOID           lpReserved,
  [in, optional]  LPARAM           sortHandle
);

Параметры

[in, optional] lpLocaleName

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

[in] dwFindNLSStringFlags

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

Значение	Значение
FIND_FROMSTART	Выполните поиск по строке, начиная с первого символа строки.
FIND_FROMEND	Поиск строки в обратном направлении, начиная с последнего символа строки.
FIND_STARTSWITH	Проверьте, является ли значение, указанное lpStringValue , первым значением в исходной строке, указанной lpStringSource.
FIND_ENDSWITH	Проверьте, является ли значение, указанное lpStringValue , последним значением в исходной строке, указанной lpStringSource.

Приложение может использовать флаги фильтрации, определенные ниже, в сочетании с флагом поиска.

Значение	Значение
LINGUISTIC_IGNORECASE	Игнорирование регистра в поиске в соответствии с лингвистическим подходом. Дополнительные сведения см. в разделе «Примечания».
LINGUISTIC_IGNOREDIACRITIC	Игнорируйте диакритические знаки, если это лингвистически уместно. Дополнительные сведения см. в разделе «Примечания». Примечание Этот флаг не всегда дает прогнозируемые результаты при использовании с разложенными символами, т. е. символами, в которых базовый символ и один или несколько символов без знака имеют отдельные значения кодовых точек.
NORM_IGNORECASE	Игнорировать регистр в поиске. Дополнительные сведения см. в разделе «Примечания».
NORM_IGNOREKANATYPE	Не следует различать символы хираганы и катаканы. Соответствующие символы хираганы и катаканы сравниваются как равные.
NORM_IGNORENONSPACE	Пропускать символы, не относящиеся к разделу. Дополнительные сведения см. в разделе «Примечания».
NORM_IGNORESYMBOLS	Игнорируйте символы и знаки препинания.
NORM_IGNOREWIDTH	Игнорируйте разницу между полуширинными и полноширинными символами, например C a t == cat. Полноширинная форма — это различие форматирования, используемое в китайских и японских письмах.
NORM_LINGUISTIC_CASING	Используйте лингвистические правила для регистра вместо правил файловой системы (по умолчанию). Дополнительные сведения см. в разделе «Примечания».

[in] lpStringSource

Указатель на исходную строку, в которой функция ищет строку, заданную lpStringValue.

[in] cchSource

Размер в символах, за исключением завершающего символа NULL строки, указанной lpStringSource. Приложение не может указать 0 или любое отрицательное число, отличное от -1, для этого параметра. Приложение указывает -1, если исходная строка завершается null и функция должна вычислять размер автоматически.

[in] lpStringValue

Указатель на строку поиска, для которой функция выполняет поиск в исходной строке.

[in] cchValue

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

[out, optional] pcchFound

Указатель на буфер, содержащий длину строки, которую находит функция. Строка может быть длиннее или короче строки поиска. Если функции не удается найти строку поиска, этот параметр не изменяется.

Функция может получить значение NULL в этом параметре. В этом случае функция не указывает, отличается ли длина найденной строки от длины исходной строки.

Обратите внимание, что значение pcchFound часто идентично значению, указанному в cchValue, но может отличаться в следующих случаях:

Значение, указанное в cchValue , отрицательное.
Строки эквивалентны, но имеют разную длину. Например, "A" и "Объединяющее кольцо" (U+0041 U+030A) эквивалентно "кольцо A" (U+00c5).

[in, optional] lpVersionInformation

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

[in, optional] lpReserved

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

[in, optional] sortHandle

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

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

В случае успешного выполнения возвращает индекс на основе 0 в исходную строку, указанную lpStringSource . В сочетании со значением в pcchFound этот индекс предоставляет точное расположение всей найденной строки в исходной строке. Возвращаемое значение 0 является индексом без ошибок в исходной строке, а соответствующая строка находится в исходной строке со смещением 0.

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

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

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

По умолчанию эта функция сопоставляет нижний регистр "i" с верхним регистром "I", даже если параметр Locale указывает турецкий (Турция) или азербайджанский (Азербайджан). Чтобы переопределить это поведение для турецкого или азербайджанского языка, приложение должно указать NORM_LINGUISTIC_CASING. Если этот флаг указан для правильного языкового стандарта, "ı" (нижний регистр без точек I) — это строчная форма "I" (прописная буква I), а "i" (строчная точка I) — строчная форма "ı" (точечная буква I).

Для многих сценариев (в частности, латинских) NORM_IGNORENONSPACE совпадает с LINGUISTIC_IGNOREDIACRITIC, а NORM_IGNORECASE совпадает с LINGUISTIC_IGNORECASE, за следующими исключениями:

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

В отличие от других функций API NLS, которые возвращают 0 для сбоя, эта функция возвращает -1 в случае сбоя. При успешном выполнении возвращается индекс на основе 0. Использование этого индекса помогает функции избежать ошибок по одному и переполнения буфера с одним символом.

Эта функция является одной из немногих функций NLS, которая вызывает SetLastError даже при успешном выполнении. Этот вызов выполняется для очистки последней ошибки в потоке, если она не соответствует строке поиска. Это очищает значение, возвращаемое GetLastError.

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

Требования


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