From Jason Turner

[format.context]

C++17 → C++20 3.3 KB 111 lines
Current Draft | LaTeX Source
Archived: C++17 | C++20
Markdown: C++17 | C++20
Explore in Adventure Game
C++ Weekly: Ep 495

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpxaaoze7i/{from.md → to.md} +108 -0
tmp/tmpxaaoze7i/{from.md → to.md} RENAMED
@@ -0,0 +1,108 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #### Class template `basic_format_context` <a id="format.context">[[format.context]]</a>
2
+
3
+ ``` cpp
4
+ namespace std {
5
+ template<class Out, class charT>
6
+ class basic_format_context {
7
+ basic_format_args<basic_format_context> args_; // exposition only
8
+ Out out_; // exposition only
9
+
10
+ public:
11
+ using iterator = Out;
12
+ using char_type = charT;
13
+ template<class T> using formatter_type = formatter<T, charT>;
14
+
15
+ basic_format_arg<basic_format_context> arg(size_t id) const;
16
+ std::locale locale();
17
+
18
+ iterator out();
19
+ void advance_to(iterator it);
20
+ };
21
+ }
22
+ ```
23
+
24
+ An instance of `basic_format_context` holds formatting state consisting
25
+ of the formatting arguments and the output iterator.
26
+
27
+ `Out` shall model `output_iterator<const charT&>`.
28
+
29
+ `format_context` is an alias for a specialization of
30
+ `basic_format_context` with an output iterator that appends to `string`,
31
+ such as `back_insert_iterator<string>`. Similarly, `wformat_context` is
32
+ an alias for a specialization of `basic_format_context` with an output
33
+ iterator that appends to `wstring`.
34
+
35
+ [*Note 1*: For a given type `charT`, implementations are encouraged to
36
+ provide a single instantiation of `basic_format_context` for appending
37
+ to `basic_string<charT>`, `vector<charT>`, or any other container with
38
+ contiguous storage by wrapping those in temporary objects with a uniform
39
+ interface (such as a `span<charT>`) and polymorphic
40
+ reallocation. — *end note*]
41
+
42
+ ``` cpp
43
+ basic_format_arg<basic_format_context> arg(size_t id) const;
44
+ ```
45
+
46
+ *Returns:* `args_.get(id)`.
47
+
48
+ ``` cpp
49
+ std::locale locale();
50
+ ```
51
+
52
+ *Returns:* The locale passed to the formatting function if the latter
53
+ takes one, and `std::locale()` otherwise.
54
+
55
+ ``` cpp
56
+ iterator out();
57
+ ```
58
+
59
+ *Returns:* `out_`.
60
+
61
+ ``` cpp
62
+ void advance_to(iterator it);
63
+ ```
64
+
65
+ *Effects:* Equivalent to: `out_ = it;`
66
+
67
+ [*Example 1*:
68
+
69
+ ``` cpp
70
+ struct S { int value; };
71
+
72
+ template<> struct std::formatter<S> {
73
+ size_t width_arg_id = 0;
74
+
75
+ // Parses a width argument id in the format { digit }.
76
+ constexpr auto parse(format_parse_context& ctx) {
77
+ auto iter = ctx.begin();
78
+ auto get_char = [&]() { return iter != ctx.end() ? *iter : 0; };
79
+ if (get_char() != '{')
80
+ return iter;
81
+ ++iter;
82
+ char c = get_char();
83
+ if (!isdigit(c) || (++iter, get_char()) != '}')
84
+ throw format_error("invalid format");
85
+ width_arg_id = c - '0';
86
+ ctx.check_arg_id(width_arg_id);
87
+ return ++iter;
88
+ }
89
+
90
+ // Formats an S with width given by the argument width_arg_id.
91
+ auto format(S s, format_context& ctx) {
92
+ int width = visit_format_arg([](auto value) -> int {
93
+ if constexpr (!is_integral_v<decltype(value)>)
94
+ throw format_error("width is not integral");
95
+ else if (value < 0 || value > numeric_limits<int>::max())
96
+ throw format_error("invalid width");
97
+ else
98
+ return value;
99
+ }, ctx.arg(width_arg_id));
100
+ return format_to(ctx.out(), "{0:x<{1}}", s.value, width);
101
+ }
102
+ };
103
+
104
+ std::string s = std::format("{0:{1}}", S{42}, 10); // value of s is "xxxxxxxx42"
105
+ ```
106
+
107
+ — *end example*]
108
+