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

Статья
08/27/2023

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

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

Синтаксис

int LCMapStringEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwMapFlags,
  [in]            LPCWSTR          lpSrcStr,
  [in]            int              cchSrc,
  [out, optional] LPWSTR           lpDestStr,
  [in]            int              cchDest,
  [in, optional]  LPNLSVERSIONINFO lpVersionInformation,
  [in, optional]  LPVOID           lpReserved,
  [in, optional]  LPARAM           sortHandle
);

Параметры

[in, optional] lpLocaleName

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

[in] dwMapFlags

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

Flag	Значение
LCMAP_BYTEREV	Используйте разворот байтов. Например, если приложение передает 0x3450 0x4822, результат будет 0x5034 0x2248.
LCMAP_FULLWIDTH	Используйте символы Юникода (расширенные) там, где это применимо. Этот флаг и LCMAP_HALFWIDTH являются взаимоисключающими. С этим флагом сопоставление может использовать форму нормализации C, даже если входной символ уже имеет полную ширину. Например, полноширинная строка "は゛" нормализуется к виду "ば". См. статью Формы нормализации Юникода.
LCMAP_HALFWIDTH	При необходимости используйте узкие символы. Этот флаг и LCMAP_FULLWIDTH являются взаимоисключающими.
LCMAP_HIRAGANA	Сопоставьте все символы катаканы с хираганой. Этот флаг и LCMAP_KATAKANA являются взаимоисключающими.
LCMAP_KATAKANA	Сопоставьте все символы хираганы с катаканой. Этот флаг и LCMAP_HIRAGANA являются взаимоисключающими.
LCMAP_LINGUISTIC_CASING	Используйте лингвистические правила для регистра вместо правил файловой системы (по умолчанию). Этот флаг действителен только для LCMAP_LOWERCASE или LCMAP_UPPERCASE.
LCMAP_LOWERCASE	Для языковых стандартов и скриптов, способных обрабатывать прописные и строчные регистры, сопоставьте все символы со строчным регистром.
LCMAP_HASH	Возвращает хэш необработанных весовых коэффициентов сортировки строки. Эквивалентные строки обычно возвращают один и тот же хэш (например, "hello" и "HELLO" с LCMAP_IGNORECASE). Однако в некоторых сложных случаях, таких как восточноазиатские языки, могут быть похожие строки с одинаковыми весовыми коэффициентами, которые сравниваются как равные, но не возвращают одинаковый хэш. LCMAP_HASH требуется, чтобы выходной буфер был размером sizeof(int)
LCMAP_SIMPLIFIED_CHINESE	Сопоставьте традиционные китайские символы с символами упрощенного китайского языка. Этот флаг и LCMAP_TRADITIONAL_CHINESE являются взаимоисключающими.
LCMAP_SORTHANDLE Использование дескриптора сортировки приводит к минимальному повышению производительности и не рекомендуется.	Возвращает токен, представляющий разрешенные параметры сортировки для языкового стандарта (например, имя языкового стандарта), чтобы будущие вызовы могли передавать `NULL` имя сортировки и передавать ранее запрошенный дескриптор сортировки в качестве последнего параметра (sortHandle) в последующих вызовах CompareStringEx или LCMapStringEx. LCMAP_SORTHANDLE требуется, чтобы выходной буфер был размером sizeof(lparam)
LCMAP_SORTKEY	Создание нормализованного ключа сортировки. Если флаг LCMAP_SORTKEY не указан, функция выполняет сопоставление строк. Дополнительные сведения о создании ключа сортировки и сопоставлении строк см. в разделе Примечания.
LCMAP_TITLECASE	Windows 7: сопоставьте все символы с регистром заголовка, в котором первая буква каждого основного слова имеет прописную букву.
LCMAP_TRADITIONAL_CHINESE	Сопоставление упрощенных китайских символов с традиционными китайскими символами. Этот флаг и LCMAP_SIMPLIFIED_CHINESE являются взаимоисключающими.
LCMAP_UPPERCASE	Для языковых стандартов и скриптов, способных обрабатывать прописные и строчные регистры, сопоставьте все символы с верхним регистром.

Следующие флаги можно использовать отдельно, друг с другом или с флагами LCMAP_SORTKEY и (или) LCMAP_BYTEREV. Однако их нельзя сочетать с другими флагами, перечисленными выше.

Flag	Значение
NORM_IGNORENONSPACE	Пропускать символы, не относящиеся к разделу. Для многих сценариев (в частности, латинских) NORM_IGNORENONSPACE совпадает с LINGUISTIC_IGNOREDIACRITIC. Примечание NORM_IGNORENONSPACE игнорирует любые вторичные различия, будь то диакритические или нет. В письмах для корейского, японского, китайского и индического языков, среди прочего, это различие используется для целей, отличных от диакритических. LINGUISTIC_IGNOREDIACRITIC приводит к тому, что функция игнорирует только фактические диакритические значения вместо игнорирования второго веса сортировки.
NORM_IGNORESYMBOLS	Игнорируйте символы и знаки препинания.

Flag

Значение

NORM_IGNORENONSPACE

Пропускать символы, не относящиеся к разделу. Для многих сценариев (в частности, латинских) NORM_IGNORENONSPACE совпадает с LINGUISTIC_IGNOREDIACRITIC.

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

NORM_IGNORESYMBOLS

Игнорируйте символы и знаки препинания.

Перечисленные ниже флаги используются только с флагом LCMAP_SORTKEY.

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

[in] lpSrcStr

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

[in] cchSrc

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

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

Приложение не может задать для этого параметра значение 0.

[out, optional] lpDestStr

Указатель на буфер, в котором эта функция извлекает сопоставленную строку или ключ сортировки.

Если приложение использует функцию для создания ключа сортировки (LCMAP_SORTKEY):

Ключ сортировки хранится в буфере и обрабатывается как непрозрачный массив байтов. Хранимые значения могут включать внедренные 0 байт в любой позиции.
Целевая строка может содержать нечетное число байтов. Флаг LCMAP_BYTEREV отменяет только четное число байтов. Последний байт (с нечетным положением) в ключе сортировки не отменяется.

Если вызывающий объект явно запрашивает подмножество строки, конечная строка не включает завершающий символ NULL, если вызывающий объект не указал его в cchDest.

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

Примечание

При задании LCMAP_UPPERCASE или LCMAP_LOWERCASE конечная строка может использовать тот же буфер, что и исходная строка. Однако это настоятельно не рекомендуется, так как некоторые условия могут привести к тому, что возвращаемая строка с регистром будет иметь другую длину.

[in] cchDest

Размер целевой строки в символах, указанной lpDestStr. Если приложение использует функцию для сопоставления строк, оно предоставляет число символов для этого параметра. Если пробел для завершающего символа NULL включен в cchSrc, cchDest также должен содержать пробел для завершающего символа NULL.

Если приложение использует функцию для создания ключа сортировки, оно предоставляет количество байтов для размера. Это число байтов должно включать пробел для ключа сортировки 0x00 признака конца.

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

[in, optional] lpVersionInformation

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

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

[in, optional] lpReserved

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

[in, optional] sortHandle

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

Примечание

CompareStringEx и LCMapStringEx могут указывать дескриптор сортировки (если языковой стандарт имеет значение NULL). Для большинства приложений такое использование не рекомендуется.

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

Если функция выполняется успешно при использовании для сопоставления строк, она возвращает количество символов в переведенной строке (дополнительные сведения см. в разделах cchSrc и cchDest ).

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

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

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

Приложение может использовать LCMapString или LCMapStringEx для создания ключа сортировки. Для этого приложение указывает LCMAP_SORTKEY для параметра dwMapFlags . Дополнительные сведения см. в разделе Обработка сортировки в приложениях.

Примечание

Ключи сортировки — это непрозрачные потоки байтов. Вызывающие элементы должны рассматривать их как массив байтов длины, возвращаемой API, и не полагаться на какую-либо внутреннюю структуру, которая может показаться присутствующей. Ноль, один или несколько байтов в возвращенном ключе сортировки могут иметь значение 0. Отсутствие или наличие нулевого байта не следует ожидать.

Другим способом использования LCMapString или LCMapStringEx приложением является сопоставление строк. В этом случае приложение не указывает LCMAP_SORTKEY для параметра dwMapFlags , но предоставляет другое сочетание флагов. Дополнительные сведения см. в разделе Обработка сортировки в приложениях.

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

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

Требования

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