From Jason Turner

[depr.conversions]

C++14 → C++17 14.8 KB 406 lines
Current Draft | LaTeX Source
Archived: C++14 | C++17
Markdown: C++14 | C++17
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmptgzypk3v/{from.md → to.md} +403 -0
tmp/tmptgzypk3v/{from.md → to.md} RENAMED
@@ -0,0 +1,403 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ## Deprecated convenience conversion interfaces <a id="depr.conversions">[[depr.conversions]]</a>
2
+
3
+ The header `<locale>` has the following additions:
4
+
5
+ ``` cpp
6
+ namespace std {
7
+ template <class Codecvt, class Elem = wchar_t,
8
+ class Wide_alloc = allocator<Elem>,
9
+ class Byte_alloc = allocator<char>>
10
+ class wstring_convert;
11
+
12
+ template <class Codecvt, class Elem = wchar_t,
13
+ class Tr = char_traits<Elem>>
14
+ class wbuffer_convert;
15
+ }
16
+ ```
17
+
18
+ ### Class template `wstring_convert` <a id="depr.conversions.string">[[depr.conversions.string]]</a>
19
+
20
+ Class template `wstring_convert` performs conversions between a wide
21
+ string and a byte string. It lets you specify a code conversion facet
22
+ (like class template `codecvt`) to perform the conversions, without
23
+ affecting any streams or locales.
24
+
25
+ [*Example 1*:
26
+
27
+ If you want to use the code conversion facet `codecvt_utf8` to output to
28
+ `cout` a UTF-8 multibyte sequence corresponding to a wide string, but
29
+ you don’t want to alter the locale for `cout`, you can write something
30
+ like:
31
+
32
+ ``` cpp
33
+ wstring_convert<std::codecvt_utf8<wchar_t>> myconv;
34
+ std::string mbstring = myconv.to_bytes(L"Hello\n");
35
+ std::cout << mbstring;
36
+ ```
37
+
38
+ — *end example*]
39
+
40
+ ``` cpp
41
+ namespace std {
42
+ template <class Codecvt, class Elem = wchar_t,
43
+ class Wide_alloc = allocator<Elem>,
44
+ class Byte_alloc = allocator<char>>
45
+ class wstring_convert {
46
+ public:
47
+ using byte_string = basic_string<char, char_traits<char>, Byte_alloc>;
48
+ using wide_string = basic_string<Elem, char_traits<Elem>, Wide_alloc>;
49
+ using state_type = typename Codecvt::state_type;
50
+ using int_type = typename wide_string::traits_type::int_type;
51
+
52
+ explicit wstring_convert(Codecvt* pcvt = new Codecvt);
53
+ wstring_convert(Codecvt* pcvt, state_type state);
54
+ explicit wstring_convert(const byte_string& byte_err,
55
+ const wide_string& wide_err = wide_string());
56
+ ~wstring_convert();
57
+
58
+ wstring_convert(const wstring_convert&) = delete;
59
+ wstring_convert& operator=(const wstring_convert&) = delete;
60
+
61
+ wide_string from_bytes(char byte);
62
+ wide_string from_bytes(const char* ptr);
63
+ wide_string from_bytes(const byte_string& str);
64
+ wide_string from_bytes(const char* first, const char* last);
65
+
66
+ byte_string to_bytes(Elem wchar);
67
+ byte_string to_bytes(const Elem* wptr);
68
+ byte_string to_bytes(const wide_string& wstr);
69
+ byte_string to_bytes(const Elem* first, const Elem* last);
70
+
71
+ size_t converted() const noexcept;
72
+ state_type state() const;
73
+
74
+ private:
75
+ byte_string byte_err_string; // exposition only
76
+ wide_string wide_err_string; // exposition only
77
+ Codecvt* cvtptr; // exposition only
78
+ state_type cvtstate; // exposition only
79
+ size_t cvtcount; // exposition only
80
+ };
81
+ }
82
+ ```
83
+
84
+ The class template describes an object that controls conversions between
85
+ wide string objects of class `basic_string<Elem, char_traits<Elem>,
86
+ Wide_alloc>` and byte string objects of class `basic_string<char,
87
+ char_traits<char>, Byte_alloc>`. The class template defines the types
88
+ `wide_string` and `byte_string` as synonyms for these two types.
89
+ Conversion between a sequence of `Elem` values (stored in a
90
+ `wide_string` object) and multibyte sequences (stored in a `byte_string`
91
+ object) is performed by an object of class `Codecvt`, which meets the
92
+ requirements of the standard code-conversion facet `codecvt<Elem,
93
+ char, mbstate_t>`.
94
+
95
+ An object of this class template stores:
96
+
97
+ - `byte_err_string` — a byte string to display on errors
98
+ - `wide_err_string` — a wide string to display on errors
99
+ - `cvtptr` — a pointer to the allocated conversion object (which is
100
+ freed when the `wstring_convert` object is destroyed)
101
+ - `cvtstate` — a conversion state object
102
+ - `cvtcount` — a conversion count
103
+
104
+ ``` cpp
105
+ using byte_string = basic_string<char, char_traits<char>, Byte_alloc>;
106
+ ```
107
+
108
+ The type shall be a synonym for
109
+ `basic_string<char, char_traits<char>, Byte_alloc>`.
110
+
111
+ ``` cpp
112
+ size_t converted() const noexcept;
113
+ ```
114
+
115
+ *Returns:* `cvtcount`.
116
+
117
+ ``` cpp
118
+ wide_string from_bytes(char byte);
119
+ wide_string from_bytes(const char* ptr);
120
+ wide_string from_bytes(const byte_string& str);
121
+ wide_string from_bytes(const char* first, const char* last);
122
+ ```
123
+
124
+ *Effects:* The first member function shall convert the single-element
125
+ sequence `byte` to a wide string. The second member function shall
126
+ convert the null-terminated sequence beginning at `ptr` to a wide
127
+ string. The third member function shall convert the sequence stored in
128
+ `str` to a wide string. The fourth member function shall convert the
129
+ sequence defined by the range \[`first`, `last`) to a wide string.
130
+
131
+ In all cases:
132
+
133
+ - If the `cvtstate` object was not constructed with an explicit value,
134
+ it shall be set to its default value (the initial conversion state)
135
+ before the conversion begins. Otherwise it shall be left unchanged.
136
+ - The number of input elements successfully converted shall be stored in
137
+ `cvtcount`.
138
+
139
+ *Returns:* If no conversion error occurs, the member function shall
140
+ return the converted wide string. Otherwise, if the object was
141
+ constructed with a wide-error string, the member function shall return
142
+ the wide-error string. Otherwise, the member function throws an object
143
+ of class `range_error`.
144
+
145
+ ``` cpp
146
+ using int_type = typename wide_string::traits_type::int_type;
147
+ ```
148
+
149
+ The type shall be a synonym for `wide_string::traits_type::int_type`.
150
+
151
+ ``` cpp
152
+ state_type state() const;
153
+ ```
154
+
155
+ returns `cvtstate`.
156
+
157
+ ``` cpp
158
+ using state_type = typename Codecvt::state_type;
159
+ ```
160
+
161
+ The type shall be a synonym for `Codecvt::state_type`.
162
+
163
+ ``` cpp
164
+ byte_string to_bytes(Elem wchar);
165
+ byte_string to_bytes(const Elem* wptr);
166
+ byte_string to_bytes(const wide_string& wstr);
167
+ byte_string to_bytes(const Elem* first, const Elem* last);
168
+ ```
169
+
170
+ *Effects:* The first member function shall convert the single-element
171
+ sequence `wchar` to a byte string. The second member function shall
172
+ convert the null-terminated sequence beginning at `wptr` to a byte
173
+ string. The third member function shall convert the sequence stored in
174
+ `wstr` to a byte string. The fourth member function shall convert the
175
+ sequence defined by the range \[`first`, `last`) to a byte string.
176
+
177
+ In all cases:
178
+
179
+ - If the `cvtstate` object was not constructed with an explicit value,
180
+ it shall be set to its default value (the initial conversion state)
181
+ before the conversion begins. Otherwise it shall be left unchanged.
182
+ - The number of input elements successfully converted shall be stored in
183
+ `cvtcount`.
184
+
185
+ *Returns:* If no conversion error occurs, the member function shall
186
+ return the converted byte string. Otherwise, if the object was
187
+ constructed with a byte-error string, the member function shall return
188
+ the byte-error string. Otherwise, the member function shall throw an
189
+ object of class `range_error`.
190
+
191
+ ``` cpp
192
+ using wide_string = basic_string<Elem, char_traits<Elem>, Wide_alloc>;
193
+ ```
194
+
195
+ The type shall be a synonym for
196
+ `basic_string<Elem, char_traits<Elem>, Wide_alloc>`.
197
+
198
+ ``` cpp
199
+ explicit wstring_convert(Codecvt* pcvt = new Codecvt);
200
+ wstring_convert(Codecvt* pcvt, state_type state);
201
+ explicit wstring_convert(const byte_string& byte_err,
202
+ const wide_string& wide_err = wide_string());
203
+ ```
204
+
205
+ *Requires:* For the first and second constructors, `pcvt != nullptr`.
206
+
207
+ *Effects:* The first constructor shall store `pcvt` in `cvtptr` and
208
+ default values in `cvtstate`, `byte_err_string`, and `wide_err_string`.
209
+ The second constructor shall store `pcvt` in `cvtptr`, `state` in
210
+ `cvtstate`, and default values in `byte_err_string` and
211
+ `wide_err_string`; moreover the stored state shall be retained between
212
+ calls to `from_bytes` and `to_bytes`. The third constructor shall store
213
+ `new Codecvt` in `cvtptr`, `state_type()` in `cvtstate`, `byte_err` in
214
+ `byte_err_string`, and `wide_err` in `wide_err_string`.
215
+
216
+ ``` cpp
217
+ ~wstring_convert();
218
+ ```
219
+
220
+ *Effects:* The destructor shall delete `cvtptr`.
221
+
222
+ ### Class template `wbuffer_convert` <a id="depr.conversions.buffer">[[depr.conversions.buffer]]</a>
223
+
224
+ Class template `wbuffer_convert` looks like a wide stream buffer, but
225
+ performs all its I/O through an underlying byte stream buffer that you
226
+ specify when you construct it. Like class template `wstring_convert`, it
227
+ lets you specify a code conversion facet to perform the conversions,
228
+ without affecting any streams or locales.
229
+
230
+ ``` cpp
231
+ namespace std {
232
+ template <class Codecvt, class Elem = wchar_t, class Tr = char_traits<Elem>>
233
+ class wbuffer_convert : public basic_streambuf<Elem, Tr> {
234
+ public:
235
+ using state_type = typename Codecvt::state_type;
236
+
237
+ explicit wbuffer_convert(streambuf* bytebuf = 0,
238
+ Codecvt* pcvt = new Codecvt,
239
+ state_type state = state_type());
240
+
241
+ ~wbuffer_convert();
242
+
243
+ wbuffer_convert(const wbuffer_convert&) = delete;
244
+ wbuffer_convert& operator=(const wbuffer_convert&) = delete;
245
+
246
+ streambuf* rdbuf() const;
247
+ streambuf* rdbuf(streambuf* bytebuf);
248
+
249
+ state_type state() const;
250
+
251
+ private:
252
+ streambuf* bufptr; // exposition only
253
+ Codecvt* cvtptr; // exposition only
254
+ state_type cvtstate; // exposition only
255
+ };
256
+ }
257
+ ```
258
+
259
+ The class template describes a stream buffer that controls the
260
+ transmission of elements of type `Elem`, whose character traits are
261
+ described by the class `Tr`, to and from a byte stream buffer of type
262
+ `streambuf`. Conversion between a sequence of `Elem` values and
263
+ multibyte sequences is performed by an object of class `Codecvt`, which
264
+ shall meet the requirements of the standard code-conversion facet
265
+ `codecvt<Elem, char, mbstate_t>`.
266
+
267
+ An object of this class template stores:
268
+
269
+ - `bufptr` — a pointer to its underlying byte stream buffer
270
+ - `cvtptr` — a pointer to the allocated conversion object (which is
271
+ freed when the `wbuffer_convert` object is destroyed)
272
+ - `cvtstate` — a conversion state object
273
+
274
+ ``` cpp
275
+ state_type state() const;
276
+ ```
277
+
278
+ *Returns:* `cvtstate`.
279
+
280
+ ``` cpp
281
+ streambuf* rdbuf() const;
282
+ ```
283
+
284
+ *Returns:* `bufptr`.
285
+
286
+ ``` cpp
287
+ streambuf* rdbuf(streambuf* bytebuf);
288
+ ```
289
+
290
+ *Effects:* Stores `bytebuf` in `bufptr`.
291
+
292
+ *Returns:* The previous value of `bufptr`.
293
+
294
+ ``` cpp
295
+ using state_type = typename Codecvt::state_type;
296
+ ```
297
+
298
+ The type shall be a synonym for `Codecvt::state_type`.
299
+
300
+ ``` cpp
301
+ explicit wbuffer_convert(
302
+ streambuf* bytebuf = 0,
303
+ Codecvt* pcvt = new Codecvt,
304
+ state_type state = state_type());
305
+ ```
306
+
307
+ *Requires:* `pcvt != nullptr`.
308
+
309
+ *Effects:* The constructor constructs a stream buffer object,
310
+ initializes `bufptr` to `bytebuf`, initializes `cvtptr` to `pcvt`, and
311
+ initializes `cvtstate` to `state`.
312
+
313
+ ``` cpp
314
+ ~wbuffer_convert();
315
+ ```
316
+
317
+ *Effects:* The destructor shall delete `cvtptr`.
318
+
319
+ <!-- Link reference definitions -->
320
+ [basic.align]: basic.md#basic.align
321
+ [basic.scope.namespace]: basic.md#basic.scope.namespace
322
+ [basic.types]: basic.md#basic.types
323
+ [class.copy]: special.md#class.copy
324
+ [class.dtor]: special.md#class.dtor
325
+ [cmath.syn]: numerics.md#cmath.syn
326
+ [complex.syn]: numerics.md#complex.syn
327
+ [containers]: containers.md#containers
328
+ [cstddef.syn]: language.md#cstddef.syn
329
+ [dcl.attr.deprecated]: dcl.md#dcl.attr.deprecated
330
+ [dcl.fct.def]: dcl.md#dcl.fct.def
331
+ [default.allocator]: utilities.md#default.allocator
332
+ [depr]: #depr
333
+ [depr.c.headers]: #depr.c.headers
334
+ [depr.ccomplex.syn]: #depr.ccomplex.syn
335
+ [depr.codecvt.syn]: #depr.codecvt.syn
336
+ [depr.conversions]: #depr.conversions
337
+ [depr.conversions.buffer]: #depr.conversions.buffer
338
+ [depr.conversions.string]: #depr.conversions.string
339
+ [depr.cpp.headers]: #depr.cpp.headers
340
+ [depr.cstdalign.syn]: #depr.cstdalign.syn
341
+ [depr.cstdbool.syn]: #depr.cstdbool.syn
342
+ [depr.ctgmath.syn]: #depr.ctgmath.syn
343
+ [depr.default.allocator]: #depr.default.allocator
344
+ [depr.except.spec]: #depr.except.spec
345
+ [depr.func.adaptor.binding]: #depr.func.adaptor.binding
346
+ [depr.func.adaptor.typedefs]: #depr.func.adaptor.typedefs
347
+ [depr.impldec]: #depr.impldec
348
+ [depr.istrstream]: #depr.istrstream
349
+ [depr.istrstream.cons]: #depr.istrstream.cons
350
+ [depr.istrstream.members]: #depr.istrstream.members
351
+ [depr.iterator.basic]: #depr.iterator.basic
352
+ [depr.iterator.primitives]: #depr.iterator.primitives
353
+ [depr.locale.stdcvt]: #depr.locale.stdcvt
354
+ [depr.locale.stdcvt.req]: #depr.locale.stdcvt.req
355
+ [depr.meta.types]: #depr.meta.types
356
+ [depr.negators]: #depr.negators
357
+ [depr.ostrstream]: #depr.ostrstream
358
+ [depr.ostrstream.cons]: #depr.ostrstream.cons
359
+ [depr.ostrstream.members]: #depr.ostrstream.members
360
+ [depr.static_constexpr]: #depr.static_constexpr
361
+ [depr.storage.iterator]: #depr.storage.iterator
362
+ [depr.str.strstreams]: #depr.str.strstreams
363
+ [depr.strstream]: #depr.strstream
364
+ [depr.strstream.cons]: #depr.strstream.cons
365
+ [depr.strstream.dest]: #depr.strstream.dest
366
+ [depr.strstream.oper]: #depr.strstream.oper
367
+ [depr.strstreambuf]: #depr.strstreambuf
368
+ [depr.strstreambuf.cons]: #depr.strstreambuf.cons
369
+ [depr.strstreambuf.members]: #depr.strstreambuf.members
370
+ [depr.strstreambuf.virtuals]: #depr.strstreambuf.virtuals
371
+ [depr.temporary.buffer]: #depr.temporary.buffer
372
+ [depr.uncaught]: #depr.uncaught
373
+ [depr.util.smartptr.shared.obs]: #depr.util.smartptr.shared.obs
374
+ [depr.weak.result_type]: #depr.weak.result_type
375
+ [expr.unary.op]: expr.md#expr.unary.op
376
+ [func.bind.bind]: utilities.md#func.bind.bind
377
+ [func.def]: utilities.md#func.def
378
+ [function.objects]: utilities.md#function.objects
379
+ [meta.rqmts]: utilities.md#meta.rqmts
380
+ [namespace.udecl]: dcl.md#namespace.udecl
381
+ [new.delete]: language.md#new.delete
382
+ [output.iterators]: iterators.md#output.iterators
383
+ [sf.cmath]: numerics.md#sf.cmath
384
+ [support.types.byteops]: language.md#support.types.byteops
385
+ [tab:future.c.headers]: #tab:future.c.headers
386
+ [tab:future.newoff.values]: #tab:future.newoff.values
387
+ [tab:future.seekoff.positioning]: #tab:future.seekoff.positioning
388
+ [tab:future.strstreambuf.effects]: #tab:future.strstreambuf.effects
389
+ [tab:future.strstreambuf1.effects]: #tab:future.strstreambuf1.effects
390
+ [tab:future.strstreambuf2.effects]: #tab:future.strstreambuf2.effects
391
+ [temp.deduct]: temp.md#temp.deduct
392
+ [unord.hash]: utilities.md#unord.hash
393
+ [util.smartptr.shared]: utilities.md#util.smartptr.shared
394
+
395
+ [^1]: The function signature `strlen(const char*)` is declared in
396
+ `<cstring>` ([[cstring.syn]]). The macro `INT_MAX` is defined in
397
+ `<climits>` ([[climits.syn]]).
398
+
399
+ [^2]: An implementation should consider `alsize` in making this
400
+ decision.
401
+
402
+ [^3]: The function signature `strlen(const char*)` is declared in
403
+ `<cstring>` ([[cstring.syn]]).