共用方式為


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 的值,如果該值不成功則為 0。 若要取得延伸的錯誤資訊,應用程式可以呼叫 GetLastError,這可以傳回下列其中一個錯誤碼:

  • ERROR_INSUFFICIENT_BUFFER。 提供的緩衝區大小不夠大,或設定為 Null不正確。
  • ERROR_INVALID_PARAMETER。 任何參數值都無效。
  • ERROR_NO_UNICODE_TRANSLATION。 在字串中找到不正確 Unicode。 傳回值是輸入字串中錯誤位置之索引的負數。
  • ERROR_SUCCESS。 動作已順利完成,但不會產生任何結果。

備註

某些 Unicode 字元有多個相等的二進位標記法,由組合和/或複合 Unicode 字元集合所組成。 Unicode 標準會定義稱為正規化的程式,當指定字元的任何對等二進位標記法時,會傳回一個二進位標記法。 正規化可以使用數種演算法來執行,稱為正規化形式,遵守不同的規則,如 使用 Unicode 正規化表示字串中所述。 Win32 和.NET Framework目前支援正規化表單 C、D、KC 和 KD,如Unicode 標準附錄 #15:Unicode 正規化表單所定義。 正規化字串通常會以序數比較來評估。

下列程式碼示範如何使用緩衝區長度估計值:

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 國際化功能變數名稱 (IDN) SP2 和更新版本之 Windows XP 上的風險降低 API,或使用 SP1 的Windows Server 2003

另請參閱

IsNormalizedString

NORM_FORM

國家語言支援

國家語言支援函式

使用 Unicode 正規化來表示字串