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

Нормализует символы текстовой строки в соответствии с Юникодом 4.0 TR#15. Дополнительные сведения см. в разделе "Использование нормализации Юникода для представления строк".

Синтаксис

int NormalizeString(
  [in]            NORM_FORM NormForm,
  [in]            LPCWSTR   lpSrcString,
  [in]            int       cwSrcLength,
  [out, optional] LPWSTR    lpDstString,
  [in]            int       cwDstLength
);

Параметры

[in] NormForm

Форма нормализации для использования. NORM_FORM задает стандартные формы нормализации Юникода.

[in] lpSrcString

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

[in] cwSrcLength

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

[out, optional] lpDstString

Указатель на буфер, в котором функция извлекает целевую строку. Кроме того, этот параметр содержит значение NULL , если для cwDstLength задано значение 0.

[in] cwDstLength

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

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

Возвращает длину нормализованной строки в целевом буфере. Если для cwDstLength задано значение 0, функция возвращает предполагаемую длину буфера, необходимую для фактического преобразования.

Если строка в входном буфере завершается null или если cwSrcLength равно -1, строка, записанная в целевой буфер, завершается null, а возвращаемая строка содержит завершающийся пустой символ.

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

• ERROR_INSUFFICIENT_BUFFER. Указанный размер буфера был недостаточно велик или неправильно задано значение NULL.
• ERROR_INVALID_PARAMETER. Любое из значений параметров было недопустимым.
• ERROR_NO_UNICODE_TRANSLATION. Недопустимый Юникод найден в строке. Возвращаемое значение является отрицательным индексом расположения ошибки во входной строке.
• ERROR_SUCCESS. Действие выполнено успешно, но не дало результатов.

Замечания

Некоторые символы Юникода имеют несколько эквивалентных двоичных представлений, состоящих из наборов объединения и /или составных символов Юникода. Стандарт Юникода определяет процесс, называемый нормализацией, который возвращает одно двоичное представление при указании любого из эквивалентных двоичных представлений символа. Нормализация может выполняться с несколькими алгоритмами, называемыми формами нормализации, которые соответствуют различным правилам, как описано в разделе "Использование нормализации Юникода для представления строк". Win32 и .NET Framework в настоящее время поддерживают формы нормализации C, D, KC и KD, как определено в стандартном приложении Юникода #15: Формы нормализации Юникода. Нормализованные строки обычно оцениваются с порядковым сравнением.

Следующий код демонстрирует использование оценки длины буфера:

const int maxIterations = 10;
LPWSTR strResult = NULL;
HANDLE hHeap = GetProcessHeap();

int iSizeEstimated = NormalizeString(form, strInput, -1, NULL, 0);
for (int i = 0; i < maxIterations; i++)
{
    if (strResult)
        HeapFree(hHeap, 0, strResult);
    strResult = (LPWSTR)HeapAlloc(hHeap, 0, iSizeEstimated * sizeof (WCHAR));
    iSizeEstimated = NormalizeString(form, strInput, -1, strResult, iSizeEstimated);
 
    if (iSizeEstimated > 0)
        break; // success 
 
    if (iSizeEstimated <= 0)
    {
        DWORD dwError = GetLastError();
        if (dwError != ERROR_INSUFFICIENT_BUFFER) break; // Real error, not buffer error 
 
        // New guess is negative of the return value. 
        iSizeEstimated = -iSizeEstimated;
    }
}

Windows XP, Windows Server 2003:

Больше не поддерживается.

Необходимый файл заголовка и DLL являются частью API устранения рисков с использованием международного доменного имени (IDN) Майкрософт, которые больше не доступны для скачивания.

Примеры

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

Требования

См. также

IsNormalizedString

NORM_FORM

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

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

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