NormalizeString 関数 (winnls.h)

Unicode 4.0 TR#15 に従ってテキスト文字列の文字を正規化します。 詳細については、「 Unicode 正規化を使用して文字列を表す」を参照してください。

構文

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

パラメーター

[in] NormForm

使用する正規化フォーム。 NORM_FORM では、標準の Unicode 正規化形式を指定します。

[in] lpSrcString

正規化されていないソース文字列へのポインター。

[in] cwSrcLength

ソース文字列を含むバッファーの長さ (文字数)。 このパラメーターは、関数が文字列が null で終わると想定し、長さを自動的に計算する必要がある場合に、このパラメーターを -1 に設定できます。

[out, optional] lpDstString

関数がコピー先の文字列を取得するバッファーへのポインター。 または、cwDstLength が 0 に設定されている場合、このパラメーターには NULL が含まれます。

[in] cwDstLength

コピー先の文字列を含むバッファーの長さ (文字数)。 または、アプリケーションでこのパラメーターを 0 に設定して、コピー先バッファーに必要なサイズを返すように関数に要求することもできます。

戻り値

コピー先バッファー内の正規化された文字列の長さを返します。 cwDstLength が 0 に設定されている場合、関数は実際の変換に必要な推定バッファー長を返します。

入力バッファー内の文字列が null で終わる場合、または cwSrcLength が -1 の場合、宛先バッファーに書き込まれる文字列は null で終了し、返される文字列の長さは終端の null 文字を含みます。

この関数は、成功しなかった場合に 0 以下の値を返します。 拡張エラー情報を取得するために、アプリケーションは GetLastError呼び出すことができます。これは、次のいずれかのエラー コードを返すことができます。

• ERROR_INSUFFICIENT_BUFFER。 指定されたバッファー サイズが十分な大きさではなかったか、NULL正しく設定されていません。
• ERROR_INVALID_PARAMETER。 パラメーター値のいずれかが無効でした。
• ERROR_NO_UNICODE_TRANSLATION。 文字列に無効な Unicode が見つかりました。 戻り値は、入力文字列内のエラーの位置のインデックスの負の値です。
• ERROR_SUCCESS。 アクションは正常に完了しましたが、結果は生成されません。

注釈

一部の Unicode 文字には、組み合わせや複合 Unicode 文字のセットで構成される複数の同等のバイナリ表現があります。 Unicode 標準では、文字の同等のバイナリ表現のいずれかが指定された場合に 1 つのバイナリ表現を返す正規化と呼ばれるプロセスを定義します。 正規化は、「 文字列を表す Unicode 正規化の使用」で説明されているように、さまざまなルールに従う正規化形式と呼ばれる複数のアルゴリズムを使用して実行できます。 現在、Win32 と .NET Framework では、 Unicode 標準付属書 #15: Unicode 正規化フォームで定義されている正規化フォーム C、D、KC、KD がサポートされています。 正規化された文字列は、通常、序数比較を使用して評価されます。

次のコードは、バッファー長の見積もりの使用を示しています。

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 は、Microsoft 国際化ドメイン名 (IDN) 軽減 API の一部であり、ダウンロードできなくなります。

例示

この関数の使用方法を示す例は、 NLS: Unicode 正規化サンプルにあります。

Requirements

こちらも参照ください

IsNormalizedString

NORM_FORM

各国語サポート

各国語サポート関数

Unicode 正規化を使用して文字列を表す