C 参考手册

位置:首页 > C 参考手册 >字符串库 >空终止多字节字符串 > wcstombs, wcstombs_s

定义于头文件 <stdlib.h>
(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 所指向的数组到其始于初始迁移状态的多字节表示。转换出的字符被存储于 dst 所指向的数组的相继元素。写入目标数组的字节数不多于 len
如同以调用 wctomb 每个字符,除了 wctomb 的转换状态不受影响。若满足下列条件则转换停止:
* 转换并存储空字符 L'\0' 。此情况下存储的字节为无迁移序列(若需要)后随 '\0'
* 找到当前 C 本地环境中不对应合法字符的 wchar_t
* 下个要存储的多字节字符会超出 len
srcdst 重叠,则行为未指定。
2)(1) ,除了
* 转换如同以 wcrtomb ,而非 wctomb
* 函数将其结果作为输出参数 retval 返回
* 若转换停止而不写入控制符,则函数将在 dst 中的下个字符,可以是 dst[len]dst[dstsz] 的先到来者,存储 '\0' (表示可能写入总计至多 len+1/dsz+1 个字符)。该情况下,空终止前不写入无迁移序列。
* 若 dst 是空指针,则将本会产生的字节数存储于 *retval
* 函数从空终止起到 dstsz 前为止破坏目标数组
* 若 srcdst 重叠,则行为未指定。
* 在运行时检测下列错误,并调用当前安装的制约处理函数:
  • retvalsrc 是空指针
  • dstszlen 大于 RSIZE_MAX (除非 dst 为空)
  • dstsz 非零(除非 dst 为空)
  • len 大于 dstsz 且直到抵达 dstsz 时,转换未于 src 数组遇到空字符或编码错误(除非 dst 为空)
同所有边界检查函数, wcstombs_s 仅若实现定义了 __STDC_LIB_EXT1__ ,且用户在包含 stdlib.h 前定义 __STDC_WANT_LIB_EXT1__ 为整数常量 1 才保证可用。

注意

大多数实现中, wcstombs 在处理过字符串时更新 mbstate_t 类型的全局静态对象,而且不能为二个线程同时调用,这种情况下应使用 wcsrtombswcstombs_s

POSIX 指定一个常见扩展:若 dst 是空指针,则此函数返回假设转换则会写入 dst 的字节数。类似行为对于 wcsrtombswcstombs_s 是标准。

参数

dst - 指向窄字符数组的指针,其中将存储多字节字符
src - 指向要转换的空终止宽字符串首字符的指针
len - dst 所指向数组中的可用字节数
dstsz - 将写入的最大字节数( dst 数组的大小)
retval - 指向 size_t 对象的指针,其中将存储结果

返回值

1) 成功时,返回写入首元素为 dst 所指向的字符数组的字节数(包含任何迁移序列,但不含终止的 '\0' )。转换错误时(若遇到非法宽字符),返回 (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";
    // 它们于 UTF-8 占用 10 个字节
    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 standard (ISO/IEC 9899:2011):
  • 7.22.8.2 The wcstombs function (p: 360)
  • K.3.6.5.2 The wcstombs_s function (p: 612-614)
  • C99 standard (ISO/IEC 9899:1999):
  • 7.20.8.2 The wcstombs function (p: 324)
  • C89/C90 standard (ISO/IEC 9899:1990):
  • 4.10.8.2 The wcstombs function

参阅

给定状态,将宽字符串转换成窄多字节字符串
(函数)
将窄多字节字符串转换成宽字符串
(函数)