22 General utilities library [utilities]

22.14 Formatting [format]

22.14.6 Formatter [format.formatter]

22.14.6.1 Formatter requirements [formatter.requirements]

A type F meets the BasicFormatter requirements if it meets the requirements, and the expressions shown in Table 73 are valid and have the indicated semantics.
A type F meets the Formatter requirements if it meets the BasicFormatter requirements and the expressions shown in Table 74 are valid and have the indicated semantics.
Given character type charT, output iterator type Out, and formatting argument type T, in Table 73 and Table 74:
  • f is a value of type (possibly const) F,
  • g is an lvalue of type F,
  • u is an lvalue of type T,
  • t is a value of a type convertible to (possibly const) T,
  • PC is basic_format_parse_context<charT>,
  • FC is basic_format_context<Out, charT>,
  • pc is an lvalue of type PC, and
  • fc is an lvalue of type FC.
pc.begin() points to the beginning of the format-spec ([format.string]) of the replacement field being formatted in the format string.
If format-spec is not present or empty then either pc.begin() == pc.end() or *pc.begin() == '}'.
Table 73: BasicFormatter requirements [tab:formatter.basic]
Expression
Return type
Requirement
g.parse(pc)
PC​::​iterator
Parses format-spec ([format.string]) for type T in the range [pc.begin(), pc.end()) until the first unmatched character.
Throws format_error unless the whole range is parsed or the unmatched character is }.
[Note 1: 
This allows formatters to emit meaningful error messages.
— end note]
Stores the parsed format specifiers in *this and returns an iterator past the end of the parsed range.
f.format(u, fc)
FC​::​iterator
Formats u according to the specifiers stored in *this, writes the output to fc.out(), and returns an iterator past the end of the output range.
The output shall only depend on u, fc.locale(), fc.arg(n) for any value n of type size_t, and the range [pc.begin(), pc.end()) from the last call to f.parse(pc).
Table 74: Formatter requirements [tab:formatter]
Expression
Return type
Requirement
f.format(t, fc)
FC​::​iterator
Formats t according to the specifiers stored in *this, writes the output to fc.out(), and returns an iterator past the end of the output range.
The output shall only depend on t, fc.locale(), fc.arg(n) for any value n of type size_t, and the range [pc.begin(), pc.end()) from the last call to f.parse(pc).
f.format(u, fc)
FC​::​iterator
As above, but does not modify u.