命名空间
变体
操作

std::to_chars

来自 cppreference.cn
< cpp‎ | 工具
 
C++
 
文本处理库
 
定义于头文件 <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 起)

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

1) 整数格式化器：value 被转换为给定 base （不带冗余前导零）的数字字符串。范围 10..35（含）中的数字表示为小写字符 a..z。如果 value 小于零，则表示以减号开头。库为所有 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。如果存在多个这样的表示，则选择与 value 差异最小的那个，并使用 std::round_to_nearest 的舍入规则解决任何剩余的平局。库为所有 cv 非限定 标准(C++23 前)浮点类型作为参数 value 的类型提供了重载。
4) 与 (3) 相同，但是如果 fmt 是 std::chars_format::fixed，则 as-if printf 指定的转换是 f；如果 fmt 是 std::chars_format::scientific，则为 e；如果 fmt 是 std::chars_format::hex，则为 a（但结果中没有前导 "0x"）；如果 fmt 是 chars_format::general，则为 g。库为所有 cv 非限定 标准(C++23 前)浮点类型作为参数 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"，则需要将其显式转换为另一个整数类型。

特性测试宏 值 标准 特性
__cpp_lib_to_chars 201611L (C++17) 基本字符串转换 (std::to_chars, std::from_chars)
202306L (C++26) 测试<charconv>函数的成功或失败
__cpp_lib_constexpr_charconv 202207L (C++23) 为整数类型添加 constexpr 修饰符到 std::to_chars 和 std::from_chars 重载 (1)

[编辑] 示例

运行此代码
#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++ 标准。

缺陷报告 应用于 发布时的行为 正确的行为
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> 的公有成员函数) [编辑]
取自 "https://cppreference.cn/mwiki/index.php?title=cpp/utility/to_chars&oldid=179100"