std::wcstombs

< cpp‎ | string‎ | multibyte
 
C++
 
字符串库
 
空终止多字节字符串
宽/多字节转换
wcstombs
(C++20)
(C++11)
(C++11)
类型
 
定义于头文件 <cstdlib>
std::size_t wcstombs( char* dst, const wchar_t* src, std::size_t len);

转换来自首元素为 src 所指向的数组到其始于初始迁移状态的多字节表示。转换出的字符被存储于 dst 所指向的数组的相继元素。写入目标数组的字节数不多于 len 。

如同以调用 std::wctomb 每个字符，除了 wctomb 的转换状态不受影响。若满足下列条件则转换停止：

  • 转换并存储空字符。
  • 找到当前 C 本地环境中不对应合法字符的 wchar_t 。
  • 下个要存储的多字节字符会超出 len 。

注意

大多数实现中，此函数在处理过字符串时更新 std::mbstate_t 类型的全局静态对象，而且不能为二个线程同时调用，这种情况下应使用 std::wcsrtombs 。

POSIX 指定一个常见扩展：若 dst 是空指针，则此函数返回假设转换则会写入 dst 的字节数。类似行为对于 std::wcsrtombs 是标准。

参数

dst - 指向窄字符数组的指针，其中将存储多字节字符
src - 指向要转换的空终止宽字符串首字符的指针
len - dst 所指向数组中的可用字节数

返回值

成功时，返回写入首元素为 dst 所指向的字符数组的字节数（包含任何迁移序列，但不含终止的 '\0' ）。

转换错误时（若遇到非法宽字符），返回 static_cast<std::size_t>(-1) 。

示例

运行此代码
#include <iostream>
#include <clocale>
#include <cstdlib>
 
int main()
{
    std::setlocale(LC_ALL, "en_US.utf8");
    // UTF-8 窄多字节编码
    const wchar_t* wstr = L"z\u00df\u6c34\U0001d10b"; // 或 L"zß水𝄋"
    char mbstr[11];
    std::wcstombs(mbstr, wstr, 11);
    std::cout << "multibyte string: " << mbstr << '\n';
}

输出： 

multibyte string: zß水𝄋

参阅

 给定状态，转换宽字符串为窄多字节字符串
(函数)
转换窄多字节字符串为宽字符串
(函数)
[虚]
 从 internT 转换字符串为 externT 转换字符串，如在写入文件时
(std::codecvt<InternT,ExternT,State> 的虚受保护成员函数)