详解mbstowcs函数

发布时间：2023-05-18

一、 mbstowcsz函数

mbstowcsz 函数在标准 C 中未定义，但在 Microsoft Windows 中，它被定义为从多字节字符集 (MBCS) 转换为宽字符集。

int mbstowcsz(
    wchar_t *pwcs,
    const char *ptr,
    size_t size
);

mbstowcsz 函数将字符串的前 size 个字符从多字节字符集编码转换成相应的宽字符集编码，然后将结果存储在 wide-character 字符数组 pwcs 中。

二、mbstowcs_s源码

mbstowcs_s 是 mbstowcs 的安全版本，这意味着它对缓冲区的大小进行了检查，因此不会发生缓冲区溢出。

errno_t mbstowcs_s(
    size_t *pReturnValue,
    wchar_t *wcstr,
    size_t sizeInWords,
    const char *mbstr,
    size_t count
);

如果 mbstr 包含了一个由 sizeInWords 指定的字符数的字符串，那么 mbstowcs_s 将该字符串转换为 wcstr 所指定的拥有相同字符数的宽字符集字符串。 同时，还要注意 count 的值，如果小于 strlen(mbstr)+1，则 mbstowcs_s 会返回 ERANGE 错误。

三、mbstowcs_s函数

以下是 mbstowcs_s 的函数原型:

errno_t mbstowcs_s(
    size_t *pReturnValue,
    wchar_t *wcstr,
    size_t sizeInWords,
    const char *mbstr,
    size_t count
);

mbstowcs_s() 函数将 mbstr 所指定的多字节字符串（MBCS）转换成相应的宽字符字符串（WCS），并将结果放入由 wcstr 指示的字符数组中。转换的过程遵循制定的代码页和本地环境，不使用其他系统区域性信息。转换的字符串中不包括截止标志。如果 mbstr 不是合法的多字节字符字符串，则 mbstowcs_s() 返回 EINVAL 错误代码。 长度限制与大小相同，转换的字符数也不能超过 sizeInWords 所指定的大小。如果目标不能包含完整的字符串，函数将把转换后的部分存储到目标缓冲区中并将指向目标缓冲区的指针偏移写入 wcstargv（如果不为 NULL）。

四、mbstowcs_r函数

下面的示例代码将多字节字符串 mymbstr 转换为宽字符缓冲区 mywcstr。输出指针指向转换数据字符串的末尾：

int mbstowcs_r(
    wchar_t *pwcs,
    const char *s,
    size_t n,
    size_t *nresult,
    mbstate_t *ps
);

此函数在每个元素中对输出缓存限制为 n - 1 个宽字符，以便在缓存中放置两个终止符的宽字符。 如果 n 不是足够大的输出缓存，则 mbstowcs_r 函数将返回缓存的不完整转换。 执行后，返回值是已转换字符的数量。

五、mbstowcs函数

mbstowcs 函数将字符串从多字节字符集编码转换为宽字符集编码。

size_t mbstowcs(
    wchar_t *pwcs,
    const char *ptr,
    size_t max
);

该函数把字符串 ptr 中的前 max 个字符从多字节字符集编码转换成相应的宽字符集编码，然后把结果存储在 wide-character 字符数组 pwcs 中。 转换的字符串不包括终止符。如果 pwcs 是 NULL，则不记录转换结果，只返回目标数组中需要的长度。

六、mbstowcs_s函数

errno_t mbstowcs_s(
    size_t *pReturnValue,
    wchar_t *wcstr,
    size_t sizeInWords,
    const char *mbstr,
    size_t count
);

mbstowcs_s() 函数将 mbstr 所指定的多字节字符串（MBCS）转换成相应的宽字符字符串（WCS），并将结果放入由 wcstr 指示的字符数组中。转换的过程遵循制定的代码页和本地环境，不使用其他系统区域性信息。转换的字符串中不包括截止标志。如果 mbstr 不是合法的多字节字符字符串，则 mbstowcs_s() 返回 EINVAL 错误代码。 此函数会在扫描输入字符串时，将计数器 count 的值按其字符数递减。如果输入字符串中字符的数量超过 count，则无法将 null 结束的字符串 mbstr 转换为 null 结束的字符串 wcstr。因此， mbstowcs_s 函数确保不会把多于 count 字符的内容写到目标缓冲区中，并在这种情况下返回实际转换的字符数和 ERANGE 错误代码。 如果目标不能包含完整的字符串，函数将把转换后的部分存储到目标缓冲区中并将指向目标缓冲区的指针偏移写入 wcstargv（如果不为 NULL）。

七、mbstowcs utf8

mbstowcs utf8 将以 UTF-8 格式编码的字符串转换为宽字符字符串。

size_t mbstowcs(
    wchar_t *pwcs,
    const char *ptr,
    size_t max
);

在多字节字符集编码中，UTF-8 使用一至四个子节标识字符。在转换期间，以下字符使用一个宽字符表示：

  • 使用一个子节（0x0001 到 0x007F）的字符转换为相应的宽字符。
  • 使用两个字节（0x0080 到 0x07FF）中的字符转换为相应的两个宽字符（其中高位字符是由 0xD800 到 0xDBFF 动态分配的一个代码单元）。
  • 使用三个字节（0x0800 到 0xFFFF）中的字符转换为相应的三个宽字符。
  • 使用四个字节（0x10000 到 0x1FFFFF）中的字符转换为相应的四个宽字符。

八、mbstowcs 返回-1

如果输入字符串为 null，则 mbstowcs() 函数将返回 -1。 否则，返回输出缓冲区中写入的 wide-character 数量。

九、mbstowcs 中文字符返回-1

如果输入字符串包含无法在当前本地环境中转换为宽字符集的字符或字节，则 mbstowcs() 函数将返回 -1 并设置 errno 为静态数据中的 EILSEQ。

总结

本文通过对 mbstowcs 函数的多个相关函数进行详细阐述，包括 mbstowcsz、mbstowcs_s 源码、mbstowcs_s、mbstowcs_r、mbstowcs 函数、mbstowcs_s 函数、mbstowcs utf8、mbstowcs 返回-1、mbstowcs 中文字符返回-1等，让读者了解这些函数的用途，以及调用时需要注意的地方。

推荐文章