From Jason Turner

[c.mb.wcs]

C++17 → C++20 11.8 KB 159 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/tmpsmwmz3k9/{from.md → to.md} +96 -57
tmp/tmpsmwmz3k9/{from.md → to.md} RENAMED
@@ -1,10 +1,9 @@
1
  ### Multibyte / wide string and character conversion functions <a id="c.mb.wcs">[[c.mb.wcs]]</a>
2
 
3
- [*Note 1*: The headers `<cstdlib>` ([[cstdlib.syn]]) and `<cwchar>` (
4
- [[cwchar.syn]]) declare the functions described in this
5
- subclause. — *end note*]
6
 
7
  ``` cpp
8
  int mbsinit(const mbstate_t* ps);
9
  int mblen(const char* s, size_t n);
10
  size_t mbstowcs(wchar_t* pwcs, const char* s, size_t n);
@@ -12,24 +11,24 @@ size_t wcstombs(char* s, const wchar_t* pwcs, size_t n);
12
  ```
13
 
14
  *Effects:* These functions have the semantics specified in the C
15
  standard library.
16
 
17
- ISO C 7.22.7.1, 7.22.8, 7.29.6.2.1
18
 
19
  ``` cpp
20
  int mbtowc(wchar_t* pwc, const char* s, size_t n);
21
  int wctomb(char* s, wchar_t wchar);
22
  ```
23
 
24
  *Effects:* These functions have the semantics specified in the C
25
  standard library.
26
 
27
  *Remarks:* Calls to these functions may introduce a data
28
- race ([[res.on.data.races]]) with other calls to the same function.
29
 
30
- ISO C 7.22.7
31
 
32
  ``` cpp
33
  size_t mbrlen(const char* s, size_t n, mbstate_t* ps);
34
  size_t mbrtowc(wchar_t* pwc, const char* s, size_t n, mbstate_t* ps);
35
  size_t wcrtomb(char* s, wchar_t wc, mbstate_t* ps);
@@ -39,97 +38,160 @@ size_t wcsrtombs(char* dst, const wchar_t** src, size_t len, mbstate_t* ps);
39
 
40
  *Effects:* These functions have the semantics specified in the C
41
  standard library.
42
 
43
  *Remarks:* Calling these functions with an `mbstate_t*` argument that is
44
- a null pointer value may introduce a data race ([[res.on.data.races]])
45
  with other calls to the same function with an `mbstate_t*` argument that
46
  is a null pointer value.
47
 
48
- ISO C 7.29.6.3
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
49
 
50
  <!-- Link reference definitions -->
51
  [basic.string]: #basic.string
52
  [basic.string.hash]: #basic.string.hash
53
  [basic.string.literals]: #basic.string.literals
54
  [basic.types]: basic.md#basic.types
55
  [c.mb.wcs]: #c.mb.wcs
56
  [c.strings]: #c.strings
57
  [cctype.syn]: #cctype.syn
58
  [char.traits]: #char.traits
 
59
  [char.traits.require]: #char.traits.require
60
  [char.traits.specializations]: #char.traits.specializations
61
  [char.traits.specializations.char]: #char.traits.specializations.char
62
- [char.traits.specializations.char16_t]: #char.traits.specializations.char16_t
63
- [char.traits.specializations.char32_t]: #char.traits.specializations.char32_t
 
64
  [char.traits.specializations.wchar.t]: #char.traits.specializations.wchar.t
65
  [char.traits.typedefs]: #char.traits.typedefs
66
  [container.requirements]: containers.md#container.requirements
67
  [container.requirements.general]: containers.md#container.requirements.general
68
- [csignal.syn]: language.md#csignal.syn
69
- [cstdlib.syn]: language.md#cstdlib.syn
 
 
 
70
  [cstring.syn]: #cstring.syn
71
  [cuchar.syn]: #cuchar.syn
72
  [cwchar.syn]: #cwchar.syn
73
  [cwctype.syn]: #cwctype.syn
 
74
  [input.output]: input.md#input.output
 
75
  [iostate.flags]: input.md#iostate.flags
76
  [iostream.forward]: input.md#iostream.forward
77
  [iostreams.limits.pos]: input.md#iostreams.limits.pos
78
  [istream.formatted.reqmts]: input.md#istream.formatted.reqmts
79
  [istream.unformatted]: input.md#istream.unformatted
 
80
  [iterator.range]: iterators.md#iterator.range
81
  [iterator.requirements.general]: iterators.md#iterator.requirements.general
82
- [length.error]: diagnostics.md#length.error
83
  [library.c]: library.md#library.c
84
  [ostream.formatted.reqmts]: input.md#ostream.formatted.reqmts
85
- [out.of.range]: diagnostics.md#out.of.range
86
  [random.access.iterators]: iterators.md#random.access.iterators
87
  [res.on.data.races]: library.md#res.on.data.races
88
- [sequence.reqmts]: containers.md#sequence.reqmts
89
  [string.access]: #string.access
90
  [string.accessors]: #string.accessors
91
  [string.append]: #string.append
92
  [string.assign]: #string.assign
93
  [string.capacity]: #string.capacity
94
  [string.classes]: #string.classes
 
95
  [string.compare]: #string.compare
96
  [string.cons]: #string.cons
97
  [string.conversions]: #string.conversions
98
  [string.copy]: #string.copy
 
99
  [string.erase]: #string.erase
 
100
  [string.find]: #string.find
101
- [string.find.first.not.of]: #string.find.first.not.of
102
- [string.find.first.of]: #string.find.first.of
103
- [string.find.last.not.of]: #string.find.last.not.of
104
- [string.find.last.of]: #string.find.last.of
105
  [string.insert]: #string.insert
106
  [string.io]: #string.io
107
  [string.iterators]: #string.iterators
108
  [string.modifiers]: #string.modifiers
109
  [string.nonmembers]: #string.nonmembers
110
- [string.op!=]: #string.op!=
111
- [string.op+]: #string.op+
112
- [string.op+=]: #string.op+=
113
- [string.op<]: #string.op<
114
- [string.op<=]: #string.op<=
115
- [string.op>]: #string.op>
116
- [string.op>=]: #string.op>=
117
- [string.operator==]: #string.operator==
118
  [string.ops]: #string.ops
119
  [string.replace]: #string.replace
120
  [string.require]: #string.require
121
- [string.rfind]: #string.rfind
122
  [string.special]: #string.special
 
123
  [string.substr]: #string.substr
124
  [string.swap]: #string.swap
125
  [string.syn]: #string.syn
126
  [string.view]: #string.view
127
  [string.view.access]: #string.view.access
128
  [string.view.capacity]: #string.view.capacity
 
129
  [string.view.comparison]: #string.view.comparison
 
130
  [string.view.cons]: #string.view.cons
 
131
  [string.view.find]: #string.view.find
132
  [string.view.hash]: #string.view.hash
133
  [string.view.io]: #string.view.io
134
  [string.view.iterators]: #string.view.iterators
135
  [string.view.literals]: #string.view.literals
@@ -137,39 +199,16 @@ ISO C 7.29.6.3
137
  [string.view.ops]: #string.view.ops
138
  [string.view.synop]: #string.view.synop
139
  [string.view.template]: #string.view.template
140
  [strings]: #strings
141
  [strings.general]: #strings.general
142
- [tab:char.traits.require]: #tab:char.traits.require
143
- [tab:copyassignable]: #tab:copyassignable
144
- [tab:copyconstructible]: #tab:copyconstructible
145
- [tab:defaultconstructible]: #tab:defaultconstructible
146
- [tab:string.view.compare]: #tab:string.view.compare
147
- [tab:string.view.comparison.overloads]: #tab:string.view.comparison.overloads
148
- [tab:string.view.ctr.2]: #tab:string.view.ctr.2
149
- [tab:string.view.ctr.3]: #tab:string.view.ctr.3
150
- [tab:strings.compare]: #tab:strings.compare
151
- [tab:strings.ctr.1]: #tab:strings.ctr.1
152
- [tab:strings.ctr.2]: #tab:strings.ctr.2
153
- [tab:strings.ctr.3]: #tab:strings.ctr.3
154
- [tab:strings.ctr.4]: #tab:strings.ctr.4
155
- [tab:strings.ctr.5]: #tab:strings.ctr.5
156
- [tab:strings.ctr.6]: #tab:strings.ctr.6
157
- [tab:strings.ctr.cpy]: #tab:strings.ctr.cpy
158
- [tab:strings.lib.summary]: #tab:strings.lib.summary
159
- [tab:strings.op=]: #tab:strings.op=
160
  [unord.hash]: utilities.md#unord.hash
161
  [utility.swap]: utilities.md#utility.swap
162
 
163
  [^1]: If `eof()` can be held in `char_type` then some iostreams
164
- operations may give surprising results.
165
 
166
- [^2]: `Allocator::value_type` must name the same type as `charT` (
167
- [[string.require]]).
168
-
169
- [^3]: For example, as an argument to non-member functions `swap()` (
170
- [[string.special]]), `operator>{}>()` ([[string.io]]), and
171
- `getline()` ([[string.io]]), or as an argument to
172
- `basic_string::swap()`.
173
-
174
- [^4]: `reserve()` uses `allocator_traits<Allocator>::allocate()` which
175
- may throw an appropriate exception.
 
1
  ### Multibyte / wide string and character conversion functions <a id="c.mb.wcs">[[c.mb.wcs]]</a>
2
 
3
+ [*Note 1*: The headers `<cstdlib>`, `<cuchar>`, and `<cwchar>` declare
4
+ the functions described in this subclause. — *end note*]
 
5
 
6
  ``` cpp
7
  int mbsinit(const mbstate_t* ps);
8
  int mblen(const char* s, size_t n);
9
  size_t mbstowcs(wchar_t* pwcs, const char* s, size_t n);
 
11
  ```
12
 
13
  *Effects:* These functions have the semantics specified in the C
14
  standard library.
15
 
16
+ See also: ISO C 7.22.7.1, 7.22.8, 7.29.6.2.1
17
 
18
  ``` cpp
19
  int mbtowc(wchar_t* pwc, const char* s, size_t n);
20
  int wctomb(char* s, wchar_t wchar);
21
  ```
22
 
23
  *Effects:* These functions have the semantics specified in the C
24
  standard library.
25
 
26
  *Remarks:* Calls to these functions may introduce a data
27
+ race [[res.on.data.races]] with other calls to the same function.
28
 
29
+ See also: ISO C 7.22.7
30
 
31
  ``` cpp
32
  size_t mbrlen(const char* s, size_t n, mbstate_t* ps);
33
  size_t mbrtowc(wchar_t* pwc, const char* s, size_t n, mbstate_t* ps);
34
  size_t wcrtomb(char* s, wchar_t wc, mbstate_t* ps);
 
38
 
39
  *Effects:* These functions have the semantics specified in the C
40
  standard library.
41
 
42
  *Remarks:* Calling these functions with an `mbstate_t*` argument that is
43
+ a null pointer value may introduce a data race [[res.on.data.races]]
44
  with other calls to the same function with an `mbstate_t*` argument that
45
  is a null pointer value.
46
 
47
+ See also: ISO C 7.29.6.3
48
+
49
+ ``` cpp
50
+ size_t mbrtoc8(char8_t* pc8, const char* s, size_t n, mbstate_t* ps);
51
+ ```
52
+
53
+ *Effects:* If `s` is a null pointer, equivalent to
54
+ `mbrtoc8(nullptr, "", 1, ps)`. Otherwise, the function inspects at most
55
+ `n` bytes beginning with the byte pointed to by `s` to determine the
56
+ number of bytes needed to complete the next multibyte character
57
+ (including any shift sequences). If the function determines that the
58
+ next multibyte character is complete and valid, it determines the values
59
+ of the corresponding UTF-8 code units and then, if `pc8` is not a null
60
+ pointer, stores the value of the first (or only) such code unit in the
61
+ object pointed to by `pc8`. Subsequent calls will store successive UTF-8
62
+ code units without consuming any additional input until all the code
63
+ units have been stored. If the corresponding Unicode character is
64
+ U+0000, the resulting state described is the initial conversion state.
65
+
66
+ *Returns:* The first of the following that applies (given the current
67
+ conversion state):
68
+
69
+ - `0`, if the next `n` or fewer bytes complete the multibyte character
70
+ that corresponds to the U+0000 Unicode character (which is the value
71
+ stored).
72
+ - between `1` and `n` (inclusive), if the next n or fewer bytes complete
73
+ a valid multibyte character (which is the value stored); the value
74
+ returned is the number of bytes that complete the multibyte character.
75
+ - `(size_t)(-3)`, if the next character resulting from a previous call
76
+ has been stored (no bytes from the input have been consumed by this
77
+ call).
78
+ - `(size_t)(-2)`, if the next `n` bytes contribute to an incomplete (but
79
+ potentially valid) multibyte character, and all `n` bytes have been
80
+ processed (no value is stored).
81
+ - `(size_t)(-1)`, if an encoding error occurs, in which case the next
82
+ `n` or fewer bytes do not contribute to a complete and valid multibyte
83
+ character (no value is stored); the value of the macro `EILSEQ` is
84
+ stored in `errno`, and the conversion state is unspecified.
85
+
86
+ ``` cpp
87
+ size_t c8rtomb(char* s, char8_t c8, mbstate_t* ps);
88
+ ```
89
+
90
+ *Effects:* If `s` is a null pointer, equivalent to
91
+ `c8rtomb(buf, u8’`\`0’, ps)` where `buf` is an internal buffer.
92
+ Otherwise, if `c8` completes a sequence of valid UTF-8 code units,
93
+ determines the number of bytes needed to represent the multibyte
94
+ character (including any shift sequences), and stores the multibyte
95
+ character representation in the array whose first element is pointed to
96
+ by `s`. At most `MB_CUR_MAX` bytes are stored. If the multibyte
97
+ character is a null character, a null byte is stored, preceded by any
98
+ shift sequence needed to restore the initial shift state; the resulting
99
+ state described is the initial conversion state.
100
+
101
+ *Returns:* The number of bytes stored in the array object (including any
102
+ shift sequences). If `c8` does not contribute to a sequence of `char8_t`
103
+ corresponding to a valid multibyte character, the value of the macro
104
+ `EILSEQ` is stored in `errno`, `(size_t) (-1)` is returned, and the
105
+ conversion state is unspecified.
106
+
107
+ *Remarks:* Calls to `c8rtomb` with a null pointer argument for `s` may
108
+ introduce a data race [[res.on.data.races]] with other calls to
109
+ `c8rtomb` with a null pointer argument for `s`.
110
 
111
  <!-- Link reference definitions -->
112
  [basic.string]: #basic.string
113
  [basic.string.hash]: #basic.string.hash
114
  [basic.string.literals]: #basic.string.literals
115
  [basic.types]: basic.md#basic.types
116
  [c.mb.wcs]: #c.mb.wcs
117
  [c.strings]: #c.strings
118
  [cctype.syn]: #cctype.syn
119
  [char.traits]: #char.traits
120
+ [char.traits.req]: #char.traits.req
121
  [char.traits.require]: #char.traits.require
122
  [char.traits.specializations]: #char.traits.specializations
123
  [char.traits.specializations.char]: #char.traits.specializations.char
124
+ [char.traits.specializations.char16.t]: #char.traits.specializations.char16.t
125
+ [char.traits.specializations.char32.t]: #char.traits.specializations.char32.t
126
+ [char.traits.specializations.char8.t]: #char.traits.specializations.char8.t
127
  [char.traits.specializations.wchar.t]: #char.traits.specializations.wchar.t
128
  [char.traits.typedefs]: #char.traits.typedefs
129
  [container.requirements]: containers.md#container.requirements
130
  [container.requirements.general]: containers.md#container.requirements.general
131
+ [container.seq.req]: containers.md#container.seq.req
132
+ [cpp17.copyassignable]: #cpp17.copyassignable
133
+ [cpp17.copyconstructible]: #cpp17.copyconstructible
134
+ [cpp17.defaultconstructible]: #cpp17.defaultconstructible
135
+ [cpp17.destructible]: #cpp17.destructible
136
  [cstring.syn]: #cstring.syn
137
  [cuchar.syn]: #cuchar.syn
138
  [cwchar.syn]: #cwchar.syn
139
  [cwctype.syn]: #cwctype.syn
140
+ [defns.character.container]: library.md#defns.character.container
141
  [input.output]: input.md#input.output
142
+ [intro.object]: basic.md#intro.object
143
  [iostate.flags]: input.md#iostate.flags
144
  [iostream.forward]: input.md#iostream.forward
145
  [iostreams.limits.pos]: input.md#iostreams.limits.pos
146
  [istream.formatted.reqmts]: input.md#istream.formatted.reqmts
147
  [istream.unformatted]: input.md#istream.unformatted
148
+ [iterator.concept.contiguous]: iterators.md#iterator.concept.contiguous
149
  [iterator.range]: iterators.md#iterator.range
150
  [iterator.requirements.general]: iterators.md#iterator.requirements.general
 
151
  [library.c]: library.md#library.c
152
  [ostream.formatted.reqmts]: input.md#ostream.formatted.reqmts
 
153
  [random.access.iterators]: iterators.md#random.access.iterators
154
  [res.on.data.races]: library.md#res.on.data.races
 
155
  [string.access]: #string.access
156
  [string.accessors]: #string.accessors
157
  [string.append]: #string.append
158
  [string.assign]: #string.assign
159
  [string.capacity]: #string.capacity
160
  [string.classes]: #string.classes
161
+ [string.cmp]: #string.cmp
162
  [string.compare]: #string.compare
163
  [string.cons]: #string.cons
164
  [string.conversions]: #string.conversions
165
  [string.copy]: #string.copy
166
+ [string.ends.with]: #string.ends.with
167
  [string.erase]: #string.erase
168
+ [string.erasure]: #string.erasure
169
  [string.find]: #string.find
 
 
 
 
170
  [string.insert]: #string.insert
171
  [string.io]: #string.io
172
  [string.iterators]: #string.iterators
173
  [string.modifiers]: #string.modifiers
174
  [string.nonmembers]: #string.nonmembers
175
+ [string.op.append]: #string.op.append
176
+ [string.op.plus]: #string.op.plus
 
 
 
 
 
 
177
  [string.ops]: #string.ops
178
  [string.replace]: #string.replace
179
  [string.require]: #string.require
 
180
  [string.special]: #string.special
181
+ [string.starts.with]: #string.starts.with
182
  [string.substr]: #string.substr
183
  [string.swap]: #string.swap
184
  [string.syn]: #string.syn
185
  [string.view]: #string.view
186
  [string.view.access]: #string.view.access
187
  [string.view.capacity]: #string.view.capacity
188
+ [string.view.compare]: #string.view.compare
189
  [string.view.comparison]: #string.view.comparison
190
+ [string.view.comparison.overloads]: #string.view.comparison.overloads
191
  [string.view.cons]: #string.view.cons
192
+ [string.view.deduct]: #string.view.deduct
193
  [string.view.find]: #string.view.find
194
  [string.view.hash]: #string.view.hash
195
  [string.view.io]: #string.view.io
196
  [string.view.iterators]: #string.view.iterators
197
  [string.view.literals]: #string.view.literals
 
199
  [string.view.ops]: #string.view.ops
200
  [string.view.synop]: #string.view.synop
201
  [string.view.template]: #string.view.template
202
  [strings]: #strings
203
  [strings.general]: #strings.general
204
+ [strings.summary]: #strings.summary
205
+ [support.signal]: support.md#support.signal
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
206
  [unord.hash]: utilities.md#unord.hash
207
  [utility.swap]: utilities.md#utility.swap
208
 
209
  [^1]: If `eof()` can be held in `char_type` then some iostreams
210
+ operations can give surprising results.
211
 
212
+ [^2]: For example, as an argument to non-member functions `swap()`
213
+ [[string.special]], `operator>{}>()` [[string.io]], and `getline()`
214
+ [[string.io]], or as an argument to `basic_string::swap()`.