詳解mbstowcs函數

一、 mbstowcsz函數

mbstowcsz 函數在標準 C 中未定義，但在 Microsoft Windows 中，它被定義為從多位元組字符集 (MBCS) 轉換為寬字符集。

    int mbstowcsz(
        wchar_t *pwcs,
        const char *ptr,
        size_t size
    );

mbstowcsz函數將字元串的前 size 個字元從多位元組字符集編碼轉換成相應的寬字符集編碼，然後將結果存儲在 wide-character 字元數組 pwcs 中。

二、mbstowcs_s源碼

mbstowcs_s 是 mbstowcs 的安全版本，這意味著它對緩衝區的大小進行了檢查，因此不會發生緩衝區溢出。

    errno_t mbstowcs_s(
        size_t *pReturnValue,
        wchar_t *wcstr,
        size_t sizeInWords,
        const char *mbstr,
        size_t count
    );

如果 mbstr 包含了一個由 sizeInWords 指定的字元數的字元串，那麼 mbstowcs_s 將該字元串轉換為 wcstr 所指定的擁有相同字元數的寬字符集字元串。

同時，還要注意 count 的值，如果小於 strlen(mbstr)+1，則 mbstowcs_s 會返回 ERANGE 錯誤。

三、mbstowcs_s函數

以下是mbstowcs_s的函數原型:

    errno_t mbstowcs_s(
        size_t *pReturnValue,
        wchar_t *wcstr,
        size_t sizeInWords,
        const char *mbstr,
        size_t count
    );

mbstowcs_s() 函數將 mbstr 所指定的多位元組字元串（MBCS）轉換成相應的寬字元字元串（WCS），並將結果放入由 wcstr 指示的字元數組中。轉換的過程遵循制定的代碼頁和本地環境，不使用其他系統區域性信息。轉換的字元串中不包括截止標誌。如果 mbstr 不是合法的多位元組字元字元串，則 mbstowcs_s() 返回 EINVAL 錯誤代碼。

長度限制與大小相同，轉換的字元數也不能超過 sizeInWords 所指定的大小。如果目標不能包含完整的字元串，函數將把轉換後的部分存儲到目標緩衝區中並將指向目標緩衝區的指針偏移寫入 wcstargv （如果不為 NULL）。

四、mbstowcs_r函數

下面的示例代碼將多位元組字元串 mymbstr 轉換為寬字元緩衝區 mywcstr。輸出指針指向轉換數據字元串的末尾：

    int mbstowcs_r(
        wchar_t *pwcs,
        const char *s,
        size_t n,
        size_t *nresult,
        mbstate_t *ps
    );

此函數在每個元素中對輸出緩存限制為 n – 1 個寬字元，以便在緩存中放置兩個終止符的寬字元。如果 n 不是足夠大的輸出緩存，則 mbstowcs_r 函數將返回緩存的不完整轉換。執行後，返回值是已轉換字元的數量。

五、mbstowcs函數

mbstowcs 函數將字元串從多位元組字符集編碼轉換為寬字符集編碼。

    size_t mbstowcs(
        wchar_t *pwcs,
        const char *ptr,
        size_t max
    );

該函數把字元串 ptr 中的前 max 個字元從多位元組字符集編碼轉換成相應的寬字符集編碼，然後把結果存儲在 wide-character 字元數組 pwcs 中。轉換的字元串不包括終止符。如果 pwcs 是 NULL，則不記錄轉換結果，只返回目標數組中需要的長度。

六、mbstowcs_s函數

    errno_t mbstowcs_s(
        size_t *pReturnValue,
        wchar_t *wcstr,
        size_t sizeInWords,
        const char *mbstr,
        size_t count
    );

此函數會在掃描輸入字元串時，將計數器 count 的值按其字元數遞減。如果輸入字元串中字元的數量超過 count ，則無法將 null 結束的字元串 mbstr 轉換為 null 結束的字元串 wcstr。因此， mbstowcs_s 函數確保不會把多於 count 字元的內容寫到目標緩衝區中，並在這種情況下返回實際轉換的字元數和 ERANGE 錯誤代碼。

如果目標不能包含完整的字元串，函數將把轉換後的部分存儲到目標緩衝區中並將指向目標緩衝區的指針偏移寫入 wcstargv （如果不為 NULL）。

七、mbstowcs utf8

mbstowcs utf8 將以 UTF-8 格式編碼的字元串轉換為寬字元字元串。

    size_t mbstowcs(
        wchar_t *pwcs,
        const char *ptr,
        size_t max
    );

在多位元組字符集編碼中，UTF-8 使用一至四個子節標識字元。在轉換期間，以下字元使用一個寬字元表示：

使用一個子節（0x0001 到 0x007F）的字元轉換為相應的寬字元。
使用兩個位元組（0x0080 到 0x07FF）中的字元轉換為相應的兩個寬字元（其中高位字元是由 0xD800 到 0xDBFF 動態分配的一個代碼單元）。
使用三個位元組（0x0800 到 0xFFFF）中的字元轉換為相應的三個寬字元。
使用四個位元組（0x10000 到 0x1FFFFF）中的字元轉換為相應的四個寬字元。

八、mbstowcs 返回-1

如果輸入字元串為 null，則 mbstowcs() 函數將返回 -1。否則，返回輸出緩衝區中寫入的 wide-character 數量。

九、mbstowcs 中文字元返回-1

如果輸入字元串包含無法在當前本地環境中轉換為寬字符集的字元或位元組，則 mbstowcs() 函數將返回 -1 並設置 errno 為靜態數據中的 EILSEQ。

總結

本文通過對 mbstowcs 函數的多個相關函數進行詳細闡述，包括 mbstowcsz,mbstowcs_s源碼,mbstowcs_s,mbstowcs_r,mbstowcs函數,mbstowcs_s函數,mbstowcs utf8,mbstowcs 返回-1,mbstowcs 中文字元返回-1等，讓讀者了解這些函數的用途，以及調用時需要注意的地方。

原創文章，作者：小藍，如若轉載，請註明出處：https://www.506064.com/zh-tw/n/206867.html