From Jason Turner

[locale.codecvt]

C++17 → C++20 8.3 KB 69 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/tmpvqhg7nm1/{from.md → to.md} +30 -30
tmp/tmpvqhg7nm1/{from.md → to.md} RENAMED
@@ -59,33 +59,32 @@ namespace std {
59
  }
60
  ```
61
 
62
  The class `codecvt<internT, externT, stateT>` is for use when converting
63
  from one character encoding to another, such as from wide characters to
64
- multibyte characters or between wide character encodings such as Unicode
65
  and EUC.
66
 
67
  The `stateT` argument selects the pair of character encodings being
68
  mapped between.
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,
@@ -133,11 +132,11 @@ int length(stateT& state, const externT* from, const externT* from_end, size_t m
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,
@@ -147,14 +146,14 @@ 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.
@@ -165,12 +164,12 @@ 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
174
  do_out(state, from, from_end, from_next, to, to_end, to_next)
175
  ```
176
 
@@ -203,13 +202,13 @@ shall also return `ok`.[^8]
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 |
@@ -224,24 +223,24 @@ 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` |
@@ -266,15 +265,16 @@ 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
 
59
  }
60
  ```
61
 
62
  The class `codecvt<internT, externT, stateT>` is for use when converting
63
  from one character encoding to another, such as from wide characters to
64
+ multibyte characters or between wide character encodings such as UTF-32
65
  and EUC.
66
 
67
  The `stateT` argument selects the pair of character encodings being
68
  mapped between.
69
 
70
+ The specializations required in [[locale.category.facets]]
71
+ [[locale.category]] convert the implementation-defined native character
72
+ set. `codecvt<char, char, mbstate_t>` implements a degenerate
73
+ conversion; it does not convert at all. The specialization
74
+ `codecvt<char16_t, char8_t, mbstate_t>` converts between the UTF-16 and
 
75
  UTF-8 encoding forms, and the specialization `codecvt`
76
+ `<char32_t, char8_t, mbstate_t>` converts between the UTF-32 and UTF-8
77
  encoding forms. `codecvt<wchar_t, char, mbstate_t>` converts between the
78
+ native character sets for ordinary and wide characters. Specializations
79
+ on `mbstate_t` perform conversion between encodings known to the library
80
  implementer. Other encodings can be converted by specializing on a
81
+ program-defined `stateT` type. Objects of type `stateT` can contain any
82
  state that is useful to communicate to or from the specialized `do_in`
83
  or `do_out` members.
84
 
85
+ ##### Members <a id="locale.codecvt.members">[[locale.codecvt.members]]</a>
86
 
87
  ``` cpp
88
  result out(
89
  stateT& state,
90
  const internT* from, const internT* from_end, const internT*& from_next,
 
132
  int max_length() const noexcept;
133
  ```
134
 
135
  *Returns:* `do_max_length()`.
136
 
137
+ ##### Virtual functions <a id="locale.codecvt.virtuals">[[locale.codecvt.virtuals]]</a>
138
 
139
  ``` cpp
140
  result do_out(
141
  stateT& state,
142
  const internT* from, const internT* from_end, const internT*& from_next,
 
146
  stateT& state,
147
  const externT* from, const externT* from_end, const externT*& from_next,
148
  internT* to, internT* to_end, internT*& to_next) const;
149
  ```
150
 
151
+ *Preconditions:* `(from <= from_end && to <= to_end)` is well-defined
152
+ and `true`; `state` is initialized, if at the beginning of a sequence,
153
+ or else is equal to the result of converting the preceding characters in
154
+ the sequence.
155
 
156
  *Effects:* Translates characters in the source range \[`from`,
157
  `from_end`), placing the results in sequential positions starting at
158
  destination `to`. Converts no more than `(from_end - from)` source
159
  elements, and stores no more than `(to_end - to)` destination elements.
 
164
  `externT` are the same type and the converted sequence is identical to
165
  the input sequence \[`from`, `from``next`). `to_next` is set equal to
166
  `to`, the value of `state` is unchanged, and there are no changes to the
167
  values in \[`to`, `to_end`).
168
 
169
+ A `codecvt` facet that is used by `basic_filebuf` [[file.streams]] shall
170
+ have the property that if
171
 
172
  ``` cpp
173
  do_out(state, from, from_end, from_next, to, to_end, to_next)
174
  ```
175
 
 
202
  [*Note 2*: This argument can be used, for example, to maintain shift
203
  state, to specify conversion options (such as count only), or to
204
  identify a cache of seek offsets. — *end note*]
205
 
206
  *Returns:* An enumeration value, as summarized in
207
+ [[locale.codecvt.inout]].
208
 
209
+ **Table: `do_in/do_out` result values** <a id="locale.codecvt.inout">[locale.codecvt.inout]</a>
210
 
211
  | Value | Meaning |
212
  | --------- | ------------------------------------------------------------------------------------------------ |
213
  | `ok` | completed the conversion |
214
  | `partial` | not all source characters converted |
 
223
 
224
  ``` cpp
225
  result do_unshift(stateT& state, externT* to, externT* to_end, externT*& to_next) const;
226
  ```
227
 
228
+ *Preconditions:* `(to <= to_end)` is well-defined and `true`; `state` is
229
+ initialized, if at the beginning of a sequence, or else is equal to the
230
+ result of converting the preceding characters in the sequence.
231
 
232
  *Effects:* Places characters starting at `to` that should be appended to
233
  terminate a sequence when the current `stateT` is given by `state`.[^9]
234
  Stores no more than `(to_end - to)` destination elements, and leaves the
235
  `to_next` pointer pointing one beyond the last element successfully
236
  stored.
237
 
238
  *Returns:* An enumeration value, as summarized in
239
+ [[locale.codecvt.unshift]].
240
 
241
+ **Table: `do_unshift` result values** <a id="locale.codecvt.unshift">[locale.codecvt.unshift]</a>
242
 
243
  | Value | Meaning |
244
  | --------- | -------------------------------------------------------------------------------------------------------------------- |
245
  | `ok` | completed the sequence |
246
  | `partial` | space for more than `to_end - to` destination elements was needed to terminate a sequence given the value of `state` |
 
265
 
266
  ``` cpp
267
  int do_length(stateT& state, const externT* from, const externT* from_end, size_t max) const;
268
  ```
269
 
270
+ *Preconditions:* `(from <= from_end)` is well-defined and `true`;
271
+ `state` is initialized, if at the beginning of a sequence, or else is
272
+ equal to the result of converting the preceding characters in the
273
+ 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