std::formatter

 

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)

 

定義於標頭檔案 <format>
template< class T, class CharT = char > struct formatter;		(C++20 起)

std::formatter 的已啟用特化定義了給定型別的格式化規則。已啟用的特化滿足 BasicFormatter 要求，並且，除非另有說明，也滿足 Formatter 要求。

對於所有型別 T 和 CharT，如果未啟用 std::formatter<T, CharT> 的特化，則該特化是完整型別且被停用。

停用的特化不滿足 Formatter 要求，並且以下均為 false

• std::is_default_constructible_v
• std::is_copy_constructible_v
• std::is_move_constructible_v
• std::is_copy_assignable_v
• std::is_move_assignable_v.

基本標準特化

在以下列表中，CharT 是 char 或 wchar_t，ArithmeticT 是除了 char、wchar_t、char8_t、char16_t 或 char32_t 之外的任何 cv-非限定算術型別。

字元格式化器
template<> struct formatter<char, char>;	(1)
template<> struct formatter<char, wchar_t>;	(2)
template<> struct formatter<wchar_t, wchar_t>;	(3)
字串格式化器
template<> struct formatter<CharT*, CharT>;	(4)
template<> struct formatter<const CharT*, CharT>;	(5)
template< std::size_t N > struct formatter<CharT[N], CharT>;	(6)
template< class Traits, class Alloc > struct formatter<std::basic_string<CharT, Traits, Alloc>, CharT>;	(7)
template< class Traits > struct formatter<std::basic_string_view<CharT, Traits>, CharT>;	(8)
算術格式化器
template<> struct formatter<ArithmeticT, CharT>;	(9)
指標格式化器
template<> struct formatter<std::nullptr_t, CharT>;	(10)
template<> struct formatter<void*, CharT>;	(11)
template<> struct formatter<const void*, CharT>;	(12)

其他指標和成員指標的格式化器被停用。

需要編碼轉換的特化，例如 std::formatter<wchar_t, char> 和 std::formatter<const char*, wchar_t> 被停用。

以下特化在 C++23 中仍被停用，以避免將某些 char 序列格式化為 wchar_t 範圍 停用的 wchar_t 格式化器 template<> struct formatter<char*, wchar_t>; (1) template<> struct formatter<const char*, wchar_t>; (2) template< std::size_t N > struct formatter<char[N], wchar_t>; (3) template< class Traits, class Allocator > struct formatter<std::basic_string<char, Traits, Allocator>, wchar_t>; (4) template< class Traits > struct formatter<std::basic_string_view<char, Traits>, wchar_t>; (5) 啟用除錯的格式化器特化額外提供一個公共非靜態成員函式 constexpr void set_debug_format();，它修改格式化器物件的狀態，使其將值格式化為 轉義並加引號，就像上次呼叫 parse 解析的格式說明符的 type 是 ? 一樣。 每個字串或字元型別的格式化器特化都啟用除錯。

(C++23 起)

庫型別的標準特化

std::formatter<std::chrono::duration> (C++20)	duration 的格式化支援 (類模板特化)
std::formatter<std::chrono::sys_time> (C++20)	sys_time 的格式化支援 (類模板特化)
std::formatter<std::chrono::utc_time> (C++20)	utc_time 的格式化支援 (類模板特化)
std::formatter<std::chrono::tai_time> (C++20)	tai_time 的格式化支援 (類模板特化)
std::formatter<std::chrono::gps_time> (C++20)	gps_time 的格式化支援 (類模板特化)
std::formatter<std::chrono::file_time> (C++20)	file_time 的格式化支援 (類模板特化)
std::formatter<std::chrono::local_time> (C++20)	local_time 的格式化支援 (類模板特化)
std::formatter<std::chrono::day> (C++20)	day 的格式化支援 (類模板特化)
std::formatter<std::chrono::month> (C++20)	month 的格式化支援 (類模板特化)
std::formatter<std::chrono::year> (C++20)	year 的格式化支援 (類模板特化)
std::formatter<std::chrono::weekday> (C++20)	weekday 的格式化支援 (類模板特化)
std::formatter<std::chrono::weekday_indexed> (C++20)	weekday_indexed 的格式化支援 (類模板特化)
std::formatter<std::chrono::weekday_last> (C++20)	weekday_last 的格式化支援 (類模板特化)
std::formatter<std::chrono::month_day> (C++20)	month_day 的格式化支援 (類模板特化)
std::formatter<std::chrono::month_day_last> (C++20)	month_day_last 的格式化支援 (類模板特化)
std::formatter<std::chrono::month_weekday> (C++20)	month_weekday 的格式化支援 (類模板特化)
std::formatter<std::chrono::month_weekday_last> (C++20)	month_weekday_last 的格式化支援 (類模板特化)
std::formatter<std::chrono::year_month> (C++20)	year_month 的格式化支援 (類模板特化)
std::formatter<std::chrono::year_month_day> (C++20)	year_month_day 的格式化支援 (類模板特化)
std::formatter<std::chrono::year_month_day_last> (C++20)	year_month_day_last 的格式化支援 (類模板特化)
std::formatter<std::chrono::year_month_weekday> (C++20)	year_month_weekday 的格式化支援 (類模板特化)
std::formatter<std::chrono::year_month_weekday_last> (C++20)	year_month_weekday_last 的格式化支援 (類模板特化)
std::formatter<std::chrono::hh_mm_ss> (C++20)	hh_mm_ss 的格式化支援 (類模板特化)
std::formatter<std::chrono::sys_info> (C++20)	sys_info 的格式化支援 (類模板特化)
std::formatter<std::chrono::local_info> (C++20)	local_info 的格式化支援 (類模板特化)
std::formatter<std::chrono::zoned_time> (C++20)	zoned_time 的格式化支援 (類模板特化)
std::formatter<std::basic_stacktrace> (C++23)	對 basic_stacktrace 的格式化支援 (類模板特化)
std::formatter<std::stacktrace_entry> (C++23)	對 stacktrace_entry 的格式化支援 (類模板特化)
std::formatter<std::thread::id> (C++23)	對 thread::id 的格式化支援 (類模板特化)
std::formatter<std::vector<bool>::reference> (C++23)	對 vector<bool>::reference 的格式化支援 (類模板特化)
std::formatter<pair-or-tuple> (C++23)	對 pair 和 tuple 的格式化支援 (類模板特化)
std::formatter<range> (C++23)	對範圍的格式化支援 (類模板特化)
std::formatter<std::stack> (C++23)	對 std::stack 的格式化支援 (類模板特化)
std::formatter<std::queue> (C++23)	對 std::queue 的格式化支援 (類模板特化)
std::formatter<std::priority_queue> (C++23)	對 std::priority_queue 的格式化支援 (類模板特化)
std::formatter<std::filesystem::path> (C++26)	對 filesystem::path 的格式化支援 (類模板特化)

示例

執行此程式碼

#include <algorithm>
#include <format>
#include <iomanip>
#include <iostream>
#include <sstream>
#include <string_view>
 
struct QuotableString : std::string_view
{};
 
template<>
struct std::formatter<QuotableString, char>
{
    bool quoted = false;
 
    template<class ParseContext>
    constexpr ParseContext::iterator parse(ParseContext& ctx)
    {
        auto it = ctx.begin();
        if (it == ctx.end())
            return it;
 
        if (*it == '#')
        {
            quoted = true;
            ++it;
        }
        if (it != ctx.end() && *it != '}')
            throw std::format_error("Invalid format args for QuotableString.");
 
        return it;
    }
 
    template<class FmtContext>
    FmtContext::iterator format(QuotableString s, FmtContext& ctx) const
    {
        std::ostringstream out;
        if (quoted)
            out << std::quoted(s);
        else
            out << s;
 
        return std::ranges::copy(std::move(out).str(), ctx.out()).out;
    }
};
 
int main()
{
    QuotableString a("be"), a2(R"( " be " )");
    QuotableString b("a question");
    std::cout << std::format("To {0} or not to {0}, that is {1}.\n", a, b);
    std::cout << std::format("To {0:} or not to {0:}, that is {1:}.\n", a, b);
    std::cout << std::format("To {0:#} or not to {0:#}, that is {1:#}.\n", a2, b);
}

輸出

To be or not to be, that is a question.
To be or not to be, that is a question.
To " \" be \" " or not to " \" be \" ", that is "a question".

缺陷報告

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

缺陷報告	應用於	釋出時的行為	正確的行為
LWG 3944	C++23	某些 char 序列可被格式化為 wchar_t 範圍	已新增停用特化

另請參閱

basic_format_contextformat_contextwformat_context (C++20 起)(C++20 起)(C++20 起)	格式化狀態，包括所有格式化引數和輸出迭代器 (類模板)
formattable (C++23)	指定型別是可格式化的，即它特化了 std::formatter 並提供了成員函式 parse 和 format (概念)
range_formatter (C++23)	類模板，有助於實現範圍型別的 std::formatter 特化 (類模板)