Namespaces
Variants

mbsrtowcs, mbsrtowcs_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
定义于头文件 <wchar.h>
(1)
size_t mbsrtowcs ( wchar_t * dst, const char ** src, size_t len, mbstate_t * ps ) ;
(C95 起)
(C99 前)
size_t mbsrtowcs ( wchar_t * restrict dst, const char ** restrict src, size_t len,
mbstate_t * restrict ps ) ;
(C99 起)
errno_t mbsrtowcs_s ( size_t * restrict retval,

wchar_t * restrict dst, rsize_t dstsz,
const char ** restrict src, rsize_t len,

mbstate_t * restrict ps ) ;
(2) (C11 起)
1) 将始于转换状态 *ps 所描述的多字节字符序列（以空字符结尾），从由 * src 指向的数组首元素开始，转换为其宽字符表示形式。若 dst 非空，则转换后的字符将存储到由 dst 指向的 wchar_t 数组的连续元素中。最多向目标数组写入 len 个宽字符。每个多字节字符的转换过程如同调用 mbrtowc 。遇到以下情况时转换停止：
  • 已转换并存储了多字节空字符。 * src 被设为空指针值，且 *ps 表示初始移位状态。
  • 遇到无效的多字节字符（根据当前 C 本地化设置）。 * src 被设为指向首个未转换多字节字符的起始位置。
  • 待存储的下一个宽字符将超出 len 限制。 * src 被设为指向首个未转换多字节字符的起始位置。若 dst 为空指针则不检查此条件。
2) 与 (1) 相同，但有以下例外：
  • 函数通过输出参数 retval 返回结果
  • 若在写入 len 个宽字符后未向 dst 写入空字符，则会在 dst[len] 处存储 L ' \0 ' ，这意味着总共写入 len+1 个宽字符
  • 函数会从终止空字符开始直到 dstsz 位置覆盖目标数组
  • 若 src 与 dst 存在重叠，行为未定义
  • 以下错误会在运行时被检测到，并调用当前安装的 约束处理函数 ：
  • retval 、 ps 、 src 或 * src 为空指针
  • dstsz 或 len 大于 RSIZE_MAX/sizeof(wchar_t) （除非 dst 为空）
  • dstsz 不为零（除非 dst 为空）
  • 在 * src 数组的前 dstsz 个多字节字符中不存在空字符，且 len 大于 dstsz （除非 dst 为空）
与所有边界检查函数一样，仅当实现定义了 __STDC_LIB_EXT1__ 且用户在包含 <wchar.h> 前将 __STDC_WANT_LIB_EXT1__ 定义为整型常量 1 时，才保证 mbsrtowcs_s 可用。

目录

参数

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

返回值

1) 成功时，返回写入字符数组的宽字符数（不包含终止符 L ' \0 ' ）。若 dst 是空指针，则返回假设长度不受限时本应写入的宽字符数。转换错误时（若遇到无效多字节字符），返回 ( size_t ) - 1 ，将 EILSEQ 存入 errno ，并使 * ps 处于未指定状态。
2) 成功时返回零（此时会向 dst 写入或本应写入的宽字符数（不含终止空字符）将存储于 * retval ），错误时返回非零值。若发生运行时约束违规，则向 * retval 存入 ( size_t ) - 1 （除非 retval 为空指针），同时设置 dst [ 0 ] 为 L ' \0 ' （除非 dst 为空指针，或 dstmax 为零或大于 RSIZE_MAX ）

示例

运行此代码 
#include <stdio.h>
#include <locale.h>
#include <wchar.h>
#include <string.h>
void print_as_wide(const char* mbstr)
{
    mbstate_t state;
    memset(&state, 0, sizeof state);
    size_t len = 1 + mbsrtowcs(NULL, &mbstr, 0, &state);
    wchar_t wstr[len];
    mbsrtowcs(&wstr[0], &mbstr, len, &state);
    wprintf(L"Wide string: %ls \n", wstr);
    wprintf(L"The length, including L'\\0': %zu\n", len);
}
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    print_as_wide(u8"z\u00df\u6c34\U0001f34c"); // u8"zß水🍌"
}

输出： 

Wide string: zß水🍌
The length, including L'\0': 5

参考文献

  • C11 标准 (ISO/IEC 9899:2011):
  • 7.29.6.4.1 mbsrtowcs 函数 (第 445 页)
  • K.3.9.3.2.1 mbsrtowcs_s 函数 (第 648-649 页)
  • C99 标准 (ISO/IEC 9899:1999):
  • 7.24.6.4.1 mbsrtowcs 函数 (第 391 页)

参见

(C11)
将窄多字节字符串转换为宽字符串
(函数)
(C95)
在给定状态下将下一个多字节字符转换为宽字符
(函数)
(C95) (C11)
在给定状态下将宽字符串转换为窄多字节字符串
(函数)
C++ 文档 for mbsrtowcs