格式化庫 (自 C++20 起)

 

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)

 

格式化 (Formatting) 函式庫

標準格式規範

格式化函數

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++ 標準。

DR	應用於	出版時的行為	正確的行為
P2418R2	C++20	既不可 const-formattable 也不可複製的物件 （例如類似生成器的物件）是不可格式化的	允許格式化這些物件 （放寬格式化器要求）
P2508R1	C++20	此設施沒有使用者可見的名稱	公開了名稱 basic_format_string

參見

print (C++23)	使用參數的格式化表示列印至 stdout 或檔案串流 (函式模板)
println (C++23)	與 std::print 相同，差別在於每個 print 都會以額外的換行符結尾 (函式模板)
print(std::ostream) (C++23)	輸出參數的格式化表示 (函式模板)