詳解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-hk/n/206867.html