NormalizeString 関数 (winnls.h)

[アーティクル]
09/27/2022

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 onWindows XP with SP2 以降、または SP1 を使用した Windows Server 2003

こちらもご覧ください

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

NormalizeString 関数 (winnls.h)

構文

パラメーター

戻り値

注釈

例

要件

こちらもご覧ください

その他のリソース

その他のリソース