| Localization library | |||||||||||||||||||||||||
| Regular expressions library(C++11) | |||||||||||||||||||||||||
| Formatting library(C++20) | |||||||||||||||||||||||||
| Null-terminated sequence utilities | |||||||||||||||||||||||||
| Byte strings | |||||||||||||||||||||||||
| Multibyte strings | |||||||||||||||||||||||||
| Wide strings | |||||||||||||||||||||||||
| Primitive numeric conversions | |||||||||||||||||||||||||
| |||||||||||||||||||||||||
| Text encoding identifications | |||||||||||||||||||||||||
| |||||||||||||||||||||||||
| Standard format specification | ||||
| Formatting functions | ||||
(C++20) | ||||
(C++20) | ||||
(C++20) | ||||
(C++20) | ||||
(C++20) | ||||
(C++20) | ||||
| Format strings | ||||
(C++20)(C++20)(C++20) | ||||
(C++26) | ||||
| Formatting concepts | ||||
(C++23) | ||||
| Formatter | ||||
formatter (C++20) | ||||
(C++23) | ||||
(C++23) | ||||
(C++23) | ||||
(C++20)(C++20)(C++20) | ||||
(C++20)(C++20)(C++20) | ||||
(C++23) | ||||
(C++23) | ||||
| Formatting arguments | ||||
(C++20) | ||||
(C++20) | ||||
(C++20)(C++20)(C++20) | ||||
(C++20)(deprecated in C++26) | ||||
(C++20)(C++20) | ||||
| Format error | ||||
(C++20) |
Defined in header <format> | ||
template<class T,class CharT=char> struct formatter; | (since C++20) | |
The enabled specializations ofstd::formatter define formatting rules for a given type. Enabled specializations meet theBasicFormatter requirements, and, unless otherwise specified, also meet theFormatter requirements.
For all typesT andCharT for which no specializationstd::formatter<T, CharT> is enabled, that specialization is a complete type and is disabled.
Disabled specializations do not meet theFormatter requirements, and the following are allfalse:
Contents |
In the following list,CharT is eitherchar orwchar_t,ArithmeticT is any cv-unqualified arithmetic type other thanchar,wchar_t,char8_t,char16_t, orchar32_t:
Character formatters | ||
template<> struct formatter<char,char>; | (1) | |
template<> struct formatter<char,wchar_t>; | (2) | |
template<> struct formatter<wchar_t,wchar_t>; | (3) | |
String formatters | ||
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) | |
Arithmetic formatters | ||
template<> struct formatter<ArithmeticT, CharT>; | (9) | |
Pointer formatters | ||
template<> struct formatter<std::nullptr_t, CharT>; | (10) | |
template<> struct formatter<void*, CharT>; | (11) | |
template<> struct formatter<constvoid*, CharT>; | (12) | |
Formatters for other pointers and pointers to members are disabled.
Specializations such asstd::formatter<wchar_t,char> andstd::formatter<constchar*,wchar_t> that would require encoding conversions are disabled.
The following specialization are still disabled in C++23 to avoid formatting somechar sequences as ranges ofwchar_t:
Adebug-enabled formatter specialization additionally provides a public non-static member functionconstexprvoid set_debug_format(); which modifies the state of the formatter object so that it will format the values asescaped and quoted, as if thetype of the format specifier parsed by the last call to Each formatter specialization for string or character type isdebug-enabled. | (since C++23) |
| This section is incomplete Reason: The standard format specification is moved to a separatepage. The section title is temporarily preserved for links to this section. This section will be removed after all those links are settled. |
formatting support forduration(class template specialization)[edit] | |
formatting support forsys_time(class template specialization)[edit] | |
formatting support forutc_time(class template specialization)[edit] | |
formatting support fortai_time(class template specialization)[edit] | |
formatting support forgps_time(class template specialization)[edit] | |
formatting support forfile_time(class template specialization)[edit] | |
formatting support forlocal_time(class template specialization)[edit] | |
formatting support forday(class template specialization)[edit] | |
formatting support formonth(class template specialization)[edit] | |
formatting support foryear(class template specialization)[edit] | |
formatting support forweekday(class template specialization)[edit] | |
formatting support forweekday_indexed(class template specialization)[edit] | |
formatting support forweekday_last(class template specialization)[edit] | |
formatting support formonth_day(class template specialization)[edit] | |
formatting support formonth_day_last(class template specialization)[edit] | |
formatting support formonth_weekday(class template specialization)[edit] | |
formatting support formonth_weekday_last(class template specialization)[edit] | |
formatting support foryear_month(class template specialization)[edit] | |
formatting support foryear_month_day(class template specialization)[edit] | |
formatting support foryear_month_day_last(class template specialization)[edit] | |
formatting support foryear_month_weekday(class template specialization)[edit] | |
formatting support foryear_month_weekday_last(class template specialization)[edit] | |
formatting support forhh_mm_ss(class template specialization)[edit] | |
formatting support forsys_info(class template specialization)[edit] | |
formatting support forlocal_info(class template specialization)[edit] | |
formatting support forzoned_time(class template specialization)[edit] | |
formatting support forbasic_stacktrace(class template specialization)[edit] | |
formatting support forstacktrace_entry(class template specialization)[edit] | |
formatting support forthread::id(class template specialization)[edit] | |
formatting support forvector<bool>::reference(class template specialization)[edit] | |
formatting support forpair andtuple(class template specialization)[edit] | |
(C++23) | formatting support for ranges (class template specialization)[edit] |
(C++23) | formatting support forstd::stack(class template specialization)[edit] |
(C++23) | formatting support forstd::queue(class template specialization)[edit] |
formatting support forstd::priority_queue(class template specialization)[edit] | |
formatting support forfilesystem::path(class template specialization)[edit] |
#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!='}')throwstd::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".
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 | somechar sequences were formattable as ranges ofwchar_t | disable specializations added |
(C++20)(C++20)(C++20) | formatting state, including all formatting arguments and the output iterator (class template)[edit] |
(C++23) | specifies that a type is formattable, that is, it specializesstd::formatter and provides member functionsparse andformat(concept)[edit] |
(C++23) | class template that helps implementingstd::formatter specializations for range types (class template)[edit] |