Formatter is a type that abstracts formatting operations for a given formatting argument type and character type. Specializations ofstd::formatter provided by the standard library are required to meet the requirements ofFormatter except as noted otherwise.
AFormatter is able to format both const and non-const arguments, typically by providing aformat member function that takes a const reference.
[edit]Requirements
A type satisfiesFormatter if it satisfiesBasicFormatter and given the following types and values, the expressions shown in the table below are valid and have the indicated semantics:
| Type | Definition |
CharT | a character type |
Arg | a formatting argument type |
Formatter | aFormatter type for typesArg andCharT |
OutputIt | aLegacyOutputIterator type |
ParseCtx | std::basic_format_parse_context<CharT> |
FmtCtx | std::basic_format_context<OutputIt, CharT> |
| Value | Definition |
| f | a value of type (possibly const-qualified)Formatter |
| arg | an lvalue of typeArg |
| t | a value of type convertible to (possibly const-qualified)Arg |
| parse_ctx | an lvalue of typeParseCtx satisfying all following conditions:- parse_ctx.begin() points to the beginning of theformat-spec of the replacement field being formatted in theformat string.
- Ifformat-spec is not present or empty, then eitherparse_ctx.begin()== parse_ctx.end() or*parse_ctx.begin()=='}'.
|
| fmt_ctx | an lvalue of typeFmtCtx |
| Expression | Return type | Semantics |
|---|
| f.format(t, fmt_ctx) | FmtCtx::iterator | - Formatst according to the specifiers stored inf, writes the output tofmt_ctx.out() and returns an end iterator of the output range.
- The output can only depend on
- t,
- fmt_ctx.locale(),
- the range
[parse_ctx.begin(), parse_ctx.end()) from the last call tof.parse(parse_ctx), and - fmt_ctx.arg(n) for any valuen of typestd::size_t.
|
| f.format(arg, fmt_ctx) | FmtCtx::iterator | As above, but does not modifyarg. |
[edit]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 3892 | C++20 | the value ofpc.begin() was unclear ifformat-spec is not present | made clear |
