std::formatter - cppreference.com
|
|
(since C++20) | |
The enabled specializations of std::formatter define formatting rules for a given type. Enabled specializations meet the BasicFormatter requirements, and, unless otherwise specified, also meet the Formatter requirements.
For all types T and CharT for which no specialization std::formatter<T, CharT> is enabled, that specialization is a complete type and is disabled.
Disabled specializations do not meet the Formatter requirements, and the following are all 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.
Basic standard specializations
In the following list, CharT is either char or wchar_t, ArithmeticT is any cv-unqualified arithmetic type other than char, wchar_t, char8_t, char16_t, or char32_t:
| Character formatters |
||
|
|
(1) | |
|
|
(2) | |
|
|
(3) | |
| String formatters |
||
|
|
(4) | |
|
|
(5) | |
|
|
(6) | |
|
|
(7) | |
|
|
(8) | |
| Arithmetic formatters |
||
|
|
(9) | |
| Pointer formatters |
||
|
|
(10) | |
|
|
(11) | |
|
|
(12) | |
Formatters for other pointers and pointers to members are disabled.
Specializations such as std::formatter<wchar_t, char> and std::formatter<const char*, wchar_t> that would require encoding conversions are disabled.
|
The following specialization are still disabled in C++23 to avoid formatting some
A debug-enabled formatter specialization additionally provides a public non-static member function Each formatter specialization for string or character type is debug-enabled. |
(since C++23) |
Standard format specification
Standard specializations for library types
formatting support for duration (class template specialization) [edit] | |
formatting support for sys_time (class template specialization) [edit] | |
formatting support for utc_time (class template specialization) [edit] | |
formatting support for tai_time (class template specialization) [edit] | |
formatting support for gps_time (class template specialization) [edit] | |
formatting support for file_time (class template specialization) [edit] | |
formatting support for local_time (class template specialization) [edit] | |
formatting support for day (class template specialization) [edit] | |
formatting support for month (class template specialization) [edit] | |
formatting support for year (class template specialization) [edit] | |
formatting support for weekday (class template specialization) [edit] | |
formatting support for weekday_indexed (class template specialization) [edit] | |
formatting support for weekday_last (class template specialization) [edit] | |
formatting support for month_day (class template specialization) [edit] | |
formatting support for month_day_last (class template specialization) [edit] | |
formatting support for month_weekday (class template specialization) [edit] | |
formatting support for month_weekday_last (class template specialization) [edit] | |
formatting support for year_month (class template specialization) [edit] | |
formatting support for year_month_day (class template specialization) [edit] | |
formatting support for year_month_day_last (class template specialization) [edit] | |
formatting support for year_month_weekday (class template specialization) [edit] | |
formatting support for year_month_weekday_last (class template specialization) [edit] | |
formatting support for hh_mm_ss (class template specialization) [edit] | |
formatting support for sys_info (class template specialization) [edit] | |
formatting support for local_info (class template specialization) [edit] | |
formatting support for zoned_time (class template specialization) [edit] | |
formatting support for basic_stacktrace (class template specialization) [edit] | |
formatting support for stacktrace_entry (class template specialization) [edit] | |
formatting support for thread::id (class template specialization) [edit] | |
formatting support for vector<bool>::reference (class template specialization) [edit] | |
formatting support for pair and tuple (class template specialization) [edit] | |
(C++23) |
formatting support for ranges (class template specialization) [edit] |
(C++23) |
formatting support for std::stack (class template specialization) [edit] |
(C++23) |
formatting support for std::queue (class template specialization) [edit] |
formatting support for std::priority_queue (class template specialization) [edit] | |
formatting support for filesystem::path (class template specialization) [edit] |
Example
#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); }
Output:
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".
Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| LWG 3944 | C++23 | some char sequences were formattable as ranges of wchar_t
|
disable specializations added |