C 参考手册

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

定义于头文件 <wchar.h>
(1)
size_t wcsrtombs( char *dst, const wchar_t **src, size_t len, mbstate_t* ps );
(C95 起)
size_t wcsrtombs( char *restrict dst, const wchar_t **restrict src, size_t len,
                  mbstate_t *restrict ps);
(C99 起)
errno_t wcsrtombs_s( size_t *restrict retval, char *restrict dst, rsize_t dstsz,

                     const wchar_t **restrict src, rsize_t len,

                     mbstate_t *restrict ps);
(2) (C11 起)
1) 转换来自元素为 *src 所指向的宽字符序列为其窄多字节表示,始于 *ps 所描述的转换状态。若 dst 非空,则存储转换后的字符于 dst 所指向的字符数组的相接元素。不写入多于 len 个字节到目标数组。
如同以调用 wcrtomb 转换每个字符。若遇到下列条件则停止转换:
* 转换并存储了空字符 L'\0' 。此情况下存储的字节是反迁移序列(若需要)后随 '\0' ,设置 *srcNULL 并令 *ps 表示初始迁移状态。
* 找到当前 C 本地环境中不对应合法字符的 wchar_t 。设置 *src 指向首个未转换的宽字符。
* 下个多字节字符将超出 len 。设置 *src 指向首个未转换的宽字符。若 dst==NULL 则不检查此条件。
2)(1) ,除了
* 函数返回其结果为输出参数 retval
* 若转换停止而不写入空字符,则函数将存储 '\0'dst 的下个字节,它可以是 dst[len]dst[dstsz] ,两者的先到来者(表示总共可能写入 len+1/dstsz+1 字节)。此情况下,在终止空字符前可以无反迁移序列。
* 函数从终止空字符 dstsz 到位置破坏数组
* 若 srcdst 重叠,则行为未指定。
* 在运行时检测下列错误,并调用当前安装的制约处理函数:
  • retvalpssrc*src 为空指针
  • dstszlen 大于 RSIZE_MAX (除非 dst 为空)
  • dstsz 非零(除非 dst 为空)
  • len 大于 dstsz 且转换在抵达 dstsz 时于 src 数组中未遇到空字符或编码错误(除非 dst 为空)
同所有边界检查函数, wcsrtombs_s 仅若实现定义了 __STDC_LIB_EXT1__ ,且用户在包含 wchar.h 前定义 __STDC_WANT_LIB_EXT1__ 为整数常量 1 才保证可用。

参数

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

返回值

1) 成功时,返回写入首元素为 dst 所指向的字符数组的字节数(包含任何迁移序列,但不包含终止 '\0' )。若 dst==NULL ,则返回本会写入的字节数。错误时(若遇到非法宽字符),返回 (size_t)-1 ,存储 EILSEQerrno ,并令 *ps 留在未指定状态。
2) 成功时返回零(该情况下将不包含终止零写入或本会写入到 dst 的字符数存储于 *retval ),错误时返回非零。在运行时制约违规的情况下,存储 (size_t)-1*retval (除非 retval 为空)并设置 dst[0]'\0' (除非 dst 为空或 dstmax 为零或大于 RSIZE_MAX )。

示例

#include <stdio.h>
#include <locale.h>
#include <string.h>
#include <wchar.h>
 
void print_wide(const wchar_t* wstr)
{
    mbstate_t state;
    memset(&state, 0, sizeof state);
    size_t len = 1 + wcsrtombs(NULL, &wstr, 0, &state);
    char mbstr[len];
    wcsrtombs(mbstr, &wstr, len, &state);
    printf("Multibyte string: %s\n", mbstr);
    printf("Length, including '\\0': %d\n", len);
}
 
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    print_wide(L"z\u00df\u6c34\U0001f34c"); // 或 L"zß水????"
}

输出:

Multibyte string: zß水????
Length, including '\0': 11

引用

  • C11 standard (ISO/IEC 9899:2011):
  • 7.29.6.4.2 The wcsrtombs function (p: 446)
  • K.3.9.3.2.2 The wcsrtombs_s function (p: 649-651)
  • C99 standard (ISO/IEC 9899:1999):
  • 7.24.6.4.2 The wcsrtombs function (p: 392)

参阅

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