mbstowcs, mbstowcs_s
來自 cppreference.com
| 在標頭檔案 <stdlib.h> 中定義 |
||
| (1) | ||
| (直到 C99) | ||
| (C99 起) | ||
| errno_t mbstowcs_s(size_t *restrict retval, wchar_t *restrict dst, rsize_t dstsz, const char *restrict src, rsize_t len); |
(2) | (C11 起) |
1) 將多位元組字串從
src指向的陣列轉換為其寬字元表示。轉換後的字元儲存在dst指向的陣列的後續元素中。寫入目標陣列的寬字元數不超過len。 每個字元都如同透過呼叫mbtowc進行轉換，但mbtowc的轉換狀態不受影響。轉換在以下情況下停止：
* 多位元組空字元已轉換並存儲。
* 遇到了無效（在當前C語言環境中）的多位元組字元。
* 將要儲存的下一個寬字元將超過
len。 如果
src和dst重疊，則行為未定義。2) 與(1)相同，但：
* 函式將其結果作為輸出引數
retval返回 * 如果在寫入
len個寬字元後沒有空字元寫入dst，則將L'\0'儲存在dst[len]中，這意味著總共寫入了len+1個寬字元 * 如果
dst是空指標，則將生成多少寬字元儲存在*retval中 * 函式會從終止空字元到
dstsz之間覆蓋目標陣列 * 如果
src和dst重疊，則行為未指定。 * 以下錯誤在執行時檢測到並呼叫當前安裝的約束處理函式
-
retval或src為空指標 -
dstsz或len大於RSIZE_MAX/sizeof(wchar_t)（除非dst為空） -
dstsz不為零（除非dst為空） src陣列中的前dstsz個多位元組字元中沒有空字元，並且len大於dstsz（除非dst為空）
-
- 與所有邊界檢查函式一樣，只有在實現定義了__STDC_LIB_EXT1__且使用者在包含<stdlib.h>之前將__STDC_WANT_LIB_EXT1__定義為整數常量1時，才保證
mbstowcs_s可用。
目錄 |
[編輯] 注意
在大多數實現中，mbstowcs在處理字串時會更新型別為mbstate_t的全域性靜態物件，並且不能由兩個執行緒同時呼叫，在這種情況下應使用mbsrtowcs。
POSIX指定了一個常見擴充套件：如果dst為空指標，此函式將返回如果轉換將寫入dst的寬字元數。mbstowcs_s和mbsrtowcs也有類似的標準行為。
[編輯] 引數
| dst | - | 指向將儲存寬字串的寬字元陣列的指標 |
| src | - | 指向要轉換的空終止多位元組字串的第一個元素的指標 |
| len | - | dst指向的陣列中可用的寬字元數 |
| dstsz | - | 將寫入的最大寬字元數（dst陣列的大小） |
| retval | - | 指向一個size_t物件的指標，結果將儲存在此處 |
[編輯] 返回值
2) 成功時返回零（在這種情況下，寫入
dst的寬字元數，不包括終止零，將儲存在*retval中），錯誤時返回非零。如果發生執行時約束違例，則在*retval中儲存(size_t)-1（除非retval為空）並將dst[0]設定為L'\0'（除非dst為空或dstmax為零或大於RSIZE_MAX）[編輯] 示例
執行此程式碼
#include <stdio.h> #include <locale.h> #include <stdlib.h> #include <wchar.h> int main(void) { setlocale(LC_ALL, "en_US.utf8"); const char* mbstr = u8"z\u00df\u6c34\U0001F34C"; // or u8"zß水🍌" wchar_t wstr[5]; mbstowcs(wstr, mbstr, 5); wprintf(L"MB string: %s\n", mbstr); wprintf(L"Wide string: %ls\n", wstr); }
輸出
MB string: zß水🍌 Wide string: zß水🍌
