Namespaces
Variants

std:: to_chars

From cppreference.net
C++
Text processing library
定义于头文件 <charconv>
std :: to_chars_result

to_chars ( char * first, char * last,

/* integer-type */ value, int base = 10 ) ;
(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,

std:: chars_format fmt ) ;
(4) (C++17 起)
std :: to_chars_result

to_chars ( char * first, char * last, /* floating-point-type */ value,

std:: chars_format fmt, int precision ) ;
(5) (C++17 起)

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

1) 整数格式化器： value 被转换为指定 base 进制下的数字字符串（不含冗余前导零）。 10..35 （含边界）范围内的数字以小写字母 a..z 表示。若数值小于零，表示形式以负号开头。该库为所有cv非限定有符号与无符号整数类型，以及作为参数 value 类型的 char 类型提供了重载。
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指定的转换格式为：当 fmt 为 std::chars_format::fixed 时使用 f ；当 fmt 为 std::chars_format::scientific 时使用 e ；当 fmt 为 std::chars_format::hex 时使用 a （但结果中不带前导"0x"）；当 fmt 为 chars_format::general 时使用 g 。该库为所有 标准 (C++23前) 浮点类型的无cv限定版本提供参数 value 的重载。
5) 与 (4) 相同，但精度由参数 precision 指定，而非最短表示要求。该库为所有 cv 未限定 标准 (C++23 前) 浮点类型提供了参数 value 类型的重载。

目录

参数

first, last - 要写入的字符范围
value - 要转换为其字符串表示形式的值
base - 使用的整数进制：介于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" 使用 std::to_chars ，必须将该值转换为其他整数类型。

功能测试 宏 值 标准 功能
__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"
值对于定义的数据类型过大

缺陷报告

下列行为变更缺陷报告被追溯应用于先前发布的 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> 的公开成员函数)