std::to_chars

 

C++

編譯器支援

獨立式與託管式

語言

標準函式庫

標準函式庫標頭檔

具名要求

特性測試巨集 (C++20)

語言支援函式庫

概念函式庫 (C++20)

診斷函式庫

記憶體管理函式庫

元編程函式庫 (C++11)

通用公用程式函式庫

容器函式庫

疊代器函式庫

Ranges 函式庫 (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)	(自 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 限定詞不修飾的(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)，但模擬 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。程式庫為所有 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 是獨立於語系（locale）、無配置記憶體行為且不會拋出例外的。它僅提供其他程式庫（如 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 <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> 的公開成員函式)