std::mbstowcs

 

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)

 

定義於標頭檔案 <cstdlib>
std::size_t mbstowcs( wchar_t* dst, const char* src, std::size_t len );

將指向 src 的多位元組字串陣列的第一個元素轉換為其寬字元表示形式。轉換後的字元儲存在指向 dst 的陣列的連續元素中。寫入目標陣列的寬字元數不超過 len 個。

每個字元的轉換都如同呼叫了 std::mbtowc，但 mbtowc 轉換狀態不受影響。當發生以下情況時，轉換停止：

• 多位元組空字元已被轉換並存儲。
• 遇到一個無效（在當前 C 語言環境中）的多位元組字元。
• 下一個要儲存的寬字元將超出 len。

注意

在大多數實現中，此函式在處理字串時會更新一個 std::mbstate_t 型別的全域性靜態物件，並且不能由兩個執行緒同時呼叫，在這種情況下應使用 std::mbsrtowcs。

POSIX 指定了一個常見擴充套件：如果 dst 是一個空指標，則此函式返回如果轉換，將寫入 dst 的寬字元數。類似的行為對於 std::mbsrtowcs 來說是標準的。

引數

dst	-	指向將儲存寬字串的寬字元陣列的指標
src	-	指向要轉換的以空字元結尾的多位元組字串的第一個元素的指標
len	-	dst指向的陣列中可用的寬字元數

返回值

成功時，返回寫入目標陣列的寬字元數，不包括終止的 L'\0'。

在轉換錯誤時（如果遇到無效的多位元組字元），返回 static_cast<std::size_t> (-1)。

示例

執行此程式碼

#include <clocale>
#include <cstdlib>
#include <iostream>
 
int main()
{
    std::setlocale(LC_ALL, "en_US.utf8");
    std::wcout.imbue(std::locale("en_US.utf8"));
    const char* mbstr = "z\u00df\u6c34\U0001f34c"; // or u8"zß水🍌"
                        // or "\x7a\xc3\x9f\xe6\xb0\xb4\xf0\x9f\x8d\x8c";
    wchar_t wstr[5];
    std::mbstowcs(wstr, mbstr, 5);
    std::wcout << "wide string: " << wstr << '\n';
}

輸出

wide string: zß水🍌

另請參閱

mbsrtowcs	將窄多位元組字元字串轉換為寬字串，給定狀態 (函式)
wcstombs	將寬字串轉換為窄多位元組字元字串 (函式)
do_in [虛擬]	將字串從 ExternT 轉換為 InternT，例如從檔案讀取時 (std::codecvt<InternT,ExternT,StateT> 的虛擬保護成員函式)
C 文件 關於 mbstowcs