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 が含まれます。

メモ 入力文字列の長さが終端の null 文字なしで明示的に指定されている場合、関数は文字列を null で終了しません。 出力文字列を null で終了するには、アプリケーションで -1 を指定するか、入力文字列の終端の 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 正規化サンプル」で確認できます。

要件

   
サポートされている最小のクライアント Windows Vista [デスクトップ アプリのみ | UWP アプリ]
サポートされている最小のサーバー Windows Server 2008 [デスクトップ アプリ | UWP アプリ]
対象プラットフォーム Windows
ヘッダー winnls.h (Windows.h を含む)
[DLL] Normaliz.dll
再頒布可能パッケージ Microsoft Internationalized Domain Name (IDN) 軽減 API on Windows XP with SP2 以降、または Windows Server 2003 sp1

関連項目

IsNormalizedString

NORM_FORM

各国語サポート

各国語サポート関数

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