wcsrtombs, wcsrtombs_s

 

C

編譯器支援

語言

標頭檔案

型別支援

程式工具

變參函式支援

錯誤處理

動態記憶體管理

字串庫

演算法

數值

日期和時間工具

輸入/輸出支援

本地化支援

併發支援 (C11)

技術規範

符號索引

 

字串庫

空終止位元組字串

空終止多位元組字串

空終止寬字串

 

空終止多位元組字串

函式
寬字元/多位元組轉換
mbsinit (C95)
mbstowcsmbstowcs_s (C11) btowc (C95) mbrtowc (C95) mbsrtowcsmbsrtowcs_s (C95)(C11)   mbrtoc8 (C23) c8rtomb (C23) mbrtoc16 (C11) c16rtomb (C11) c32rtomb (C11) mbrtoc32 (C11)	mblen mbtowc wctombwctomb_s (C11) wcstombswcstombs_s (C11) wctob (C95) wcrtombwcrtomb_s (C95)(C11) wcsrtombswcsrtombs_s (C95)(C11) mbrlen (C95)
型別
mbstate_t (C95) char8_t (C23)	char16_t (C11) char32_t (C11)
宏
MB_LEN_MAX	MB_CUR_MAX

 

在標頭檔案 <wchar.h> 中定義
	(1)
size_t wcsrtombs( char *dst, const wchar_t **src, size_t len, mbstate_t* ps );			(自 C95 起) (直到 C99)
size_t wcsrtombs( char *restrict dst, const wchar_t **restrict src, size_t len,                   mbstate_t *restrict ps );			(C99 起)
errno_t wcsrtombs_s( size_t *restrict retval, char *restrict dst, rsize_t dstsz,                      const wchar_t **restrict src, rsize_t len,                      mbstate_t *restrict ps );		(2)	(C11 起)

1) 將寬字元序列從其第一個元素由 *src 指向的陣列轉換為其窄多位元組表示，該表示以 *ps 描述的轉換狀態開始。如果 dst 不為 null，則轉換後的字元儲存在 dst 指向的 char 陣列的連續元素中。寫入目標陣列的位元組數不超過 len。每個字元都像透過呼叫 wcrtomb 轉換一樣。轉換停止，如果

• 空字元 L'\0' 已轉換並存儲。在這種情況下儲存的位元組是解除移位序列（如果需要）後跟 '\0'，*src 設定為 null 指標值，*ps 表示初始移位狀態。
• 發現 wchar_t 不對應於當前 C 語言環境中的有效字元。*src 設定為指向第一個未轉換的寬字元。
• 下一個要儲存的多位元組字元將超過 len。*src 設定為指向第一個未轉換的寬字元。如果 dst 是空指標，則不檢查此條件。

2) 與(1)相同，但：

• 函式將其結果作為輸出引數 retval 返回。
• 如果轉換停止而未寫入空字元，函式將在 dst 中的下一個位元組（可能是 dst[len] 或 dst[dstsz]，以先到達者為準，這意味著最多可寫入 len+1/dstsz+1 總位元組）中儲存 '\0'。在這種情況下，在終止空字元之前可能沒有寫入解除移位序列。
• 函式從終止空字元開始，直到 dstsz 為止，覆蓋目標陣列。
• 如果 src 和 dst 重疊，則行為未指定。
• 執行時檢測到以下錯誤並呼叫當前安裝的約束處理程式函式

• retval、ps、src 或 *src 為空指標。
• dstsz 或 len 大於 RSIZE_MAX（除非 dst 為空）
• dstsz不為零（除非dst為空）
• len 大於 dstsz，並且在到達 dstsz 時，轉換在 src 陣列中沒有遇到空字元或編碼錯誤（除非 dst 為空）。

與所有邊界檢查函式一樣，只有當實現定義了 __STDC_LIB_EXT1__ 並且使用者在包含 <wchar.h> 之前將 __STDC_WANT_LIB_EXT1__ 定義為整型常量 1 時，才能保證 wcsrtombs_s 可用。

引數

dst	-	指向儲存多位元組字元的窄字元陣列的指標
src	-	指向空終止寬字串的第一個元素指標的指標
len	-	dst 指向的陣列中可用的位元組數
ps	-	指向轉換狀態物件的指標
dstsz	-	將寫入的最大位元組數（dst 陣列的大小）
retval	-	指向儲存結果的 size_t 物件的指標

返回值

1) 成功時，返回寫入字元陣列（其第一個元素由 dst 指向）的位元組數（包括任何移位序列，但不包括終止 '\0'）。如果 dst 是空指標，則返回本應寫入的位元組數。在轉換錯誤（如果遇到無效寬字元）時，返回 (size_t)-1，將 EILSEQ 儲存在 errno 中，並將 *ps 保持在未指定狀態。

2) 成功時返回零（在這種情況下，寫入或將寫入 dst 的位元組數（不包括終止零）儲存在 *retval 中），錯誤時返回非零。在執行時約束衝突的情況下，將 (size_t)-1 儲存在 *retval 中（除非 retval 為空），並將 dst[0] 設定為 '\0'（除非 dst 為空或 dstmax 為零或大於 RSIZE_MAX）。

示例

執行此程式碼

#include <stdio.h>
#include <locale.h>
#include <string.h>
#include <wchar.h>
 
void print_wide(const wchar_t* wstr)
{
    mbstate_t state;
    memset(&state, 0, sizeof state);
    size_t len = 1 + wcsrtombs(NULL, &wstr, 0, &state);
    char mbstr[len];
    wcsrtombs(mbstr, &wstr, len, &state);
    printf("Multibyte string: %s\n", mbstr);
    printf("Length, including '\\0': %zu\n", len);
}
 
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    print_wide(L"z\u00df\u6c34\U0001f34c"); // or L"zß水🍌"
}

輸出

Multibyte string: zß水🍌
Length, including '\0': 11

參考

• C17 標準 (ISO/IEC 9899:2018)

• 7.29.6.4.2 wcsrtombs 函式 (p: 324-325)

• K.3.9.3.2.2 wcsrtombs_s 函式 (p: 471-472)

• C11 標準 (ISO/IEC 9899:2011)

• 7.29.6.4.2 wcsrtombs 函式 (p: 446)

• K.3.9.3.2.2 wcsrtombs_s 函式 (p: 649-651)

• C99 標準 (ISO/IEC 9899:1999)

• 7.24.6.4.2 wcsrtombs 函式 (p: 392)

另請參閱

wcstombswcstombs_s (C11)	將寬字串轉換為窄多位元組字元字串 (function)
wcrtombwcrtomb_s (C95)(C11)	將寬字元轉換為其多位元組表示，給定狀態 (function)
mbsrtowcsmbsrtowcs_s (C95)(C11)	將窄多位元組字元字串轉換為寬字串，給定狀態 (function)
C++ 文件 for wcsrtombs