From Jason Turner

[locale.codecvt]

C++14 → C++17 14.6 KB 155 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/tmp3dx69xnc/{from.md → to.md} +81 -69
tmp/tmp3dx69xnc/{from.md → to.md} RENAMED
@@ -8,46 +8,54 @@ namespace std {
8
  };
9
 
10
  template <class internT, class externT, class stateT>
11
  class codecvt : public locale::facet, public codecvt_base {
12
  public:
13
- typedef internT intern_type;
14
- typedef externT extern_type;
15
- typedef stateT state_type;
16
 
17
  explicit codecvt(size_t refs = 0);
18
 
19
- result out(stateT& state,
 
20
  const internT* from, const internT* from_end, const internT*& from_next,
21
  externT* to, externT* to_end, externT*& to_next) const;
22
- result unshift(stateT& state,
 
 
23
  externT* to, externT* to_end, externT*& to_next) const;
24
- result in(stateT& state,
 
 
25
  const externT* from, const externT* from_end, const externT*& from_next,
26
  internT* to, internT* to_end, internT*& to_next) const;
 
27
  int encoding() const noexcept;
28
  bool always_noconv() const noexcept;
29
- int length(stateT&, const externT* from, const externT* end,
30
- size_t max) const;
31
  int max_length() const noexcept;
32
 
33
  static locale::id id;
34
 
35
  protected:
36
  ~codecvt();
37
- virtual result do_out(stateT& state,
 
38
  const internT* from, const internT* from_end, const internT*& from_next,
39
  externT* to, externT* to_end, externT*& to_next) const;
40
- virtual result do_in(stateT& state,
 
41
  const externT* from, const externT* from_end, const externT*& from_next,
42
  internT* to, internT* to_end, internT*& to_next) const;
43
- virtual result do_unshift(stateT& state,
 
44
  externT* to, externT* to_end, externT*& to_next) const;
 
45
  virtual int do_encoding() const noexcept;
46
  virtual bool do_always_noconv() const noexcept;
47
- virtual int do_length(stateT&, const externT* from,
48
- const externT* end, size_t max) const;
49
  virtual int do_max_length() const noexcept;
50
  };
51
  }
52
  ```
53
 
@@ -61,103 +69,105 @@ mapped between.
61
 
62
  The specializations required in Table 
63
  [[tab:localization.category.facets]] ([[locale.category]]) convert the
64
  implementation-defined native character set.
65
  `codecvt<char, char, mbstate_t>` implements a degenerate conversion; it
66
- does not convert at all. The specialization `codecvt<char16_t,`
67
- `char, mbstate_t>` converts between the UTF-16 and UTF-8 encoding forms,
68
- and the specialization `codecvt` `<char32_t, char, mbstate_t>` converts
69
- between the UTF-32 and UTF-8 encoding forms.
70
- `codecvt<wchar_t,char,mbstate_t>` converts between the native character
71
- sets for narrow and wide characters. Specializations on `mbstate_t`
72
- perform conversion between encodings known to the library implementer.
73
- Other encodings can be converted by specializing on a user-defined
74
- `stateT` type. Objects of type `stateT` can contain any state that is
75
- useful to communicate to or from the specialized `do_in` or `do_out`
76
- members.
77
 
78
  ##### `codecvt` members <a id="locale.codecvt.members">[[locale.codecvt.members]]</a>
79
 
80
  ``` cpp
81
- result out(stateT& state,
 
82
  const internT* from, const internT* from_end, const internT*& from_next,
83
  externT* to, externT* to_end, externT*& to_next) const;
84
  ```
85
 
86
  *Returns:*
87
- `do_out(state, from, from_end, from_next, to, to_end, to_next)`
88
 
89
  ``` cpp
90
- result unshift(stateT& state,
91
- externT* to, externT* to_end, externT*& to_next) const;
92
  ```
93
 
94
- *Returns:* `do_unshift(state, to, to_end, to_next)`
95
 
96
  ``` cpp
97
- result in(stateT& state,
 
98
  const externT* from, const externT* from_end, const externT*& from_next,
99
  internT* to, internT* to_end, internT*& to_next) const;
100
  ```
101
 
102
  *Returns:*
103
- `do_in(state, from, from_end, from_next, to, to_end, to_next)`
104
 
105
  ``` cpp
106
  int encoding() const noexcept;
107
  ```
108
 
109
- *Returns:* `do_encoding()`
110
 
111
  ``` cpp
112
  bool always_noconv() const noexcept;
113
  ```
114
 
115
- *Returns:* `do_always_noconv()`
116
 
117
  ``` cpp
118
- int length(stateT& state, const externT* from, const externT* from_end,
119
- size_t max) const;
120
  ```
121
 
122
- *Returns:* `do_length(state, from,from_end,max)`
123
 
124
  ``` cpp
125
  int max_length() const noexcept;
126
  ```
127
 
128
- *Returns:* `do_max_length()`
129
 
130
  ##### `codecvt` virtual functions <a id="locale.codecvt.virtuals">[[locale.codecvt.virtuals]]</a>
131
 
132
  ``` cpp
133
- result do_out(stateT& state,
 
134
  const internT* from, const internT* from_end, const internT*& from_next,
135
  externT* to, externT* to_end, externT*& to_next) const;
136
 
137
- result do_in(stateT& state,
 
138
  const externT* from, const externT* from_end, const externT*& from_next,
139
  internT* to, internT* to_end, internT*& to_next) const;
140
  ```
141
 
142
- *Preconditions:* `(from<=from_end && to<=to_end)` well-defined and
143
  `true`; `state` initialized, if at the beginning of a sequence, or else
144
  equal to the result of converting the preceding characters in the
145
  sequence.
146
 
147
- *Effects:* Translates characters in the source range `[from,from_end)`,
148
- placing the results in sequential positions starting at destination
149
- `to`. Converts no more than `(from_end-from)` source elements, and
150
- stores no more than `(to_end-to)` destination elements.
151
 
152
  Stops if it encounters a character it cannot convert. It always leaves
153
  the `from_next` and `to_next` pointers pointing one beyond the last
154
  element successfully converted. If returns `noconv`, `internT` and
155
  `externT` are the same type and the converted sequence is identical to
156
- the input sequence `[from, from_next)`. `to_next` is set equal to `to`,
157
- the value of `state` is unchanged, and there are no changes to the
158
- values in `[to, to_end)`.
159
 
160
  A `codecvt` facet that is used by `basic_filebuf` ([[file.streams]])
161
  shall have the property that if
162
 
163
  ``` cpp
@@ -180,103 +190,105 @@ would return `ok`, where `to != to_end`, then
180
 
181
  ``` cpp
182
  do_in(state, from, from_end, from_next, to, to + 1, to_next)
183
  ```
184
 
185
- shall also return `ok`.[^7] As a result of operations on `state`, it can
186
- return `ok` or `partial` and set `from_next == from` and
187
- `to_next != to`.
188
 
189
- *Remarks:* Its operations on `state` are unspecified. This argument can
190
- be used, for example, to maintain shift state, to specify conversion
191
- options (such as count only), or to identify a cache of seek offsets.
 
 
 
 
 
 
192
 
193
  *Returns:* An enumeration value, as summarized in
194
  Table  [[tab:localization.convert.result.values.out.in]].
195
 
196
  **Table: `do_in/do_out` result values** <a id="tab:localization.convert.result.values.out.in">[tab:localization.convert.result.values.out.in]</a>
197
 
198
  | Value | Meaning |
199
  | --------- | ------------------------------------------------------------------------------------------------ |
200
  | `ok` | completed the conversion |
201
  | `partial` | not all source characters converted |
202
- | `error` | encountered a character in `[from,from_end)` that it could not convert |
203
  | `noconv` | `internT` and `externT` are the same type, and input sequence is identical to converted sequence |
204
 
205
 
206
- A return value of `partial`, if `(from_next==from_end)`, indicates that
207
- either the destination sequence has not absorbed all the available
208
  destination elements, or that additional source elements are needed
209
  before another destination element can be produced.
210
 
211
  ``` cpp
212
- result do_unshift(stateT& state,
213
- externT* to, externT* to_end, externT*& to_next) const;
214
  ```
215
 
216
- *Requires:* `(to <= to_end)` well defined and true; state initialized,
217
  if at the beginning of a sequence, or else equal to the result of
218
  converting the preceding characters in the sequence.
219
 
220
  *Effects:* Places characters starting at `to` that should be appended to
221
- terminate a sequence when the current `stateT` is given by `state`.[^8]
222
  Stores no more than `(to_end - to)` destination elements, and leaves the
223
  `to_next` pointer pointing one beyond the last element successfully
224
  stored.
225
 
226
  *Returns:* An enumeration value, as summarized in
227
  Table  [[tab:localization.convert.result.values.unshift]].
228
 
229
  **Table: `do_unshift` result values** <a id="tab:localization.convert.result.values.unshift">[tab:localization.convert.result.values.unshift]</a>
230
 
231
  | Value | Meaning |
232
- | --------- | ------------------------------------------------------------------------------------------------------------------ |
233
  | `ok` | completed the sequence |
234
  | `partial` | space for more than `to_end - to` destination elements was needed to terminate a sequence given the value of `state` |
235
  | `error` | an unspecified error has occurred |
236
  | `noconv` | no termination is needed for this `state_type` |
237
 
238
  ``` cpp
239
  int do_encoding() const noexcept;
240
  ```
241
 
242
- *Returns:* -1 if the encoding of the `externT` sequence is
243
  state-dependent; else the constant number of `externT` characters needed
244
- to produce an internal character; or 0 if this number is not a
245
- constant.[^9]
246
 
247
  ``` cpp
248
  bool do_always_noconv() const noexcept;
249
  ```
250
 
251
  *Returns:* `true` if `do_in()` and `do_out()` return `noconv` for all
252
  valid argument values. `codecvt<char, char, mbstate_t>` returns `true`.
253
 
254
  ``` cpp
255
- int do_length(stateT& state, const externT* from, const externT* from_end,
256
- size_t max) const;
257
  ```
258
 
259
- *Preconditions:* `(from<=from_end)` well-defined and `true`; `state`
260
  initialized, if at the beginning of a sequence, or else equal to the
261
  result of converting the preceding characters in the sequence.
262
 
263
  *Effects:* The effect on the `state` argument is “as if” it called
264
  `do_in(state, from, from_end, from, to, to+max, to)` for `to` pointing
265
  to a buffer of at least `max` elements.
266
 
267
  *Returns:* `(from_next-from)` where `from_next` is the largest value in
268
- the range `[from,from_end]` such that the sequence of values in the
269
  range \[`from`, `from_next`) represents `max` or fewer valid complete
270
  characters of type `internT`. The specialization
271
  `codecvt<char, char, mbstate_t>`, returns the lesser of `max` and
272
  `(from_end-from)`.
273
 
274
  ``` cpp
275
  int do_max_length() const noexcept;
276
  ```
277
 
278
  *Returns:* The maximum value that `do_length(state, from, from_end, 1)`
279
- can return for any valid range `[from, from_end)` and `stateT` value
280
  `state`. The specialization
281
  `codecvt<char, char, mbstate_t>::do_max_length()` returns 1.
282
 
 
8
  };
9
 
10
  template <class internT, class externT, class stateT>
11
  class codecvt : public locale::facet, public codecvt_base {
12
  public:
13
+ using intern_type = internT;
14
+ using extern_type = externT;
15
+ using state_type = stateT;
16
 
17
  explicit codecvt(size_t refs = 0);
18
 
19
+ result out(
20
+ stateT& state,
21
  const internT* from, const internT* from_end, const internT*& from_next,
22
  externT* to, externT* to_end, externT*& to_next) const;
23
+
24
+ result unshift(
25
+ stateT& state,
26
  externT* to, externT* to_end, externT*& to_next) const;
27
+
28
+ result in(
29
+ stateT& state,
30
  const externT* from, const externT* from_end, const externT*& from_next,
31
  internT* to, internT* to_end, internT*& to_next) const;
32
+
33
  int encoding() const noexcept;
34
  bool always_noconv() const noexcept;
35
+ int length(stateT&, const externT* from, const externT* end, size_t max) const;
 
36
  int max_length() const noexcept;
37
 
38
  static locale::id id;
39
 
40
  protected:
41
  ~codecvt();
42
+ virtual result do_out(
43
+ stateT& state,
44
  const internT* from, const internT* from_end, const internT*& from_next,
45
  externT* to, externT* to_end, externT*& to_next) const;
46
+ virtual result do_in(
47
+ stateT& state,
48
  const externT* from, const externT* from_end, const externT*& from_next,
49
  internT* to, internT* to_end, internT*& to_next) const;
50
+ virtual result do_unshift(
51
+ stateT& state,
52
  externT* to, externT* to_end, externT*& to_next) const;
53
+
54
  virtual int do_encoding() const noexcept;
55
  virtual bool do_always_noconv() const noexcept;
56
+ virtual int do_length(stateT&, const externT* from, const externT* end, size_t max) const;
 
57
  virtual int do_max_length() const noexcept;
58
  };
59
  }
60
  ```
61
 
 
69
 
70
  The specializations required in Table 
71
  [[tab:localization.category.facets]] ([[locale.category]]) convert the
72
  implementation-defined native character set.
73
  `codecvt<char, char, mbstate_t>` implements a degenerate conversion; it
74
+ does not convert at all. The specialization
75
+ `codecvt<char16_t, char, mbstate_t>` converts between the UTF-16 and
76
+ UTF-8 encoding forms, and the specialization `codecvt`
77
+ `<char32_t, char, mbstate_t>` converts between the UTF-32 and UTF-8
78
+ encoding forms. `codecvt<wchar_t, char, mbstate_t>` converts between the
79
+ native character sets for narrow and wide characters. Specializations on
80
+ `mbstate_t` perform conversion between encodings known to the library
81
+ implementer. Other encodings can be converted by specializing on a
82
+ user-defined `stateT` type. Objects of type `stateT` can contain any
83
+ state that is useful to communicate to or from the specialized `do_in`
84
+ or `do_out` members.
85
 
86
  ##### `codecvt` members <a id="locale.codecvt.members">[[locale.codecvt.members]]</a>
87
 
88
  ``` cpp
89
+ result out(
90
+ stateT& state,
91
  const internT* from, const internT* from_end, const internT*& from_next,
92
  externT* to, externT* to_end, externT*& to_next) const;
93
  ```
94
 
95
  *Returns:*
96
+ `do_out(state, from, from_end, from_next, to, to_end, to_next)`.
97
 
98
  ``` cpp
99
+ result unshift(stateT& state, externT* to, externT* to_end, externT*& to_next) const;
 
100
  ```
101
 
102
+ *Returns:* `do_unshift(state, to, to_end, to_next)`.
103
 
104
  ``` cpp
105
+ result in(
106
+ stateT& state,
107
  const externT* from, const externT* from_end, const externT*& from_next,
108
  internT* to, internT* to_end, internT*& to_next) const;
109
  ```
110
 
111
  *Returns:*
112
+ `do_in(state, from, from_end, from_next, to, to_end, to_next)`.
113
 
114
  ``` cpp
115
  int encoding() const noexcept;
116
  ```
117
 
118
+ *Returns:* `do_encoding()`.
119
 
120
  ``` cpp
121
  bool always_noconv() const noexcept;
122
  ```
123
 
124
+ *Returns:* `do_always_noconv()`.
125
 
126
  ``` cpp
127
+ int length(stateT& state, const externT* from, const externT* from_end, size_t max) const;
 
128
  ```
129
 
130
+ *Returns:* `do_length(state, from, from_end, max)`.
131
 
132
  ``` cpp
133
  int max_length() const noexcept;
134
  ```
135
 
136
+ *Returns:* `do_max_length()`.
137
 
138
  ##### `codecvt` virtual functions <a id="locale.codecvt.virtuals">[[locale.codecvt.virtuals]]</a>
139
 
140
  ``` cpp
141
+ result do_out(
142
+ stateT& state,
143
  const internT* from, const internT* from_end, const internT*& from_next,
144
  externT* to, externT* to_end, externT*& to_next) const;
145
 
146
+ result do_in(
147
+ stateT& state,
148
  const externT* from, const externT* from_end, const externT*& from_next,
149
  internT* to, internT* to_end, internT*& to_next) const;
150
  ```
151
 
152
+ *Requires:* `(from <= from_end && to <= to_end)` well-defined and
153
  `true`; `state` initialized, if at the beginning of a sequence, or else
154
  equal to the result of converting the preceding characters in the
155
  sequence.
156
 
157
+ *Effects:* Translates characters in the source range \[`from`,
158
+ `from_end`), placing the results in sequential positions starting at
159
+ destination `to`. Converts no more than `(from_end - from)` source
160
+ elements, and stores no more than `(to_end - to)` destination elements.
161
 
162
  Stops if it encounters a character it cannot convert. It always leaves
163
  the `from_next` and `to_next` pointers pointing one beyond the last
164
  element successfully converted. If returns `noconv`, `internT` and
165
  `externT` are the same type and the converted sequence is identical to
166
+ the input sequence \[`from`, `from``next`). `to_next` is set equal to
167
+ `to`, the value of `state` is unchanged, and there are no changes to the
168
+ values in \[`to`, `to_end`).
169
 
170
  A `codecvt` facet that is used by `basic_filebuf` ([[file.streams]])
171
  shall have the property that if
172
 
173
  ``` cpp
 
190
 
191
  ``` cpp
192
  do_in(state, from, from_end, from_next, to, to + 1, to_next)
193
  ```
194
 
195
+ shall also return `ok`.[^8]
 
 
196
 
197
+ [*Note 1*: As a result of operations on `state`, it can return `ok` or
198
+ `partial` and set `from_next == from` and
199
+ `to_next != to`. — *end note*]
200
+
201
+ *Remarks:* Its operations on `state` are unspecified.
202
+
203
+ [*Note 2*: This argument can be used, for example, to maintain shift
204
+ state, to specify conversion options (such as count only), or to
205
+ identify a cache of seek offsets. — *end note*]
206
 
207
  *Returns:* An enumeration value, as summarized in
208
  Table  [[tab:localization.convert.result.values.out.in]].
209
 
210
  **Table: `do_in/do_out` result values** <a id="tab:localization.convert.result.values.out.in">[tab:localization.convert.result.values.out.in]</a>
211
 
212
  | Value | Meaning |
213
  | --------- | ------------------------------------------------------------------------------------------------ |
214
  | `ok` | completed the conversion |
215
  | `partial` | not all source characters converted |
216
+ | `error` | encountered a character in {[}`from`, `from_end`{)} that it could not convert |
217
  | `noconv` | `internT` and `externT` are the same type, and input sequence is identical to converted sequence |
218
 
219
 
220
+ A return value of `partial`, if `(from_next == from_end)`, indicates
221
+ that either the destination sequence has not absorbed all the available
222
  destination elements, or that additional source elements are needed
223
  before another destination element can be produced.
224
 
225
  ``` cpp
226
+ result do_unshift(stateT& state, externT* to, externT* to_end, externT*& to_next) const;
 
227
  ```
228
 
229
+ *Requires:* `(to <= to_end)` well defined and `true`; state initialized,
230
  if at the beginning of a sequence, or else equal to the result of
231
  converting the preceding characters in the sequence.
232
 
233
  *Effects:* Places characters starting at `to` that should be appended to
234
+ terminate a sequence when the current `stateT` is given by `state`.[^9]
235
  Stores no more than `(to_end - to)` destination elements, and leaves the
236
  `to_next` pointer pointing one beyond the last element successfully
237
  stored.
238
 
239
  *Returns:* An enumeration value, as summarized in
240
  Table  [[tab:localization.convert.result.values.unshift]].
241
 
242
  **Table: `do_unshift` result values** <a id="tab:localization.convert.result.values.unshift">[tab:localization.convert.result.values.unshift]</a>
243
 
244
  | Value | Meaning |
245
+ | --------- | -------------------------------------------------------------------------------------------------------------------- |
246
  | `ok` | completed the sequence |
247
  | `partial` | space for more than `to_end - to` destination elements was needed to terminate a sequence given the value of `state` |
248
  | `error` | an unspecified error has occurred |
249
  | `noconv` | no termination is needed for this `state_type` |
250
 
251
  ``` cpp
252
  int do_encoding() const noexcept;
253
  ```
254
 
255
+ *Returns:* `-1` if the encoding of the `externT` sequence is
256
  state-dependent; else the constant number of `externT` characters needed
257
+ to produce an internal character; or `0` if this number is not a
258
+ constant.[^10]
259
 
260
  ``` cpp
261
  bool do_always_noconv() const noexcept;
262
  ```
263
 
264
  *Returns:* `true` if `do_in()` and `do_out()` return `noconv` for all
265
  valid argument values. `codecvt<char, char, mbstate_t>` returns `true`.
266
 
267
  ``` cpp
268
+ int do_length(stateT& state, const externT* from, const externT* from_end, size_t max) const;
 
269
  ```
270
 
271
+ *Requires:* `(from <= from_end)` well-defined and `true`; `state`
272
  initialized, if at the beginning of a sequence, or else equal to the
273
  result of converting the preceding characters in the sequence.
274
 
275
  *Effects:* The effect on the `state` argument is “as if” it called
276
  `do_in(state, from, from_end, from, to, to+max, to)` for `to` pointing
277
  to a buffer of at least `max` elements.
278
 
279
  *Returns:* `(from_next-from)` where `from_next` is the largest value in
280
+ the range \[`from`, `from_end`\] such that the sequence of values in the
281
  range \[`from`, `from_next`) represents `max` or fewer valid complete
282
  characters of type `internT`. The specialization
283
  `codecvt<char, char, mbstate_t>`, returns the lesser of `max` and
284
  `(from_end-from)`.
285
 
286
  ``` cpp
287
  int do_max_length() const noexcept;
288
  ```
289
 
290
  *Returns:* The maximum value that `do_length(state, from, from_end, 1)`
291
+ can return for any valid range \[`from`, `from_end`) and `stateT` value
292
  `state`. The specialization
293
  `codecvt<char, char, mbstate_t>::do_max_length()` returns 1.
294