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

Статья
08/26/2023

Сопоставляет одну строку Юникода с другой, выполняя указанное преобразование. Общие сведения об использовании строковых функций см. в разделе Строки.

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

Синтаксис

int FoldStringW(
  [in]            DWORD                         dwMapFlags,
  [in]            _In_NLS_string_(cchSrc)LPCWCH lpSrcStr,
  [in]            int                           cchSrc,
  [out, optional] LPWSTR                        lpDestStr,
  [in]            int                           cchDest
);

Параметры

[in] dwMapFlags

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

Flag	Значение
MAP_COMPOSITE	Сопоставьте символы с диапозитивами, то есть символами, в которых базовый символ и один или несколько символов без знака имеют отдельные значения кодовых точек. Например, Ä представлена A + ированием: ЛАТИНСКАЯ ПРОПИСНАЯ БУКВа A (U+0041) + COMBINING DIAERESIS (U+0308). Этот флаг эквивалентен нормализации формы D в Windows Vista. Обратите внимание, что этот флаг нельзя использовать с MB_PRECOMPOSED.
MAP_EXPAND_LIGATURES	Разверните все символы лигатуры, чтобы они были представлены их эквивалентом из двух символов. Например, лигатура "æ" (U+00e6) расширяется до двух символов "a" (U+0061) + "e" (U+0065). Это значение нельзя объединить с MAP_PRECOMPOSED или MAP_COMPOSITE.
MAP_FOLDCZONE	Сложите символы зоны совместимости в стандартные эквиваленты Юникода. Этот флаг эквивалентен форме нормализации KD в Windows Vista, если также установлен флаг MAP_COMPOSITE. Если составной флаг не задан (по умолчанию), этот флаг эквивалентен нормализации формы KC в Windows Vista.
MAP_FOLDDIGITS	Сопоставьте все цифры с символами Юникода от 0 до 9.
MAP_PRECOMPOSED	Сопоставьте символы с акцентами с предварительно скомпилированные символы, в которых акцент и базовый символы объединяются в одно значение символа. Этот флаг эквивалентен нормализации формы C в Windows Vista. Это значение не может быть объединено с MAP_COMPOSITE.

[in] lpSrcStr

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

[in] cchSrc

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

[out, optional] lpDestStr

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

[in] cchDest

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

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

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

Возвращает количество символов в переведенной строке, включая завершающий пустой символ, если это будет выполнено успешно. Если функция выполняется успешно, а значение cchDest равно 0, возвращаемое значение — это размер буфера, необходимый для хранения переведенной строки, включая завершающий символ NULL.

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

ERROR_INSUFFICIENT_BUFFER. Указанный размер буфера был недостаточно велик или для него неправильно задано значение NULL.
ERROR_INVALID_DATA. Недопустимые данные.
ERROR_INVALID_FLAGS. Значения, указанные для флагов, были недопустимыми.
ERROR_INVALID_PARAMETER. Любое из значений параметров было недопустимым.
ERROR_MOD_NOT_FOUND. Модуль не найден.
ERROR_OUTOFMEMORY. Недостаточно места для выполнения этой операции.
ERROR_PROC_NOT_FOUND. Требуемая процедура не найдена.

Зона совместимости в Юникоде состоит из символов в диапазоне 0xF900 по 0xFFEF, которые назначены символам из других стандартов кодирования для символов, но на самом деле являются вариантами символов, уже существующих в Юникоде. Зона совместимости используется для поддержки сопоставления кругового пути с этими стандартами. Приложения могут использовать флаг MAP_FOLDCZONE, чтобы избежать дублирования символов в зоне совместимости.

Начиная с Windows Vista: Эта функция поддерживает нормализацию Юникода. Сопоставляются все символы совместимости Юникода.

Начиная с Windows Vista: Преобразования, указанные флагами MAP_FOLDCZONE, MAP_PRECOMPOSED и MAP_COMPOSITE, используют формы нормализации Юникода KC, C и D (с помощью функции NormalizeString ) для выполнения сопоставлений.

Начиная с 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