BasicFormatter is a type that abstracts formatting operations for a given formatting argument type and character type. Specializations ofstd::formatter are required to meet the requirements ofBasicFormatter.
ABasicFormatter is aFormatter if it is able to format both const and non-const arguments.
[edit]Requirements
A type satisfiesBasicFormatter if it is semiregular, meaning it satisfies:
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 |
| g | a value of typeFormatter |
| 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 |
|---|
| g.parse(parse_ctx) | ParseCtx::iterator | - In the range
[parse_ctx.begin(), parse_ctx.end()), parses theformat-spec for typeArg until the first unmatched character. - Throwsstd::format_error unless the whole range is parsed or the unmatched character is}.[note 1]
- Stores the parsed format specifiers ing and returns an end iterator of the parsed range.
|
| f.format(arg, fmt_ctx) | FmtCtx::iterator | - Formatsarg according to the specifiers stored inf, writes the output tofmt_ctx.out() and returns an end iterator of the output range.
- The output shall only depend on
- arg,
- 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.
|
- ↑This allows formatters to emit meaningful error messages.
[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 |
