mbsrtowcs, mbsrtowcs_s
來自 cppreference.com
| 在標頭檔案 <wchar.h> 中定義 |
||
| (1) | ||
| (自 C95 起) (直到 C99) |
||
| (C99 起) | ||
| (2) | (C11 起) | |
1) 將以
*ps 描述的轉換狀態開始的空終止多位元組字元序列從 *src 指向的陣列的第一個元素轉換為其寬字元表示。如果 dst 不為空，則轉換後的字元儲存在 dst 指向的 wchar_t 陣列的連續元素中。寫入目標陣列的寬字元不超過 len 個。每個多位元組字元都像透過呼叫 mbrtowc 進行轉換。轉換在以下情況下停止：- 多位元組空字元已轉換並存儲。*src 設定為空指標值，
*ps表示初始移位狀態。 - 遇到無效的多位元組字元（根據當前 C 區域設定）。*src 設定為指向第一個未轉換的多位元組字元的開頭。
- 下一個要儲存的寬字元將超過
len。*src 設定為指向第一個未轉換的多位元組字元的開頭。如果dst是空指標，則不檢查此條件。
2) 與(1)相同，但：
- 函式將其結果作為輸出引數
retval返回 - 如果在寫入
len個寬字元後，沒有空字元寫入dst，則將 L'\0' 儲存在dst[len]中，這意味著總共寫入len+1個寬字元 - 函式從終止空字元到
dstsz處覆蓋目標陣列 - 如果
src和dst重疊，則行為未指定。 - 在執行時檢測到以下錯誤並呼叫當前安裝的約束處理程式函式
-
retval、ps、src或 *src 為空指標 -
dstsz或len大於 RSIZE_MAX/sizeof(wchar_t)（除非dst為空） -
dstsz不為零（除非dst為空） - 在 *src 陣列的前
dstsz個多位元組字元中沒有空字元，並且len大於dstsz（除非dst為空）
-
- 與所有邊界檢查函式一樣，只有當實現定義了 __STDC_LIB_EXT1__ 且使用者在包含 <wchar.h> 之前將 __STDC_WANT_LIB_EXT1__ 定義為整數常量 1 時，才能保證
mbsrtowcs_s可用。
目錄 |
[編輯] 引數
| dst | - | 指向寬字元陣列的指標，結果將儲存在此處 |
| src | - | 指向空終止多位元組字串的第一個元素的指標的指標 |
| len | - | dst指向的陣列中可用的寬字元數 |
| ps | - | 指向轉換狀態物件的指標 |
| dstsz | - | 將寫入的最大寬字元數（dst 陣列的大小） |
| retval | - | 指向一個size_t物件的指標，結果將儲存在此處 |
[編輯] 返回值
1) 成功時，返回寫入字元陣列的寬字元數，不包括終止空字元 L'\0'。如果
dst 是空指標，則返回在無限長度下本應寫入的寬字元數。在轉換錯誤時（如果遇到無效的多位元組字元），返回 (size_t)-1，將 EILSEQ 儲存在 errno 中，並使 *ps 處於未指定狀態。2) 成功時返回零（在這種情況下，不包括終止零的寬字元數，已寫入或將寫入
dst，儲存在 *retval 中），錯誤時返回非零。在執行時約束衝突的情況下，將 (size_t)-1 儲存在 *retval 中（除非 retval 為空），並將 dst[0] 設定為 L'\0'（除非 dst 為空或 dstmax 為零或大於 RSIZE_MAX）[編輯] 示例
執行此程式碼
#include <stdio.h> #include <locale.h> #include <wchar.h> #include <string.h> void print_as_wide(const char* mbstr) { mbstate_t state; memset(&state, 0, sizeof state); size_t len = 1 + mbsrtowcs(NULL, &mbstr, 0, &state); wchar_t wstr[len]; mbsrtowcs(&wstr[0], &mbstr, len, &state); wprintf(L"Wide string: %ls \n", wstr); wprintf(L"The length, including L'\\0': %zu\n", len); } int main(void) { setlocale(LC_ALL, "en_US.utf8"); print_as_wide(u8"z\u00df\u6c34\U0001f34c"); // u8"zß水🍌" }
輸出
Wide string: zß水🍌 The length, including L'\0': 5
