std::to_chars
在标头 <charconv> 定义
|
||
std::to_chars_result to_chars( char* first, char* last, |
(1) | (C++17 起) (C++23 起为 constexpr ) |
std::to_chars_result to_chars( char*, char*, bool, int = 10 ) = delete; |
(2) | (C++17 起) |
std::to_chars_result to_chars( char* first, char* last, /* floating-point-type */ value ); |
(3) | (C++17 起) |
std::to_chars_result to_chars( char* first, char* last, /* floating-point-type */ value, |
(4) | (C++17 起) |
std::to_chars_result to_chars( char* first, char* last, /* floating-point-type */ value, |
(5) | (C++17 起) |
通过连续填充范围 [
first,
last)
将 value 转换成字符串,[
first,
last)
要求是有效范围。
10..35
(含上下限)中的数字被表示成小写字母 a..z
。如果值小于零,那么该表示以负号开头。标准库提供以所有无 cv 限定的 (C++23 起)有符号及无符号整数和 char 类型作为形参 value 的类型的重载。std::to_chars
拒绝 bool 类型的实参,因为假如允许则结果会是 "0"/"1" 而非 "false"/"true"。printf
的转换指定为 f,在 fmt 是 std::chars_format::scientific 时指定为 e,在 fmt 是 std::chars_format::hex 时指定为 a(但结果无前导 "0x"),且在 fmt 是 chars_format::general 时指定为 g。标准库提供以所有无 cv 限定的标准 (C++23 前)浮点类型作为形参 value 的类型的重载。参数
first, last | - | 要写入的字符范围 |
value | - | 要转换到其字符串表示的值 |
base | - | 使用的整数底数:2 与 36 间的值(含上下限)。 |
fmt | - | 使用的浮点格式 std::chars_format 类型的位掩码 |
precision | - | 使用的浮点精度 |
返回值
成功时,返回 std::to_chars_result 类型的值,它的 ec
等于值初始化的 std::errc,且其 ptr
是指向被写入字符尾后一位置的指针。注意该字符串不 是空终止的。
错误时,返回 std::to_chars_result 类型的值,ec
保有 std::errc::value_too_large,ptr
保有 last 值的副本,并在范围 [
first,
last)
中留下未指定状态的内容。
异常
不抛出。
注解
不同于 C++ 和 C 库中的其他格式化函数,std::to_chars
独立于本地环境,不分配,而且不抛出。它只提供其他库(例如 std::sprintf)所用策略的一个小子集。它的目的是在常见的高吞吐量环境,例如基于文本的交换(JSON 或 XML)中,允许尽可能快的实现。
只有在两个函数都来自同一实现的情况下,才保证 std::from_chars 能恢复每个由 std::to_chars
格式化的浮点值。
如果想要格式化 bool 值为 "0"/"1",那么要求将它显式转型为另一整数类型。
功能特性测试宏 | 值 | 标准 | 功能特性 |
---|---|---|---|
__cpp_lib_to_chars |
201611L | (C++17) | 初等字符串转换(std::to_chars ,std::from_chars)
|
202306L | (C++26) | 检测 <charconv> 函数是否成功 | |
__cpp_lib_constexpr_charconv |
202207L | (C++23) | 向 std::to_chars 和 std::from_chars 对于整数类型的重载 (1) 添加 constexpr 修饰符
|
示例
#include <array> #include <charconv> #include <iostream> #include <string_view> #include <system_error> void show_to_chars(auto... format_args) { std::array<char, 10> str; #if __cpp_lib_to_chars >= 202306L and __cpp_structured_bindings >= 202406L // 使用 C++26 operator bool() 进行错误检查 if (auto res = std::to_chars(str.data(), str.data() + str.size(), format_args...)) std::cout << std::string_view(str.data(), res.ptr) << '\n'; else std::cout << std::make_error_code(res.ec).message() << '\n'; #else if (auto [ptr, ec] = std::to_chars(str.data(), str.data() + str.size(), format_args...); ec == std::errc()) std::cout << std::string_view(str.data(), ptr) << '\n'; else std::cout << std::make_error_code(ec).message() << '\n'; #endif } int main() { show_to_chars(42); show_to_chars(+3.14159F); show_to_chars(-3.14159, std::chars_format::fixed); show_to_chars(-3.14159, std::chars_format::scientific, 3); show_to_chars(3.1415926535, std::chars_format::fixed, 10); }
可能的输出:
42 3.14159 -3.14159 -3.142e+00 Value too large for defined data type
缺陷报告
下列更改行为的缺陷报告追溯地应用于以前出版的 C++ 标准。
缺陷报告 | 应用于 | 出版时的行为 | 正确行为 |
---|---|---|---|
LWG 2955 | C++17 | 此函数在 <utility> 且使用 std::error_code | 移动到 <charconv> 并使用 std::errc |
LWG 3266 | C++17 | 接受 bool 实参并将它提升到 int | 由弃置重载拒绝 |
LWG 3373 | C++17 | std::to_chars_result 可能拥有额外的成员
|
禁止额外的成员 |
参阅
(C++17) |
std::to_chars 的返回类型 (类) |
(C++17) |
转换字符序列到整数或浮点值 (函数) |
(C++11) |
转换整数或浮点值为 string (函数) |
(C++11) |
打印有格式输出到 stdout、文件流或缓冲区 (函数) |
插入带格式数据 ( std::basic_ostream<CharT,Traits> 的公开成员函数) |