命名空间
变体
操作

mbsrtowcs, mbsrtowcs_s

来自 cppreference.cn
< c‎ | string‎ | multibyte
在头文件 <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,则将 L'\0' 存储在 dst[len] 中,这意味着总共写入 len+1 个宽字符
  • 函数从终止空字符到 dstsz 处覆盖目标数组
  • 如果 srcdst 重叠,则行为未指定。
  • 在运行时检测到以下错误并调用当前安装的约束处理程序函数
  • retvalpssrc*src 为空指针
  • dstszlen 大于 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 中),错误时返回非零。在运行时约束冲突的情况下,将 (size_t)-1 存储在 *retval 中(除非 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 函数 (p: 445)
  • K.3.9.3.2.1 mbsrtowcs_s 函数 (p: 648-649)
  • C99 标准 (ISO/IEC 9899:1999)
  • 7.24.6.4.1 mbsrtowcs 函数 (p: 391)

[编辑] 另请参阅

将窄多字节字符字符串转换为宽字符串
(函数) [编辑]
将下一个多字节字符转换为宽字符,给定状态
(函数) [编辑]
将宽字符串转换为窄多字节字符字符串,给定状态
(函数) [编辑]
C++ 文档 for mbsrtowcs