std::to_chars

 

C++

编译器支持

独立式和宿主式

语言

标准库

标准库头文件

具名要求

特性测试宏 (C++20)

语言支持库

概念库 (C++20)

诊断库

内存管理库

元编程库 (C++11)

通用工具库

容器库

迭代器库

范围库 (C++20)

算法库

字符串库

文本处理库

数值库

日期和时间库

输入/输出库

文件系统库 (C++17)

并发支持库 (C++11)

执行控制库 (C++26)

技术规范

符号索引

外部库

 

文本处理库

本地化库

正则表达式库 (C++11)

格式化库 (C++20)

空字符结尾序列工具

字节字符串

多字节字符串

宽字符串

原始数值转换

to_chars (C++17) to_chars_result (C++17) from_chars (C++17) from_chars_result (C++17) chars_format (C++17)

文本编码标识

text_encoding (C++26)

 

定义于头文件 <charconv>
std::to_chars_result     to_chars( char* first, char* last,               /* integer-type */ value, int base = 10 );	(1)	(since C++17) (constexpr since C++23)
std::to_chars_result     to_chars( char*, char*, bool, int = 10 ) = delete;	(2)	(since C++17)
std::to_chars_result     to_chars( char* first, char* last, /* floating-point-type */ value );	(3)	(since C++17)
std::to_chars_result     to_chars( char* first, char* last, /* floating-point-type */ value,               std::chars_format fmt );	(4)	(since C++17)
std::to_chars_result     to_chars( char* first, char* last, /* floating-point-type */ value,               std::chars_format fmt, int precision );	(5)	(since C++17)

通过连续填充范围 [first, last)，将 value 转换为字符串，其中 [first, last) 必须是有效范围。

1) 整数格式化器：value 被转换为给定 base 中的数字字符串（没有冗余的前导零）。范围 10..35 （包括）中的数字表示为小写字符 a..z。如果值小于零，则表示形式以减号开头。该库为所有 cv-未限定的(自 C++23 起) 有符号和无符号整数类型以及类型 char 作为参数 value 的类型提供了重载。

2) bool 的重载被删除。 std::to_chars 拒绝 bool 类型的参数，因为如果允许，结果将是 "0"/"1" 而不是 "false"/"true"。

3) value 被转换为字符串，如同在默认的 ("C") 区域设置中通过 std::printf 一样。转换说明符是 f 或 e （在平局的情况下偏向于 f ），根据最短表示形式的要求选择：字符串表示形式由最小数量的字符组成，使得在小数点（如果存在）之前至少有一位数字，并且使用相应的 std::from_chars 函数解析表示形式可以完全恢复值。如果存在多个这样的表示形式，则选择与 value 差异最小的一个，并根据 std::round_to_nearest 使用舍入来解决任何剩余的平局。该库为所有 cv-未限定的 标准(直到 C++23) 浮点类型作为参数 value 的类型提供了重载。

4) 与 (3) 相同，但为 as-if printf 指定的转换是 f 如果 fmt 是 std::chars_format::fixed， e 如果 fmt 是 std::chars_format::scientific， a （但在结果中没有前导 "0x" ）如果 fmt 是 std::chars_format::hex，以及 g 如果 fmt 是 chars_format::general。该库为所有 cv-未限定的 标准(直到 C++23) 浮点类型作为参数 value 的类型提供了重载。

5) 与 (4) 相同，除了精度由参数 precision 而不是最短表示形式要求指定。该库为所有 cv-未限定的 标准(直到 C++23) 浮点类型作为参数 value 的类型提供了重载。

参数

first, last	-	写入字符的范围
value	-	要转换为字符串表示形式的值
base	-	要使用的整数基数：介于 2 和 36 之间的值（包括 2 和 36）。
fmt	-	要使用的浮点格式，std::chars_format 类型的位掩码
precision	-	要使用的浮点精度

返回值

成功时，返回 std::to_chars_result 类型的值，使得 ec 等于值初始化的 std::errc 并且 ptr 是写入字符的末尾后指针。请注意，该字符串未以 NUL 结尾。

出错时，返回 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" ，则需要显式地将 bool 值强制转换为另一种整数类型。

特性测试 宏	值	Std	特性
__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 <charconv>
#include <iomanip>
#include <iostream>
#include <string_view>
#include <system_error>
 
void show_to_chars(auto... format_args)
{
    const size_t buf_size = 10;
    char buf[buf_size]{};
    std::to_chars_result result = std::to_chars(buf, buf + buf_size, format_args...);
 
    if (result.ec != std::errc())
        std::cout << std::make_error_code(result.ec).message() << '\n';
    else
    {
        std::string_view str(buf, result.ptr - buf);
        std::cout << std::quoted(str) << '\n';
    }
}
 
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++ 标准。

DR	应用于	已发布的行为	正确的行为
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 可能有其他成员	不允许有其他成员

参见

to_chars_result (C++17)	std::to_chars 的返回类型 (类)
from_chars (C++17)	将字符序列转换为整数或浮点值 (函数)
to_string (C++11)	将整数或浮点值转换为 string (函数)
printffprintfsprintfsnprintf (C++11)	将格式化输出打印到 stdout、文件流或缓冲区 (函数)
operator<<	插入格式化数据 (std::basic_ostream<CharT,Traits> 的公共成员函数)