From Jason Turner

[charconv]

C++17 → C++20 10.3 KB 245 lines
Current Draft | LaTeX Source
Archived: C++17 | C++20
Markdown: C++17 | C++20
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpveebuo0a/{from.md → to.md} +242 -0
tmp/tmpveebuo0a/{from.md → to.md} RENAMED
@@ -0,0 +1,242 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ## Primitive numeric conversions <a id="charconv">[[charconv]]</a>
2
+
3
+ ### Header `<charconv>` synopsis <a id="charconv.syn">[[charconv.syn]]</a>
4
+
5
+ ``` cpp
6
+ %
7
+ %
8
+ {chars_format{chars_format{chars_format{chars_formatnamespace std {
9
+ // floating-point format for primitive numerical conversion
10
+ enum class chars_format {
11
+ scientific = unspecified,
12
+ fixed = unspecified,
13
+ hex = unspecified,
14
+ general = fixed | scientific
15
+ };
16
+ %
17
+ %
18
+ {to_chars_result{to_chars_result}
19
+
20
+ // [charconv.to.chars], primitive numerical output conversion
21
+ struct to_chars_result {
22
+ char* ptr;
23
+ errc ec;
24
+ friend bool operator==(const to_chars_result&, const to_chars_result&) = default;
25
+ };
26
+
27
+ to_chars_result to_chars(char* first, char* last, see below value, int base = 10);
28
+ to_chars_result to_chars(char* first, char* last, bool value, int base = 10) = delete;
29
+
30
+ to_chars_result to_chars(char* first, char* last, float value);
31
+ to_chars_result to_chars(char* first, char* last, double value);
32
+ to_chars_result to_chars(char* first, char* last, long double value);
33
+
34
+ to_chars_result to_chars(char* first, char* last, float value, chars_format fmt);
35
+ to_chars_result to_chars(char* first, char* last, double value, chars_format fmt);
36
+ to_chars_result to_chars(char* first, char* last, long double value, chars_format fmt);
37
+
38
+ to_chars_result to_chars(char* first, char* last, float value,
39
+ chars_format fmt, int precision);
40
+ to_chars_result to_chars(char* first, char* last, double value,
41
+ chars_format fmt, int precision);
42
+ to_chars_result to_chars(char* first, char* last, long double value,
43
+ chars_format fmt, int precision);
44
+ %
45
+ %
46
+ {from_chars_result{from_chars_result}
47
+
48
+ // [charconv.from.chars], primitive numerical input conversion
49
+ struct from_chars_result {
50
+ const char* ptr;
51
+ errc ec;
52
+ friend bool operator==(const from_chars_result&, const from_chars_result&) = default;
53
+ };
54
+
55
+ from_chars_result from_chars(const char* first, const char* last,
56
+ see below& value, int base = 10);
57
+
58
+ from_chars_result from_chars(const char* first, const char* last, float& value,
59
+ chars_format fmt = chars_format::general);
60
+ from_chars_result from_chars(const char* first, const char* last, double& value,
61
+ chars_format fmt = chars_format::general);
62
+ from_chars_result from_chars(const char* first, const char* last, long double& value,
63
+ chars_format fmt = chars_format::general);
64
+ }
65
+ ```
66
+
67
+ The type `chars_format` is a bitmask type [[bitmask.types]] with
68
+ elements `scientific`, `fixed`, and `hex`.
69
+
70
+ The types `to_chars_result` and `from_chars_result` have the data
71
+ members and special members specified above. They have no base classes
72
+ or members other than those specified.
73
+
74
+ ### Primitive numeric output conversion <a id="charconv.to.chars">[[charconv.to.chars]]</a>
75
+
76
+ All functions named `to_chars` convert `value` into a character string
77
+ by successively filling the range \[`first`, `last`), where \[`first`,
78
+ `last`) is required to be a valid range. If the member `ec` of the
79
+ return value is such that the value is equal to the value of a
80
+ value-initialized `errc`, the conversion was successful and the member
81
+ `ptr` is the one-past-the-end pointer of the characters written.
82
+ Otherwise, the member `ec` has the value `errc::value_too_large`, the
83
+ member `ptr` has the value `last`, and the contents of the range
84
+ \[`first`, `last`) are unspecified.
85
+
86
+ The functions that take a floating-point `value` but not a `precision`
87
+ parameter ensure that the string representation consists of the smallest
88
+ number of characters such that there is at least one digit before the
89
+ radix point (if present) and parsing the representation using the
90
+ corresponding `from_chars` function recovers `value` exactly.
91
+
92
+ [*Note 1*: This guarantee applies only if `to_chars` and `from_chars`
93
+ are executed on the same implementation. — *end note*]
94
+
95
+ If there are several such representations, the representation with the
96
+ smallest difference from the floating-point argument value is chosen,
97
+ resolving any remaining ties using rounding according to
98
+ `round_to_nearest` [[round.style]].
99
+
100
+ The functions taking a `chars_format` parameter determine the conversion
101
+ specifier for `printf` as follows: The conversion specifier is `f` if
102
+ `fmt` is `chars_format::fixed`, `e` if `fmt` is
103
+ `chars_format::scientific`, `a` (without leading `"0x"` in the result)
104
+ if `fmt` is `chars_format::hex`, and `g` if `fmt` is
105
+ `chars_format::general`.
106
+
107
+ ``` cpp
108
+ to_chars_result to_chars(char* first, char* last, see below value, int base = 10);
109
+ ```
110
+
111
+ *Preconditions:* `base` has a value between 2 and 36 (inclusive).
112
+
113
+ *Effects:* The value of `value` is converted to a string of digits in
114
+ the given base (with no redundant leading zeroes). Digits in the range
115
+ 10..35 (inclusive) are represented as lowercase characters `a`..`z`. If
116
+ `value` is less than zero, the representation starts with `’-’`.
117
+
118
+ *Throws:* Nothing.
119
+
120
+ *Remarks:* The implementation shall provide overloads for all signed and
121
+ unsigned integer types and `char` as the type of the parameter `value`.
122
+
123
+ ``` cpp
124
+ to_chars_result to_chars(char* first, char* last, float value);
125
+ to_chars_result to_chars(char* first, char* last, double value);
126
+ to_chars_result to_chars(char* first, char* last, long double value);
127
+ ```
128
+
129
+ *Effects:* `value` is converted to a string in the style of `printf` in
130
+ the `"C"` locale. The conversion specifier is `f` or `e`, chosen
131
+ according to the requirement for a shortest representation (see above);
132
+ a tie is resolved in favor of `f`.
133
+
134
+ *Throws:* Nothing.
135
+
136
+ ``` cpp
137
+ to_chars_result to_chars(char* first, char* last, float value, chars_format fmt);
138
+ to_chars_result to_chars(char* first, char* last, double value, chars_format fmt);
139
+ to_chars_result to_chars(char* first, char* last, long double value, chars_format fmt);
140
+ ```
141
+
142
+ *Preconditions:* `fmt` has the value of one of the enumerators of
143
+ `chars_format`.
144
+
145
+ *Effects:* `value` is converted to a string in the style of `printf` in
146
+ the `"C"` locale.
147
+
148
+ *Throws:* Nothing.
149
+
150
+ ``` cpp
151
+ to_chars_result to_chars(char* first, char* last, float value,
152
+ chars_format fmt, int precision);
153
+ to_chars_result to_chars(char* first, char* last, double value,
154
+ chars_format fmt, int precision);
155
+ to_chars_result to_chars(char* first, char* last, long double value,
156
+ chars_format fmt, int precision);
157
+ ```
158
+
159
+ *Preconditions:* `fmt` has the value of one of the enumerators of
160
+ `chars_format`.
161
+
162
+ *Effects:* `value` is converted to a string in the style of `printf` in
163
+ the `"C"` locale with the given precision.
164
+
165
+ *Throws:* Nothing.
166
+
167
+ See also: ISO C 7.21.6.1
168
+
169
+ ### Primitive numeric input conversion <a id="charconv.from.chars">[[charconv.from.chars]]</a>
170
+
171
+ All functions named `from_chars` analyze the string \[`first`, `last`)
172
+ for a pattern, where \[`first`, `last`) is required to be a valid range.
173
+ If no characters match the pattern, `value` is unmodified, the member
174
+ `ptr` of the return value is `first` and the member `ec` is equal to
175
+ `errc::invalid_argument`.
176
+
177
+ [*Note 1*: If the pattern allows for an optional sign, but the string
178
+ has no digit characters following the sign, no characters match the
179
+ pattern. — *end note*]
180
+
181
+ Otherwise, the characters matching the pattern are interpreted as a
182
+ representation of a value of the type of `value`. The member `ptr` of
183
+ the return value points to the first character not matching the pattern,
184
+ or has the value `last` if all characters match. If the parsed value is
185
+ not in the range representable by the type of `value`, `value` is
186
+ unmodified and the member `ec` of the return value is equal to
187
+ `errc::result_out_of_range`. Otherwise, `value` is set to the parsed
188
+ value, after rounding according to `round_to_nearest` [[round.style]],
189
+ and the member `ec` is value-initialized.
190
+
191
+ ``` cpp
192
+ from_chars_result from_chars(const char* first, const char* last,
193
+ see below& value, int base = 10);
194
+ ```
195
+
196
+ *Preconditions:* `base` has a value between 2 and 36 (inclusive).
197
+
198
+ *Effects:* The pattern is the expected form of the subject sequence in
199
+ the `"C"` locale for the given nonzero base, as described for `strtol`,
200
+ except that no `"0x"` or `"0X"` prefix shall appear if the value of
201
+ `base` is 16, and except that `’-’` is the only sign that may appear,
202
+ and only if `value` has a signed type.
203
+
204
+ *Throws:* Nothing.
205
+
206
+ *Remarks:* The implementation shall provide overloads for all signed and
207
+ unsigned integer types and `char` as the referenced type of the
208
+ parameter `value`.
209
+
210
+ ``` cpp
211
+ from_chars_result from_chars(const char* first, const char* last, float& value,
212
+ chars_format fmt = chars_format::general);
213
+ from_chars_result from_chars(const char* first, const char* last, double& value,
214
+ chars_format fmt = chars_format::general);
215
+ from_chars_result from_chars(const char* first, const char* last, long double& value,
216
+ chars_format fmt = chars_format::general);
217
+ ```
218
+
219
+ *Preconditions:* `fmt` has the value of one of the enumerators of
220
+ `chars_format`.
221
+
222
+ *Effects:* The pattern is the expected form of the subject sequence in
223
+ the `"C"` locale, as described for `strtod`, except that
224
+
225
+ - the sign `’+’` may only appear in the exponent part;
226
+ - if `fmt` has `chars_format::scientific` set but not
227
+ `chars_format::fixed`, the otherwise optional exponent part shall
228
+ appear;
229
+ - if `fmt` has `chars_format::fixed` set but not
230
+ `chars_format::scientific`, the optional exponent part shall not
231
+ appear; and
232
+ - if `fmt` is `chars_format::hex`, the prefix `"0x"` or `"0X"` is
233
+ assumed. \[*Example 1*: The string `0x123` is parsed to have the value
234
+ `0` with remaining characters `x123`. — *end example*]
235
+
236
+ In any case, the resulting `value` is one of at most two floating-point
237
+ values closest to the value of the string matching the pattern.
238
+
239
+ *Throws:* Nothing.
240
+
241
+ See also: ISO C 7.22.1.3, 7.22.1.4
242
+