Namespaces
Variants

wcsrtombs, wcsrtombs_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
定义于头文件 <wchar.h>
(1)
size_t wcsrtombs ( char * dst, const wchar_t ** src, size_t len, mbstate_t * ps ) ;
(C95起)
(C99前)
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 ' ， * src 被设为空指针值，且 * ps 表示初始移位状态。
  • 遇到在当前C语言区域中无效的 wchar_t 字符。 * src 被设置为指向首个未转换的宽字符。
  • 待存储的下一个多字节字符将超出 len 限制。 * src 被设置为指向首个未转换的宽字符。若 dst 为空指针则不检查此条件。
2) 与 (1) 相同，但存在以下例外：
  • 函数通过输出参数 retval 返回结果
  • 若转换停止时未写入空字符，函数将在 dst 的下一个字节（可能是 dst [ len ] 或 dst [ dstsz ] 中较早出现的那个位置）存入 ' \0 ' （这意味着最多可能写入 len+1/dstsz+1 个字节）。此种情况下，终止空字符前可能不会写入复位序列
  • 函数会破坏目标数组中从终止空字符到 dstsz 范围的内容
  • 若 src 与 dst 存在重叠，行为未定义
  • 以下错误会在运行时被检测到，并调用当前安装的 约束处理函数 ：
  • retval 、 ps 、 src 或 * src 为空指针
  • dstsz 或 len 大于 RSIZE_MAX （除非 dst 为空指针）
  • dstsz 不为零（除非 dst 为空指针）
  • len 大于 dstsz 且转换在达到 dstsz 前未在 src 数组中遇到空字符或编码错误（除非 dst 为空指针）
与所有边界检查函数一样，仅当实现定义了 __STDC_LIB_EXT1__ 且用户在包含 <wchar.h> 前将 __STDC_WANT_LIB_EXT1__ 定义为整型常量 1 时，才保证 wcsrtombs_s 可用。

目录

参数

dst - 指向将存储多字节字符的窄字符数组的指针
src - 指向以空字符结尾的宽字符串首元素的指针的指针
len - dst所指数组中可用的字节数
ps - 指向转换状态对象的指针
dstsz - 将被写入的最大字节数（ dst 数组的大小）
retval - 指向将存储结果的 size_t 对象的指针

返回值

1) 成功时，返回写入到以 dst 指向的首元素的字符数组的字节数（包含任何移位序列，但不包含终止符 ' \0 ' ）。若 dst 为空指针，返回本应写入的字节数。转换错误时（若遇到无效宽字符），返回 ( size_t ) - 1 ，将 EILSEQ 存入 errno ，并使 * ps 处于未指定状态。
2) 成功时返回零（此时已写入或将要写入 dst 的字节数（不包括终止空字符）将存储于 * retval ），错误时返回非零值。若发生运行时约束违规，则向 * retval 存入 ( size_t ) - 1 （除非 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': %zu\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

参考文献

  • C17 标准 (ISO/IEC 9899:2018):
  • 7.29.6.4.2 wcsrtombs 函数 (页码: 324-325)
  • K.3.9.3.2.2 wcsrtombs_s 函数 (页码: 471-472)
  • C11 标准 (ISO/IEC 9899:2011):
  • 7.29.6.4.2 wcsrtombs 函数 (p: 446)
  • K.3.9.3.2.2 wcsrtombs_s 函数 (p: 649-651)
  • C99标准（ISO/IEC 9899:1999）：
  • 7.24.6.4.2 wcsrtombs函数（页码：392）

参见

(C11)
将宽字符串转换为窄多字节字符串
(函数)
(C95) (C11)
根据给定状态将宽字符转换为其多字节表示形式
(函数)
(C95) (C11)
根据给定状态将窄多字节字符串转换为宽字符串
(函数)
C++ documentation for wcsrtombs