20 General utilities library [utilities]

20.20 Formatting [format]

20.20.6 Formatter [format.formatter]

20.20.6.1 Formatter requirements [formatter.requirements]

A type F meets the BasicFormatter requirements if:
A type F meets the Formatter requirements if it meets the BasicFormatter requirements and the expressions shown in Table 71 are valid and have the indicated semantics.
Given character type charT, output iterator type Out, and formatting argument type T, in Table 70 and Table 71:
  • f is a value 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 empty then either pc.begin() == pc.end() or *pc.begin() == '}'.
Table 70: BasicFormatter requirements [tab:formatter.basic]
Expression
Return type
Requirement
f.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 71: 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.