Функция 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, а возвращаемая длина строки содержит завершающий символ NULL.
Функция возвращает значение, которое меньше или равно 0, если она не выполняется успешно. Чтобы получить расширенные сведения об ошибке, приложение может вызвать Метод GetLastError, который может возвращать один из следующих кодов ошибок:
- ERROR_INSUFFICIENT_BUFFER. Указанный размер буфера был недостаточно велик или для него неправильно задано значение NULL.
- ERROR_INVALID_PARAMETER. Любое из значений параметров было недопустимым.
- ERROR_NO_UNICODE_TRANSLATION. В строке обнаружен недопустимый Юникод. Возвращаемое значение является отрицательным значением индекса расположения ошибки во входной строке.
- ERROR_SUCCESS. Действие успешно завершено, но не дало результатов.
Комментарии
Некоторые символы Юникода имеют несколько эквивалентных двоичных представлений, состоящих из наборов комбинирующих и (или) составных символов Юникода. Стандарт Юникода определяет процесс, называемый нормализацией, который возвращает одно двоичное представление при наличии любого из эквивалентных двоичных представлений символа. Нормализация может выполняться с помощью нескольких алгоритмов, называемых формами нормализации, которые подчиняются разным правилам, как описано в разделе Использование нормализации Юникода для представления строк. Win32 и платформа .NET Framework в настоящее время поддерживают формы нормализации C, D, KC и KD, как определено в стандартном приложении Юникода No 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: пример нормализации Юникода.
Требования
Минимальная версия клиента | Windows Vista [классические приложения | Приложения UWP] |
Минимальная версия сервера | Windows Server 2008 [классические приложения | Приложения UWP] |
Целевая платформа | Windows |
Header | winnls.h (включая Windows.h) |
DLL | Normaliz.dll |
Распространяемые компоненты | API-интерфейсы устранения международных доменных имен (IDN) Майкрософт в Windows XP с пакетом обновления 2 (SP2) или Windows Server 2003 с пакетом обновления 1 (SP1) |