C 参考手册

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

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 。
若 src 与 dst 重叠，则行为未指定。
2) 同 (1) ，除了
* 转换如同以 wcrtomb ，而非 wctomb
* 函数将其结果作为输出参数 retval 返回
* 若转换停止而不写入控制符，则函数将在 dst 中的下个字符，可以是 dst[len] 或 dst[dstsz] 的先到来者，存储 '\0' （表示可能写入总计至多 len+1/dsz+1 个字符）。该情况下，空终止前不写入无迁移序列。
* 若 dst 是空指针，则将本会产生的字节数存储于 *retval
* 函数从空终止起到 dstsz 前为止破坏目标数组
* 若 src 与 dst 重叠，则行为未指定。
* 在运行时检测下列错误，并调用当前安装的制约处理函数：
  • retval 或 src 是空指针
  • dstsz 或 len 大于 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 类型的全局静态对象，而且不能为二个线程同时调用，这种情况下应使用 wcsrtombs 或 wcstombs_s 。

POSIX 指定一个常见扩展：若 dst 是空指针，则此函数返回假设转换则会写入 dst 的字节数。类似行为对于 wcsrtombs 和 wcstombs_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

参阅

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