Namespaces
Variants

wcstombs, wcstombs_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
定义于头文件 <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 的char数组的连续元素中。目标数组最多写入 len 个字节。
每个字符的转换方式如同调用 wctomb 函数，但 wctomb 的转换状态不受影响。遇到以下情况时转换将停止：
* 空字符 L ' \0 ' 被转换并存储。这种情况下存储的字节是未移位序列（如有必要）后跟 ' \0 ' ,
* 发现一个 wchar_t 无法对应当前 C 语言区域设置中的有效字符。
* 下一个要存储的多字节字符将超过 len 。
如果 src 和 dst 存在重叠，则行为是未定义的。
2) 与 (1) 相同，不同之处在于
* 转换过程如同通过 wcrtomb 进行，而非 wctomb
* 该函数通过输出参数 retval 返回其结果
* 若转换停止时未写入空字符，函数将在 dst 的下一个字节（可能是 dst[len] 或 dst[dstsz] 中先到达者）存入 ' \0 ' （这意味着最多可能写入 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 可用。

目录

注释

在大多数实现中， 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 ），错误时返回非零值。若发生运行时约束违规，则向 * retval 存入 ( size_t ) - 1 （除非 retval 为空指针），同时设置 dst [ 0 ] 为 ' \0 ' （除非 dst 为空指针，或 dstmax 为零或大于 RSIZE_MAX ）

示例

运行此代码 
#include <stdio.h>
#include <stdlib.h>
#include <locale.h>
int main(void)
{
    // 4个宽字符
    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 标准 (ISO/IEC 9899:2011):
  • 7.22.8.2 wcstombs 函数 (第360页)
  • K.3.6.5.2 wcstombs_s 函数 (第612-614页)
  • C99 标准 (ISO/IEC 9899:1999):
  • 7.20.8.2 wcstombs 函数 (第324页)
  • C89/C90 标准 (ISO/IEC 9899:1990):
  • 4.10.8.2 wcstombs 函数

参见

(C95) (C11)
转换宽字符串为窄多字节字符串（给定状态）
(函数)
(C11)
转换窄多字节字符串为宽字符串
(函数)
C++ 文档 关于 wcstombs