std::mbsrtowcs

 

C++

編譯器支援

自由（freestanding）與宿主（hosted）

語言

標準庫

標準庫標頭檔案

具名要求

特性測試宏 (C++20)

語言支援庫

概念庫 (C++20)

診斷庫

記憶體管理庫

超程式設計庫 (C++11)

通用工具庫

容器庫

迭代器庫

範圍庫 (C++20)

演算法庫

字串庫

文字處理庫

數值庫

日期和時間庫

輸入/輸出庫

檔案系統庫 (C++17)

併發支援庫 (C++11)

執行控制庫 (C++26)

技術規範

符號索引

外部庫

 

文字處理庫

本地化庫

正則表示式庫 (C++11)

格式化庫 (C++20)

空終止序列工具

位元組字串

多位元組字串

寬字串

原生數值轉換

to_chars (C++17) to_chars_result (C++17) from_chars (C++17) from_chars_result (C++17) chars_format (C++17)

文字編碼標識

text_encoding (C++26)

 

空終止多位元組字串

函式 寬/多位元組檢查 mblen mbrlen mbsinit 多位元組/寬字元轉換 mbtowc mbstowcs btowc mbrtowc mbsrtowcs    wctomb wcstombs wctob wcrtomb wcsrtombs mbrtoc8 (C++20) mbrtoc16 (C++11) mbrtoc32 (C++11) c8rtomb (C++20) c16rtomb (C++11) c32rtomb (C++11)

型別

mbstate_t

宏

MB_LEN_MAX MB_CUR_MAX __STDC_UTF_16__ __STDC_UTF_32__ (C++11)(C++11)

 

在標頭檔案 <cwchar> 中定義
std::size_t mbsrtowcs( wchar_t* dst,                        const char** src,                        std::size_t len,                        std::mbstate_t* ps );

將從 *src 指向的陣列首元素開始、以 *ps 描述的轉換狀態開始的多位元組字元空終止序列，轉換為寬字元表示。如果 dst 不為 null，則轉換後的字元儲存在 dst 指向的 wchar_t 陣列的連續元素中。寫入目標陣列的寬字元不超過 len 個。

每個多位元組字元都像透過呼叫 std::mbrtowc 轉換一樣。如果出現以下情況，轉換將停止：

• 多位元組空字元已轉換並存儲。src 被設定為空指標，而 *ps 表示初始移位狀態。
• 遇到無效的多位元組字元（根據當前 C 語言環境）。src 被設定為指向第一個未轉換多位元組字元的開頭。
• 要儲存的下一個寬字元將超過 len。src 被設定為指向第一個未轉換多位元組字元的開頭。如果 dst 為空指標，則不檢查此條件。

引數

dst	-	指向寬字元陣列的指標，結果將儲存在此處
src	-	指向空終止多位元組字串第一個元素的指標的指標
len	-	dst指向的陣列中可用的寬字元數
ps	-	指向轉換狀態物件的指標

返回值

成功時，返回寫入字元陣列的寬字元數，不包括終止符 L'\0'。如果 dst 是空指標，則返回在長度無限制的情況下會寫入的寬字元數。

在轉換錯誤（如果遇到無效多位元組字元）時，返回 static_cast<std::size_t>(-1)，將 EILSEQ 儲存在 errno 中，並使 *ps 處於未指定狀態。

注意

此函式將 src 指標移動到已轉換多位元組字串的末尾。如果 dst 為空指標，則不會發生這種情況。

示例

執行此程式碼

#include <clocale>
#include <cwchar>
#include <iostream>
#include <vector>
 
void print_as_wide(const char* mbstr)
{
    std::mbstate_t state = std::mbstate_t();
    std::size_t len = 1 + std::mbsrtowcs(nullptr, &mbstr, 0, &state);
    std::vector<wchar_t> wstr(len);
    std::mbsrtowcs(&wstr[0], &mbstr, wstr.size(), &state);
    std::wcout << "Wide string: " << &wstr[0] << '\n'
               << "The length, including '\\0': " << wstr.size() << '\n';
}
 
int main()
{
    std::setlocale(LC_ALL, "en_US.utf8");
    const char* mbstr = "z\u00df\u6c34\U0001f34c"; // or u8"zß水🍌"
    print_as_wide(mbstr);
}

輸出

Wide string: zß水🍌
The length, including '\0': 5

另請參閱

mbrtowc	將下一個多位元組字元轉換為寬字元，給定狀態 (函式)
wcsrtombs	將寬字串轉換為窄多位元組字元字串，給定狀態 (函式)
do_in [virtual]	將字串從 ExternT 轉換為 InternT，例如從檔案讀取時 (std::codecvt<InternT,ExternT,StateT> 的虛保護成員函式)
C 文件 針對 mbsrtowcs