wcstombs
wcstombs, wcstombs_s
| 在头文件 | | |
|---|---|---|
| | (1) | |
| size_t wcstombs（char * dst，const wchar_t * src，size_t len）; | （直到C99） | |
| size_t wcstombs（char * restrict dst，const wchar_t * restrict src，size_t len）; | （自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以初始移位状态开始的窄多字节表示形式。转换后的字符存储在指向的char数组的后续元素中dst。不超过len字节被写入目标数组。
wctomb除了wctomb的转换状态不受影响之外， 每个字符都通过调用转换。在下列情况下停止转换：
*空字符L'\0'被转换并存储。存储在这种情况下，字节是不印字序列（必要时），接着'\0'，
* wchar_t发现A 不对应于当前C语言环境中的有效字符。
*要存储的下一个多字节字符将超过len。
如果src和dst重叠，行为是未指定的。
2）与（1）相同，除此之外
*转换为 - 如果wcrtomb不是wctomb
*该函数将其结果作为out参数返回 retval
*如果转换在不写入空字符的情况下停止，函数将存储'\0'在下一个字节中dst，该字节可以是dst[len]或者dst[dstsz]]先到达的任意一个（意味着最多可以写入len+1/dstsz + 1总字节）。在这种情况下，在终止空值之前可能没有写入不偏移的序列。
*如果dst是空指针，则将生成的宽字符数存储在中*retval
*该函数从终止null和直到clobbers目的地数组 dstsz
*如果src和dst重叠，行为是未指定的。
*在运行时检测到以下错误并调用当前安装的约束处理函数：
retval或者src是空指针
作为所有边界检查函数，wcstombs_s只有在被__STDC_LIB_EXT1__实现定义__STDC_WANT_LIB_EXT1__并且1在包含之前用户定义为整数常量时才能保证可用stdlib.h。
注意
在大多数实现中，当它在字符串中处理时wcstombs更新一个全局静态对象mbstate_t，并且不能由两个线程同时调用，wcsrtombs或者wcstombs_s应该在这种情况下使用。
POSIX指定了一个公共扩展：如果dst是空指针，则该函数返回将被写入的字节数（dst如果转换）。类似的行为标准wcsrtombs和wcstombs_s。
参数
| dst | - | 指向多字节字符将被存储在其中的窄字符数组的指针 |
|---|---|---|
| src | - | 指向要转换的空终止宽字符串的第一个元素的指针 |
| len | - | 由dst指向的数组中可用的字节数 |
| dstsz | - | 将被写入的最大字节数（dst数组的大小） |
| retval | - | 指向将存储结果的size_t对象的指针 |
返回值
1）成功时，返回'\0'写入第一个元素指向的字符数组的字节数（包括任何移位序列，但不包括终止）dst。出现转换错误（如果遇到无效的宽字符），返回(size_t)-1。
2）如果成功则返回零（在这种情况下不包括终止零那名，或将被写入到的字节数dst，被存储在*retval上的误差），非零。在运行时约束违反的情况下，存储(size_t)-1在*retval（除非retval为空），并设置dst[0]于'\0'（除非dst为空或dstmax为零或大于RSIZE_MAX）
示例
#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
参考
- C11标准（ISO/IEC 9899:2011）：
另请参阅
| wcsrtombswcsrtombs_s（C95）（C11） | 将宽字符串转换为窄多字节字符串，给定状态（函数） |
|---|---|
| mbstowcsmbstowcs_s（C11） | 将窄多字节字符串转换为宽字符串（函数） |
| 用于wcstombs |的C ++文档
