22 General utilities library [utilities]

22.14 Formatting [format]

22.14.6 Formatter [format.formatter]

22.14.6.1 Formatter requirements [formatter.requirements]

1
#
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.
2
#
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.
3
#
Given character type charT, output iterator type Out, and formatting argument type T, in Table 73 and Table 74:
  • (3.1)
    f is a value of type (possibly const) F,
  • (3.2)
    g is an lvalue of type F,
  • (3.3)
    u is an lvalue of type T,
  • (3.4)
    t is a value of a type convertible to (possibly const) T,
  • (3.5)
    PC is basic_format_parse_context<charT>,
  • (3.6)
    FC is basic_format_context<Out, charT>,
  • (3.7)
    pc is an lvalue of type PC, and
  • (3.8)
    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 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.