wcstombs, wcstombs_s
來自 cppreference.com
| 在標頭檔案 <stdlib.h> 中定義 |
||
| (1) | ||
| (直到 C99) | ||
| (C99 起) | ||
| errno_t wcstombs_s( size_t *restrict retval, char *restrict dst, rsize_t dstsz, const wchar_t *restrict src, rsize_t len ); |
(2) | (C11 起) |
1) 將寬字元序列（其第一個元素由
src 指向）轉換為其窄多位元組表示，該表示以初始移位狀態開始。轉換後的字元儲存在由 dst 指向的 char 陣列的後續元素中。寫入目標陣列的位元組數不超過 len。 每個字元都像透過呼叫 wctomb 一樣進行轉換，只是 wctomb 的轉換狀態不受影響。如果發生以下情況，轉換停止：
* 空字元 L'\0' 已轉換並存儲。在這種情況下儲存的位元組是解除移位序列（如果需要）後跟 '\0'，
* 找到的 wchar_t 不對應於當前 C 區域設定中的有效字元。
* 要儲存的下一個多位元組字元將超過
len。 如果
src 和 dst 重疊，則行為未指定。2) 與(1)相同，但：
* 函式透過輸出引數
retval 返回其結果 * 如果轉換在沒有寫入空字元的情況下停止，函式會將 '\0' 儲存在
dst 中的下一個位元組中，這可能是 dst[len] 或 dst[dstsz]，以先到者為準（這意味著最多可以寫入 len+1/dstsz+1 總位元組）。在這種情況下，在終止空字元之前可能沒有寫入解除移位序列。 * 如果
dst 是空指標，則產生的位元組數儲存在 *retval 中 * 函式會從終止空字元到
dstsz 破壞目標陣列 * 如果
src 和 dst 重疊，則行為未指定。 * 在執行時檢測到以下錯誤並呼叫當前安裝的 約束處理程式 函式
-
retval或src是空指標 -
dstsz或len大於 RSIZE_MAX（除非dst為空） -
dstsz不為零（除非dst為空） -
len大於dstsz並且在達到dstsz時，轉換在src陣列中沒有遇到空字元或編碼錯誤（除非dst為空）
-
- 與所有邊界檢查函式一樣，只有當實現定義了 __STDC_LIB_EXT1__ 並且使用者在包含 <stdlib.h> 之前將 __STDC_WANT_LIB_EXT1__ 定義為整數常量 1 時，才能保證
wcstombs_s可用。
目錄 |
[edit] 注意
在大多數實現中，wcstombs 在處理字串時更新型別為 mbstate_t 的全域性靜態物件，並且不能由兩個執行緒同時呼叫，在這種情況下應使用 wcsrtombs 或 wcstombs_s。
POSIX 指定了一個常見擴充套件：如果 dst 是空指標，此函式返回如果轉換，將寫入 dst 的位元組數。 wcsrtombs 和 wcstombs_s 的行為類似。
[edit] 引數
| dst | - | 指向窄字元陣列的指標，多位元組字元將儲存在此處 |
| src | - | 指向要轉換的空終止寬字串的第一個元素的指標 |
| len | - | dst 指向的陣列中可用的位元組數 |
| dstsz | - | 將寫入的最大位元組數（dst 陣列的大小） |
| retval | - | 指向一個size_t物件的指標，結果將儲存在此處 |
[edit] 返回值
2) 成功時返回零（在這種情況下，不包括終止零的位元組數，已寫入或將寫入
dst 的位元組數，儲存在 *retval 中），錯誤時返回非零。如果發生執行時約束違規，則將 (size_t)-1 儲存在 *retval 中（除非 retval 為空）並將 dst[0] 設定為 '\0' （除非 dst 為空或 dstmax 為零或大於 RSIZE_MAX）[edit] 示例
執行此程式碼
#include <stdio.h> #include <stdlib.h> #include <locale.h> int main(void) { // 4 wide characters const wchar_t src[] = L"z\u00df\u6c34\U0001f34c"; // they occupy 10 bytes in UTF-8 char dst[11]; setlocale(LC_ALL, "en_US.utf8"); printf("wide-character string: '%ls'\n",src); for (size_t ndx=0; ndx < sizeof src/sizeof src[0]; ++ndx) printf(" src[%2zu] = %#8x\n", ndx, src[ndx]); int rtn_val = wcstombs(dst, src, sizeof dst); printf("rtn_val = %d\n", rtn_val); if (rtn_val > 0) printf("multibyte string: '%s'\n",dst); for (size_t ndx=0; ndx<sizeof dst; ++ndx) printf(" dst[%2zu] = %#2x\n", ndx, (unsigned char)dst[ndx]); }
輸出
wide-character string: 'zß水🍌' src[ 0] = 0x7a src[ 1] = 0xdf src[ 2] = 0x6c34 src[ 3] = 0x1f34c src[ 4] = 0 rtn_val = 10 multibyte string: 'zß水🍌' dst[ 0] = 0x7a dst[ 1] = 0xc3 dst[ 2] = 0x9f dst[ 3] = 0xe6 dst[ 4] = 0xb0 dst[ 5] = 0xb4 dst[ 6] = 0xf0 dst[ 7] = 0x9f dst[ 8] = 0x8d dst[ 9] = 0x8c dst[10] = 0
[edit] 參考
- C11 標準 (ISO/IEC 9899:2011)
- 7.22.8.2 wcstombs 函式 (p: 360)
- K.3.6.5.2 wcstombs_s 函式 (p: 612-614)
