格式化庫 (C++20 起)

 

C++

編譯器支援

自由（freestanding）與宿主（hosted）

語言

標準庫

標準庫標頭檔案

具名要求

特性測試宏 (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)

 

格式化庫

標準格式規範

格式化函式

format (C++20)

format_to (C++20)

format_to_n (C++20)

formatted_size (C++20)

vformat (C++20)

vformat_to (C++20)

格式字串

basic_format_stringformat_stringwformat_string (C++20)(C++20)(C++20)

runtime_format (C++26)

格式化概念

formattable (C++23)

Formatter

formatter (C++20)

formatter<pair-or-tuple> (C++23)

formatter<range> (C++23)

range_formatter (C++23)

enable_nonlocking_formatter_optimization (C++23)

basic_format_parse_contextformat_parse_contextwformat_parse_context (C++20)(C++20)(C++20)

basic_format_contextformat_contextwformat_context (C++20)(C++20)(C++20)

range_format (C++23)

format_kind (C++23)

格式化引數

basic_format_arg (C++20)

basic_format_arg::handle (C++20)

basic_format_argsformat_argswformat_args (C++20)(C++20)(C++20)

visit_format_arg (C++20) (在 C++26 中廢棄)

make_format_argsmake_wformat_args (C++20)(C++20)

格式錯誤

format_error (C++20)

 

文字格式化庫提供了一種安全且可擴充套件的替代方案，以取代 printf 系列函式。它旨在補充現有的 C++ I/O 流庫。

格式規範

格式規範指定了物件如何以不同型別的選項進行格式化。

基本型別和標準字串型別的物件格式化使用基本格式規範。其他庫元件也可能提供自己的格式規範，詳見此處。

格式化函式

定義於標頭檔案 <format>
format (C++20)	將引數的格式化表示儲存在新字串中 (函式模板)
format_to (C++20)	透過輸出迭代器寫出其引數的格式化表示 (函式模板)
format_to_n (C++20)	透過輸出迭代器寫出其引數的格式化表示，不超過指定大小 (函式模板)
formatted_size (C++20)	確定儲存其引數格式化表示所需的字元數 (函式模板)

格式字串

定義於標頭檔案 <format>
basic_format_stringformat_stringwformat_string (C++20)(C++20)(C++20)	在構造時執行編譯時格式字串檢查的類模板 (類模板)
runtime_format (C++26)	建立可直接用於面向使用者的格式化函式的執行時格式字串 (函式)

格式化概念

定義於標頭檔案 <format>
formattable (C++23)	指定一個型別是可格式化的，即它專門化了 std::formatter 並提供了成員函式 parse 和 format (概念)

可擴充套件性支援和實現細節

定義於標頭檔案 <format>
vformat (C++20)	使用型別擦除引數表示的 std::format 的非模板變體 (函式)
vformat_to (C++20)	使用型別擦除引數表示的 std::format_to 的非模板變體 (函式模板)
make_format_argsmake_wformat_args (C++20)(C++20)	建立引用所有格式化引數的型別擦除物件，可轉換為 format_args (函式模板)
visit_format_arg (C++20) (在 C++26 中廢棄)	使用者定義格式化器的引數訪問介面 (函式模板)
formatter (C++20)	定義給定型別的格式化規則 (類模板)
range_formatter (C++23)	有助於實現範圍型別的 std::formatter 特化的類模板 (類模板)
enable_nonlocking_formatter_optimization (C++23)	指示引數型別可以高效列印 (變數模板)
range_format (C++23)	指定範圍應如何格式化 (列舉)
format_kind (C++23)	為範圍選擇合適的 std::range_format (變數模板)
basic_format_arg (C++20)	為使用者定義格式化器提供格式化引數訪問的類模板 (類模板)
basic_format_argsformat_argswformat_args (C++20)(C++20)(C++20)	提供對所有格式化引數訪問的類 (類模板)
basic_format_contextformat_contextwformat_context (C++20)(C++20)(C++20)	格式化狀態，包括所有格式化引數和輸出迭代器 (類模板)
basic_format_parse_contextformat_parse_contextwformat_parse_context (C++20)(C++20)(C++20)	格式化字串解析器狀態 (類模板)
format_error (C++20)	格式化錯誤時丟擲的異常型別 (類)

輔助項 (C++23 起)

template< class R, class CharT > concept /*const-formattable-range*/ =     ranges::input_range<const R> &&     std::formattable<ranges::range_reference_t<const R>, CharT>;	(1)	(僅作說明*)
template< class R, class CharT > using /*fmt-maybe-const*/ =     std::conditional_t</*const-formattable-range*/<R, CharT>, const R, R>;	(2)	(僅作說明*)

注意

特性測試宏	值	標準	特性
__cpp_lib_format	201907L	(C++20)	文字格式化
	202106L	(C++23) (DR20)	編譯時格式字串檢查； 減少 std::vformat_to 的引數化
	202110L	(C++23) (DR20)	修復 chrono 格式化器中的區域設定處理； 支援不可 const-formattable 的型別
	202207L	(C++23) (DR20)	公開 std::basic_format_string； 澄清 chrono 型別本地化格式化中編碼的處理
	202304L	(C++26)	指標格式化
	202305L	(C++26)	型別檢查格式引數
	202306L	(C++26)	成員 std::basic_format_arg::visit
	202311L	(C++26)	執行時格式字串
	202403L	(C++26)	使用 std::println 列印空行
	202403L	(C++26) (DR23)	允許 std::print 的高效實現
__cpp_lib_format_ranges	202207L	(C++23)	格式化範圍
__cpp_lib_format_path	202403L	(C++26)	格式化 std::filesystem::path
__cpp_lib_format_uchar	202311L	(C++26)	修復程式碼單元作為整數的格式化
__cpp_lib_formatters	202302L	(C++23)	格式化 std::thread::id 和 std::stacktrace

我們有意將 std::basic_format_string (P2508) 的新增視為缺陷報告，因為所有已知實現都在 C++20 模式下提供這些元件，儘管它並未正式歸類。

示例

執行此程式碼

#include <cassert>
#include <format>
 
int main()
{
    std::string message = std::format("The answer is {}.", 42);
    assert(message == "The answer is 42.");
}

缺陷報告

下列更改行為的缺陷報告追溯地應用於以前出版的 C++ 標準。

缺陷報告	應用於	釋出時的行為	正確的行為
P2418R2	C++20	既不可 const-formattable 也不可複製的物件 (例如生成器類物件) 不可格式化	允許格式化這些物件 (放寬格式化器要求)
P2508R1	C++20	該功能沒有使用者可見的名稱	公開了名稱 basic_format_string

另請參見

print (C++23)	使用引數的格式化表示列印到 stdout 或檔案流 (函式模板)
println (C++23)	與 std::print 相同，但每次列印都以額外的換行符終止 (函式模板)
print(std::ostream) (C++23)	輸出引數的格式化表示 (函式模板)