Namespaces
Variants

mbstowcs, mbstowcs_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
定义于头文件 <stdlib.h>
(1)
size_t mbstowcs ( wchar_t * dst, const char * src, size_t len )
(C99前)
size_t mbstowcs ( wchar_t * restrict dst, const char * restrict src, size_t len )
(C99起)
errno_t mbstowcs_s ( size_t * restrict retval, wchar_t * restrict dst,
rsize_t dstsz, const char * restrict src, rsize_t len ) ;
(2) (C11起)
1) 将首个元素由 src 指向的数组中的多字节字符串转换为其宽字符表示形式。转换后的字符将存储在由 dst 指向的数组的连续元素中。最多向目标数组写入 len 个宽字符。
每个字符的转换过程如同调用 mbtowc 函数，但 mbtowc 的转换状态不受影响。满足以下条件时转换将终止：
* 多字节空字符已被转换并存储。
* 遇到无效的（在当前C语言环境中）多字节字符。
* 下一个待存储的宽字符将超过 len 。
如果 src 和 dst 发生重叠，则行为是未定义的
2) 与 (1) 相同，不同之处在于
* 转换过程如同通过 mbrtowc 进行，而非 mbtowc
* 函数通过输出参数 retval 返回其结果
* 如果在写入 len 个宽字符后没有向 dst 写入空字符，则会在 dst[len] 位置存储 L ' \0 ' ，这意味着总共写入 len+1 个宽字符
* 如果 dst 是空指针，将生成的宽字符数量存储于 * retval
* 该函数会从终止空字符开始直到 dstsz 位置覆盖目标数组
* 如果 src 和 dst 存在重叠，行为是未定义的。
* 以下错误在运行时被检测到，并会调用当前安装的 约束处理函数 ：
  • retval 或 src 是空指针
  • dstsz 或 len 大于 RSIZE_MAX/sizeof(wchar_t) （除非 dst 为空）
  • dstsz 不为零（除非 dst 为空）
  • 在 src 数组的前 dstsz 个多字节字符中没有空字符，且 len 大于 dstsz （除非 dst 为空）
与所有边界检查函数一样，仅当实现定义了 __STDC_LIB_EXT1__ 且用户在包含 <stdlib.h> 之前将 __STDC_WANT_LIB_EXT1__ 定义为整型常量 1 时，才保证 mbstowcs_s 可用。

目录

注释

在大多数实现中， mbstowcs 在处理字符串时会更新一个类型为 mbstate_t 的全局静态对象，因此无法被两个线程同时调用，在此类情况下应使用 mbsrtowcs 。

POSIX 规定了一个通用扩展：如果 dst 是空指针，本函数将返回若转换完成时将被写入 dst 的宽字符数量。类似的行为对于 mbstowcs_s 和 mbsrtowcs 是标准化的。

参数

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

返回值

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

示例

运行此代码 
#include <stdio.h>
#include <locale.h>
#include <stdlib.h>
#include <wchar.h>
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    const char* mbstr = u8"z\u00df\u6c34\U0001F34C"; // or u8"zß水🍌"
    wchar_t wstr[5];
    mbstowcs(wstr, mbstr, 5);
    wprintf(L"MB string: %s\n", mbstr);
    wprintf(L"Wide string: %ls\n", wstr);
}

输出： 

MB string: zß水🍌
Wide string: zß水🍌

参考文献

  • C11 标准 (ISO/IEC 9899:2011):
  • 7.22.8.1 mbstowcs 函数 (第 359 页)
  • K.3.6.5.1 mbstowcs_s 函数 (第 611-612 页)
  • C99 标准 (ISO/IEC 9899:1999):
  • 7.20.8.1 mbstowcs 函数 (第 323 页)
  • C89/C90 标准 (ISO/IEC 9899:1990):
  • 4.10.8.1 mbstowcs 函数

参见

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