From Jason Turner

[c.strings]

C++17 → C++20 19.2 KB 236 lines
Current Draft | LaTeX Source
Archived: C++17 | C++20
Markdown: C++17 | C++20
Explore in Adventure Game
C++ Weekly: Ep 313

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpsb4ybikq/{from.md → to.md} +134 -91
tmp/tmpsb4ybikq/{from.md → to.md} RENAMED
@@ -22,11 +22,11 @@ namespace std {
22
  ```
23
 
24
  The contents and meaning of the header `<cctype>` are the same as the C
25
  standard library header `<ctype.h>`.
26
 
27
- ISO C 7.4
28
 
29
  ### Header `<cwctype>` synopsis <a id="cwctype.syn">[[cwctype.syn]]</a>
30
 
31
  ``` cpp
32
  namespace std {
@@ -58,11 +58,11 @@ namespace std {
58
  ```
59
 
60
  The contents and meaning of the header `<cwctype>` are the same as the C
61
  standard library header `<wctype.h>`.
62
 
63
- ISO C 7.30
64
 
65
  ### Header `<cstring>` synopsis <a id="cstring.syn">[[cstring.syn]]</a>
66
 
67
  ``` cpp
68
  namespace std {
@@ -78,21 +78,21 @@ namespace std {
78
  int strcmp(const char* s1, const char* s2);
79
  int strcoll(const char* s1, const char* s2);
80
  int strncmp(const char* s1, const char* s2, size_t n);
81
  size_t strxfrm(char* s1, const char* s2, size_t n);
82
  const void* memchr(const void* s, int c, size_t n); // see [library.c]
83
- void* memchr(void* s, int c, size_t n) // see [library.c]
84
- const char* strchr(const char* s, int c) // see [library.c]
85
- char* strchr(char* s, int c) // see [library.c]
86
  size_t strcspn(const char* s1, const char* s2);
87
- const char* strpbrk(const char* s1, const char* s2) // see [library.c]
88
- char* strpbrk(char* s1, const char* s2) // see [library.c]
89
- const char* strrchr(const char* s, int c) // see [library.c]
90
- char* strrchr(char* s, int c) // see [library.c]
91
  size_t strspn(const char* s1, const char* s2);
92
- const char* strstr(const char* s1, const char* s2) // see [library.c]
93
- char* strstr(char* s1, const char* s2) // see [library.c]
94
  char* strtok(char* s1, const char* s2);
95
  void* memset(void* s, int c, size_t n);
96
  char* strerror(int errnum);
97
  size_t strlen(const char* s);
98
  }
@@ -102,20 +102,22 @@ namespace std {
102
 
103
  The contents and meaning of the header `<cstring>` are the same as the C
104
  standard library header `<string.h>`.
105
 
106
  The functions `strerror` and `strtok` are not required to avoid data
107
- races ([[res.on.data.races]]).
108
 
109
- The functions `memcpy` and `memmove` are signal-safe ([[csignal.syn]]).
 
 
 
110
 
111
  [*Note 1*: The functions `strchr`, `strpbrk`, `strrchr`, `strstr`, and
112
- `memchr`, have different signatures in this International Standard, but
113
- they have the same behavior as in the C standard library (
114
- [[library.c]]). — *end note*]
115
 
116
- ISO C 7.24.
117
 
118
  ### Header `<cwchar>` synopsis <a id="cwchar.syn">[[cwchar.syn]]</a>
119
 
120
  ``` cpp
121
  namespace std {
@@ -163,23 +165,23 @@ namespace std {
163
  int wcscmp(const wchar_t* s1, const wchar_t* s2);
164
  int wcscoll(const wchar_t* s1, const wchar_t* s2);
165
  int wcsncmp(const wchar_t* s1, const wchar_t* s2, size_t n);
166
  size_t wcsxfrm(wchar_t* s1, const wchar_t* s2, size_t n);
167
  int wmemcmp(const wchar_t* s1, const wchar_t* s2, size_t n);
168
- const wchar_t* wcschr(const wchar_t* s, wchar_t c) // see [library.c]
169
- wchar_t* wcschr(wchar_t* s, wchar_t c) // see [library.c]
170
  size_t wcscspn(const wchar_t* s1, const wchar_t* s2);
171
- const wchar_t* wcspbrk(const wchar_t* s1, const wchar_t* s2) // see [library.c]
172
- wchar_t* wcspbrk(wchar_t* s1, const wchar_t* s2) // see [library.c]
173
- const wchar_t* wcsrchr(const wchar_t* s, wchar_t c) // see [library.c]
174
- wchar_t* wcsrchr(wchar_t* s, wchar_t c) // see [library.c]
175
  size_t wcsspn(const wchar_t* s1, const wchar_t* s2);
176
- const wchar_t* wcsstr(const wchar_t* s1, const wchar_t* s2) // see [library.c]
177
- wchar_t* wcsstr(wchar_t* s1, const wchar_t* s2) // see [library.c]
178
  wchar_t* wcstok(wchar_t* s1, const wchar_t* s2, wchar_t** ptr);
179
- const wchar_t* wmemchr(const wchar_t* s, wchar_t c, size_t n) // see [library.c]
180
- wchar_t* wmemchr(wchar_t* s, wchar_t c, size_t n) // see [library.c]
181
  size_t wcslen(const wchar_t* s);
182
  wchar_t* wmemset(wchar_t* s, wchar_t c, size_t n);
183
  size_t wcsftime(wchar_t* s, size_t maxsize, const wchar_t* format, const struct tm* timeptr);
184
  wint_t btowc(int c);
185
  int wctob(wint_t c);
@@ -202,41 +204,42 @@ namespace std {
202
  The contents and meaning of the header `<cwchar>` are the same as the C
203
  standard library header `<wchar.h>`, except that it does not declare a
204
  type `wchar_t`.
205
 
206
  [*Note 1*: The functions `wcschr`, `wcspbrk`, `wcsrchr`, `wcsstr`, and
207
- `wmemchr` have different signatures in this International Standard, but
208
- they have the same behavior as in the C standard library (
209
- [[library.c]]). — *end note*]
210
 
211
- ISO C 7.29
212
 
213
  ### Header `<cuchar>` synopsis <a id="cuchar.syn">[[cuchar.syn]]</a>
214
 
215
  ``` cpp
216
  namespace std {
217
  using mbstate_t = see below;
218
  using size_t = see [support.types.layout];
219
 
 
 
220
  size_t mbrtoc16(char16_t* pc16, const char* s, size_t n, mbstate_t* ps);
221
  size_t c16rtomb(char* s, char16_t c16, mbstate_t* ps);
222
  size_t mbrtoc32(char32_t* pc32, const char* s, size_t n, mbstate_t* ps);
223
  size_t c32rtomb(char* s, char32_t c32, mbstate_t* ps);
224
  }
225
  ```
226
 
227
  The contents and meaning of the header `<cuchar>` are the same as the C
228
- standard library header `<uchar.h>`, except that it does not declare
229
- types `char16_t` nor `char32_t`.
 
230
 
231
- ISO C 7.28
232
 
233
  ### Multibyte / wide string and character conversion functions <a id="c.mb.wcs">[[c.mb.wcs]]</a>
234
 
235
- [*Note 1*: The headers `<cstdlib>` ([[cstdlib.syn]]) and `<cwchar>` (
236
- [[cwchar.syn]]) declare the functions described in this
237
- subclause. — *end note*]
238
 
239
  ``` cpp
240
  int mbsinit(const mbstate_t* ps);
241
  int mblen(const char* s, size_t n);
242
  size_t mbstowcs(wchar_t* pwcs, const char* s, size_t n);
@@ -244,24 +247,24 @@ size_t wcstombs(char* s, const wchar_t* pwcs, size_t n);
244
  ```
245
 
246
  *Effects:* These functions have the semantics specified in the C
247
  standard library.
248
 
249
- ISO C 7.22.7.1, 7.22.8, 7.29.6.2.1
250
 
251
  ``` cpp
252
  int mbtowc(wchar_t* pwc, const char* s, size_t n);
253
  int wctomb(char* s, wchar_t wchar);
254
  ```
255
 
256
  *Effects:* These functions have the semantics specified in the C
257
  standard library.
258
 
259
  *Remarks:* Calls to these functions may introduce a data
260
- race ([[res.on.data.races]]) with other calls to the same function.
261
 
262
- ISO C 7.22.7
263
 
264
  ``` cpp
265
  size_t mbrlen(const char* s, size_t n, mbstate_t* ps);
266
  size_t mbrtowc(wchar_t* pwc, const char* s, size_t n, mbstate_t* ps);
267
  size_t wcrtomb(char* s, wchar_t wc, mbstate_t* ps);
@@ -271,97 +274,160 @@ size_t wcsrtombs(char* dst, const wchar_t** src, size_t len, mbstate_t* ps);
271
 
272
  *Effects:* These functions have the semantics specified in the C
273
  standard library.
274
 
275
  *Remarks:* Calling these functions with an `mbstate_t*` argument that is
276
- a null pointer value may introduce a data race ([[res.on.data.races]])
277
  with other calls to the same function with an `mbstate_t*` argument that
278
  is a null pointer value.
279
 
280
- ISO C 7.29.6.3
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
281
 
282
  <!-- Link reference definitions -->
283
  [basic.string]: #basic.string
284
  [basic.string.hash]: #basic.string.hash
285
  [basic.string.literals]: #basic.string.literals
286
  [basic.types]: basic.md#basic.types
287
  [c.mb.wcs]: #c.mb.wcs
288
  [c.strings]: #c.strings
289
  [cctype.syn]: #cctype.syn
290
  [char.traits]: #char.traits
 
291
  [char.traits.require]: #char.traits.require
292
  [char.traits.specializations]: #char.traits.specializations
293
  [char.traits.specializations.char]: #char.traits.specializations.char
294
- [char.traits.specializations.char16_t]: #char.traits.specializations.char16_t
295
- [char.traits.specializations.char32_t]: #char.traits.specializations.char32_t
 
296
  [char.traits.specializations.wchar.t]: #char.traits.specializations.wchar.t
297
  [char.traits.typedefs]: #char.traits.typedefs
298
  [container.requirements]: containers.md#container.requirements
299
  [container.requirements.general]: containers.md#container.requirements.general
300
- [csignal.syn]: language.md#csignal.syn
301
- [cstdlib.syn]: language.md#cstdlib.syn
 
 
 
302
  [cstring.syn]: #cstring.syn
303
  [cuchar.syn]: #cuchar.syn
304
  [cwchar.syn]: #cwchar.syn
305
  [cwctype.syn]: #cwctype.syn
 
306
  [input.output]: input.md#input.output
 
307
  [iostate.flags]: input.md#iostate.flags
308
  [iostream.forward]: input.md#iostream.forward
309
  [iostreams.limits.pos]: input.md#iostreams.limits.pos
310
  [istream.formatted.reqmts]: input.md#istream.formatted.reqmts
311
  [istream.unformatted]: input.md#istream.unformatted
 
312
  [iterator.range]: iterators.md#iterator.range
313
  [iterator.requirements.general]: iterators.md#iterator.requirements.general
314
- [length.error]: diagnostics.md#length.error
315
  [library.c]: library.md#library.c
316
  [ostream.formatted.reqmts]: input.md#ostream.formatted.reqmts
317
- [out.of.range]: diagnostics.md#out.of.range
318
  [random.access.iterators]: iterators.md#random.access.iterators
319
  [res.on.data.races]: library.md#res.on.data.races
320
- [sequence.reqmts]: containers.md#sequence.reqmts
321
  [string.access]: #string.access
322
  [string.accessors]: #string.accessors
323
  [string.append]: #string.append
324
  [string.assign]: #string.assign
325
  [string.capacity]: #string.capacity
326
  [string.classes]: #string.classes
 
327
  [string.compare]: #string.compare
328
  [string.cons]: #string.cons
329
  [string.conversions]: #string.conversions
330
  [string.copy]: #string.copy
 
331
  [string.erase]: #string.erase
 
332
  [string.find]: #string.find
333
- [string.find.first.not.of]: #string.find.first.not.of
334
- [string.find.first.of]: #string.find.first.of
335
- [string.find.last.not.of]: #string.find.last.not.of
336
- [string.find.last.of]: #string.find.last.of
337
  [string.insert]: #string.insert
338
  [string.io]: #string.io
339
  [string.iterators]: #string.iterators
340
  [string.modifiers]: #string.modifiers
341
  [string.nonmembers]: #string.nonmembers
342
- [string.op!=]: #string.op!=
343
- [string.op+]: #string.op+
344
- [string.op+=]: #string.op+=
345
- [string.op<]: #string.op<
346
- [string.op<=]: #string.op<=
347
- [string.op>]: #string.op>
348
- [string.op>=]: #string.op>=
349
- [string.operator==]: #string.operator==
350
  [string.ops]: #string.ops
351
  [string.replace]: #string.replace
352
  [string.require]: #string.require
353
- [string.rfind]: #string.rfind
354
  [string.special]: #string.special
 
355
  [string.substr]: #string.substr
356
  [string.swap]: #string.swap
357
  [string.syn]: #string.syn
358
  [string.view]: #string.view
359
  [string.view.access]: #string.view.access
360
  [string.view.capacity]: #string.view.capacity
 
361
  [string.view.comparison]: #string.view.comparison
 
362
  [string.view.cons]: #string.view.cons
 
363
  [string.view.find]: #string.view.find
364
  [string.view.hash]: #string.view.hash
365
  [string.view.io]: #string.view.io
366
  [string.view.iterators]: #string.view.iterators
367
  [string.view.literals]: #string.view.literals
@@ -369,39 +435,16 @@ ISO C 7.29.6.3
369
  [string.view.ops]: #string.view.ops
370
  [string.view.synop]: #string.view.synop
371
  [string.view.template]: #string.view.template
372
  [strings]: #strings
373
  [strings.general]: #strings.general
374
- [tab:char.traits.require]: #tab:char.traits.require
375
- [tab:copyassignable]: #tab:copyassignable
376
- [tab:copyconstructible]: #tab:copyconstructible
377
- [tab:defaultconstructible]: #tab:defaultconstructible
378
- [tab:string.view.compare]: #tab:string.view.compare
379
- [tab:string.view.comparison.overloads]: #tab:string.view.comparison.overloads
380
- [tab:string.view.ctr.2]: #tab:string.view.ctr.2
381
- [tab:string.view.ctr.3]: #tab:string.view.ctr.3
382
- [tab:strings.compare]: #tab:strings.compare
383
- [tab:strings.ctr.1]: #tab:strings.ctr.1
384
- [tab:strings.ctr.2]: #tab:strings.ctr.2
385
- [tab:strings.ctr.3]: #tab:strings.ctr.3
386
- [tab:strings.ctr.4]: #tab:strings.ctr.4
387
- [tab:strings.ctr.5]: #tab:strings.ctr.5
388
- [tab:strings.ctr.6]: #tab:strings.ctr.6
389
- [tab:strings.ctr.cpy]: #tab:strings.ctr.cpy
390
- [tab:strings.lib.summary]: #tab:strings.lib.summary
391
- [tab:strings.op=]: #tab:strings.op=
392
  [unord.hash]: utilities.md#unord.hash
393
  [utility.swap]: utilities.md#utility.swap
394
 
395
  [^1]: If `eof()` can be held in `char_type` then some iostreams
396
- operations may give surprising results.
397
 
398
- [^2]: `Allocator::value_type` must name the same type as `charT` (
399
- [[string.require]]).
400
-
401
- [^3]: For example, as an argument to non-member functions `swap()` (
402
- [[string.special]]), `operator>{}>()` ([[string.io]]), and
403
- `getline()` ([[string.io]]), or as an argument to
404
- `basic_string::swap()`.
405
-
406
- [^4]: `reserve()` uses `allocator_traits<Allocator>::allocate()` which
407
- may throw an appropriate exception.
 
22
  ```
23
 
24
  The contents and meaning of the header `<cctype>` are the same as the C
25
  standard library header `<ctype.h>`.
26
 
27
+ See also: ISO C 7.4
28
 
29
  ### Header `<cwctype>` synopsis <a id="cwctype.syn">[[cwctype.syn]]</a>
30
 
31
  ``` cpp
32
  namespace std {
 
58
  ```
59
 
60
  The contents and meaning of the header `<cwctype>` are the same as the C
61
  standard library header `<wctype.h>`.
62
 
63
+ See also: ISO C 7.30
64
 
65
  ### Header `<cstring>` synopsis <a id="cstring.syn">[[cstring.syn]]</a>
66
 
67
  ``` cpp
68
  namespace std {
 
78
  int strcmp(const char* s1, const char* s2);
79
  int strcoll(const char* s1, const char* s2);
80
  int strncmp(const char* s1, const char* s2, size_t n);
81
  size_t strxfrm(char* s1, const char* s2, size_t n);
82
  const void* memchr(const void* s, int c, size_t n); // see [library.c]
83
+ void* memchr(void* s, int c, size_t n); // see [library.c]
84
+ const char* strchr(const char* s, int c); // see [library.c]
85
+ char* strchr(char* s, int c); // see [library.c]
86
  size_t strcspn(const char* s1, const char* s2);
87
+ const char* strpbrk(const char* s1, const char* s2); // see [library.c]
88
+ char* strpbrk(char* s1, const char* s2); // see [library.c]
89
+ const char* strrchr(const char* s, int c); // see [library.c]
90
+ char* strrchr(char* s, int c); // see [library.c]
91
  size_t strspn(const char* s1, const char* s2);
92
+ const char* strstr(const char* s1, const char* s2); // see [library.c]
93
+ char* strstr(char* s1, const char* s2); // see [library.c]
94
  char* strtok(char* s1, const char* s2);
95
  void* memset(void* s, int c, size_t n);
96
  char* strerror(int errnum);
97
  size_t strlen(const char* s);
98
  }
 
102
 
103
  The contents and meaning of the header `<cstring>` are the same as the C
104
  standard library header `<string.h>`.
105
 
106
  The functions `strerror` and `strtok` are not required to avoid data
107
+ races [[res.on.data.races]].
108
 
109
+ The functions `memcpy` and `memmove` are signal-safe [[support.signal]].
110
+ Both functions implicitly create objects [[intro.object]] in the
111
+ destination region of storage immediately prior to copying the sequence
112
+ of characters to the destination.
113
 
114
  [*Note 1*: The functions `strchr`, `strpbrk`, `strrchr`, `strstr`, and
115
+ `memchr`, have different signatures in this document, but they have the
116
+ same behavior as in the C standard library [[library.c]]. — *end note*]
 
117
 
118
+ See also: ISO C 7.24
119
 
120
  ### Header `<cwchar>` synopsis <a id="cwchar.syn">[[cwchar.syn]]</a>
121
 
122
  ``` cpp
123
  namespace std {
 
165
  int wcscmp(const wchar_t* s1, const wchar_t* s2);
166
  int wcscoll(const wchar_t* s1, const wchar_t* s2);
167
  int wcsncmp(const wchar_t* s1, const wchar_t* s2, size_t n);
168
  size_t wcsxfrm(wchar_t* s1, const wchar_t* s2, size_t n);
169
  int wmemcmp(const wchar_t* s1, const wchar_t* s2, size_t n);
170
+ const wchar_t* wcschr(const wchar_t* s, wchar_t c); // see [library.c]
171
+ wchar_t* wcschr(wchar_t* s, wchar_t c); // see [library.c]
172
  size_t wcscspn(const wchar_t* s1, const wchar_t* s2);
173
+ const wchar_t* wcspbrk(const wchar_t* s1, const wchar_t* s2); // see [library.c]
174
+ wchar_t* wcspbrk(wchar_t* s1, const wchar_t* s2); // see [library.c]
175
+ const wchar_t* wcsrchr(const wchar_t* s, wchar_t c); // see [library.c]
176
+ wchar_t* wcsrchr(wchar_t* s, wchar_t c); // see [library.c]
177
  size_t wcsspn(const wchar_t* s1, const wchar_t* s2);
178
+ const wchar_t* wcsstr(const wchar_t* s1, const wchar_t* s2); // see [library.c]
179
+ wchar_t* wcsstr(wchar_t* s1, const wchar_t* s2); // see [library.c]
180
  wchar_t* wcstok(wchar_t* s1, const wchar_t* s2, wchar_t** ptr);
181
+ const wchar_t* wmemchr(const wchar_t* s, wchar_t c, size_t n); // see [library.c]
182
+ wchar_t* wmemchr(wchar_t* s, wchar_t c, size_t n); // see [library.c]
183
  size_t wcslen(const wchar_t* s);
184
  wchar_t* wmemset(wchar_t* s, wchar_t c, size_t n);
185
  size_t wcsftime(wchar_t* s, size_t maxsize, const wchar_t* format, const struct tm* timeptr);
186
  wint_t btowc(int c);
187
  int wctob(wint_t c);
 
204
  The contents and meaning of the header `<cwchar>` are the same as the C
205
  standard library header `<wchar.h>`, except that it does not declare a
206
  type `wchar_t`.
207
 
208
  [*Note 1*: The functions `wcschr`, `wcspbrk`, `wcsrchr`, `wcsstr`, and
209
+ `wmemchr` have different signatures in this document, but they have the
210
+ same behavior as in the C standard library [[library.c]]. — *end note*]
 
211
 
212
+ See also: ISO C 7.29
213
 
214
  ### Header `<cuchar>` synopsis <a id="cuchar.syn">[[cuchar.syn]]</a>
215
 
216
  ``` cpp
217
  namespace std {
218
  using mbstate_t = see below;
219
  using size_t = see [support.types.layout];
220
 
221
+ size_t mbrtoc8(char8_t* pc8, const char* s, size_t n, mbstate_t* ps);
222
+ size_t c8rtomb(char* s, char8_t c8, mbstate_t* ps);
223
  size_t mbrtoc16(char16_t* pc16, const char* s, size_t n, mbstate_t* ps);
224
  size_t c16rtomb(char* s, char16_t c16, mbstate_t* ps);
225
  size_t mbrtoc32(char32_t* pc32, const char* s, size_t n, mbstate_t* ps);
226
  size_t c32rtomb(char* s, char32_t c32, mbstate_t* ps);
227
  }
228
  ```
229
 
230
  The contents and meaning of the header `<cuchar>` are the same as the C
231
+ standard library header `<uchar.h>`, except that it declares the
232
+ additional `mbrtoc8` and `c8rtomb` functions and does not declare types
233
+ `char16_t` nor `char32_t`.
234
 
235
+ See also: ISO C 7.28
236
 
237
  ### Multibyte / wide string and character conversion functions <a id="c.mb.wcs">[[c.mb.wcs]]</a>
238
 
239
+ [*Note 1*: The headers `<cstdlib>`, `<cuchar>`, and `<cwchar>` declare
240
+ the functions described in this subclause. — *end note*]
 
241
 
242
  ``` cpp
243
  int mbsinit(const mbstate_t* ps);
244
  int mblen(const char* s, size_t n);
245
  size_t mbstowcs(wchar_t* pwcs, const char* s, size_t n);
 
247
  ```
248
 
249
  *Effects:* These functions have the semantics specified in the C
250
  standard library.
251
 
252
+ See also: ISO C 7.22.7.1, 7.22.8, 7.29.6.2.1
253
 
254
  ``` cpp
255
  int mbtowc(wchar_t* pwc, const char* s, size_t n);
256
  int wctomb(char* s, wchar_t wchar);
257
  ```
258
 
259
  *Effects:* These functions have the semantics specified in the C
260
  standard library.
261
 
262
  *Remarks:* Calls to these functions may introduce a data
263
+ race [[res.on.data.races]] with other calls to the same function.
264
 
265
+ See also: ISO C 7.22.7
266
 
267
  ``` cpp
268
  size_t mbrlen(const char* s, size_t n, mbstate_t* ps);
269
  size_t mbrtowc(wchar_t* pwc, const char* s, size_t n, mbstate_t* ps);
270
  size_t wcrtomb(char* s, wchar_t wc, mbstate_t* ps);
 
274
 
275
  *Effects:* These functions have the semantics specified in the C
276
  standard library.
277
 
278
  *Remarks:* Calling these functions with an `mbstate_t*` argument that is
279
+ a null pointer value may introduce a data race [[res.on.data.races]]
280
  with other calls to the same function with an `mbstate_t*` argument that
281
  is a null pointer value.
282
 
283
+ See also: ISO C 7.29.6.3
284
+
285
+ ``` cpp
286
+ size_t mbrtoc8(char8_t* pc8, const char* s, size_t n, mbstate_t* ps);
287
+ ```
288
+
289
+ *Effects:* If `s` is a null pointer, equivalent to
290
+ `mbrtoc8(nullptr, "", 1, ps)`. Otherwise, the function inspects at most
291
+ `n` bytes beginning with the byte pointed to by `s` to determine the
292
+ number of bytes needed to complete the next multibyte character
293
+ (including any shift sequences). If the function determines that the
294
+ next multibyte character is complete and valid, it determines the values
295
+ of the corresponding UTF-8 code units and then, if `pc8` is not a null
296
+ pointer, stores the value of the first (or only) such code unit in the
297
+ object pointed to by `pc8`. Subsequent calls will store successive UTF-8
298
+ code units without consuming any additional input until all the code
299
+ units have been stored. If the corresponding Unicode character is
300
+ U+0000, the resulting state described is the initial conversion state.
301
+
302
+ *Returns:* The first of the following that applies (given the current
303
+ conversion state):
304
+
305
+ - `0`, if the next `n` or fewer bytes complete the multibyte character
306
+ that corresponds to the U+0000 Unicode character (which is the value
307
+ stored).
308
+ - between `1` and `n` (inclusive), if the next n or fewer bytes complete
309
+ a valid multibyte character (which is the value stored); the value
310
+ returned is the number of bytes that complete the multibyte character.
311
+ - `(size_t)(-3)`, if the next character resulting from a previous call
312
+ has been stored (no bytes from the input have been consumed by this
313
+ call).
314
+ - `(size_t)(-2)`, if the next `n` bytes contribute to an incomplete (but
315
+ potentially valid) multibyte character, and all `n` bytes have been
316
+ processed (no value is stored).
317
+ - `(size_t)(-1)`, if an encoding error occurs, in which case the next
318
+ `n` or fewer bytes do not contribute to a complete and valid multibyte
319
+ character (no value is stored); the value of the macro `EILSEQ` is
320
+ stored in `errno`, and the conversion state is unspecified.
321
+
322
+ ``` cpp
323
+ size_t c8rtomb(char* s, char8_t c8, mbstate_t* ps);
324
+ ```
325
+
326
+ *Effects:* If `s` is a null pointer, equivalent to
327
+ `c8rtomb(buf, u8’`\`0’, ps)` where `buf` is an internal buffer.
328
+ Otherwise, if `c8` completes a sequence of valid UTF-8 code units,
329
+ determines the number of bytes needed to represent the multibyte
330
+ character (including any shift sequences), and stores the multibyte
331
+ character representation in the array whose first element is pointed to
332
+ by `s`. At most `MB_CUR_MAX` bytes are stored. If the multibyte
333
+ character is a null character, a null byte is stored, preceded by any
334
+ shift sequence needed to restore the initial shift state; the resulting
335
+ state described is the initial conversion state.
336
+
337
+ *Returns:* The number of bytes stored in the array object (including any
338
+ shift sequences). If `c8` does not contribute to a sequence of `char8_t`
339
+ corresponding to a valid multibyte character, the value of the macro
340
+ `EILSEQ` is stored in `errno`, `(size_t) (-1)` is returned, and the
341
+ conversion state is unspecified.
342
+
343
+ *Remarks:* Calls to `c8rtomb` with a null pointer argument for `s` may
344
+ introduce a data race [[res.on.data.races]] with other calls to
345
+ `c8rtomb` with a null pointer argument for `s`.
346
 
347
  <!-- Link reference definitions -->
348
  [basic.string]: #basic.string
349
  [basic.string.hash]: #basic.string.hash
350
  [basic.string.literals]: #basic.string.literals
351
  [basic.types]: basic.md#basic.types
352
  [c.mb.wcs]: #c.mb.wcs
353
  [c.strings]: #c.strings
354
  [cctype.syn]: #cctype.syn
355
  [char.traits]: #char.traits
356
+ [char.traits.req]: #char.traits.req
357
  [char.traits.require]: #char.traits.require
358
  [char.traits.specializations]: #char.traits.specializations
359
  [char.traits.specializations.char]: #char.traits.specializations.char
360
+ [char.traits.specializations.char16.t]: #char.traits.specializations.char16.t
361
+ [char.traits.specializations.char32.t]: #char.traits.specializations.char32.t
362
+ [char.traits.specializations.char8.t]: #char.traits.specializations.char8.t
363
  [char.traits.specializations.wchar.t]: #char.traits.specializations.wchar.t
364
  [char.traits.typedefs]: #char.traits.typedefs
365
  [container.requirements]: containers.md#container.requirements
366
  [container.requirements.general]: containers.md#container.requirements.general
367
+ [container.seq.req]: containers.md#container.seq.req
368
+ [cpp17.copyassignable]: #cpp17.copyassignable
369
+ [cpp17.copyconstructible]: #cpp17.copyconstructible
370
+ [cpp17.defaultconstructible]: #cpp17.defaultconstructible
371
+ [cpp17.destructible]: #cpp17.destructible
372
  [cstring.syn]: #cstring.syn
373
  [cuchar.syn]: #cuchar.syn
374
  [cwchar.syn]: #cwchar.syn
375
  [cwctype.syn]: #cwctype.syn
376
+ [defns.character.container]: library.md#defns.character.container
377
  [input.output]: input.md#input.output
378
+ [intro.object]: basic.md#intro.object
379
  [iostate.flags]: input.md#iostate.flags
380
  [iostream.forward]: input.md#iostream.forward
381
  [iostreams.limits.pos]: input.md#iostreams.limits.pos
382
  [istream.formatted.reqmts]: input.md#istream.formatted.reqmts
383
  [istream.unformatted]: input.md#istream.unformatted
384
+ [iterator.concept.contiguous]: iterators.md#iterator.concept.contiguous
385
  [iterator.range]: iterators.md#iterator.range
386
  [iterator.requirements.general]: iterators.md#iterator.requirements.general
 
387
  [library.c]: library.md#library.c
388
  [ostream.formatted.reqmts]: input.md#ostream.formatted.reqmts
 
389
  [random.access.iterators]: iterators.md#random.access.iterators
390
  [res.on.data.races]: library.md#res.on.data.races
 
391
  [string.access]: #string.access
392
  [string.accessors]: #string.accessors
393
  [string.append]: #string.append
394
  [string.assign]: #string.assign
395
  [string.capacity]: #string.capacity
396
  [string.classes]: #string.classes
397
+ [string.cmp]: #string.cmp
398
  [string.compare]: #string.compare
399
  [string.cons]: #string.cons
400
  [string.conversions]: #string.conversions
401
  [string.copy]: #string.copy
402
+ [string.ends.with]: #string.ends.with
403
  [string.erase]: #string.erase
404
+ [string.erasure]: #string.erasure
405
  [string.find]: #string.find
 
 
 
 
406
  [string.insert]: #string.insert
407
  [string.io]: #string.io
408
  [string.iterators]: #string.iterators
409
  [string.modifiers]: #string.modifiers
410
  [string.nonmembers]: #string.nonmembers
411
+ [string.op.append]: #string.op.append
412
+ [string.op.plus]: #string.op.plus
 
 
 
 
 
 
413
  [string.ops]: #string.ops
414
  [string.replace]: #string.replace
415
  [string.require]: #string.require
 
416
  [string.special]: #string.special
417
+ [string.starts.with]: #string.starts.with
418
  [string.substr]: #string.substr
419
  [string.swap]: #string.swap
420
  [string.syn]: #string.syn
421
  [string.view]: #string.view
422
  [string.view.access]: #string.view.access
423
  [string.view.capacity]: #string.view.capacity
424
+ [string.view.compare]: #string.view.compare
425
  [string.view.comparison]: #string.view.comparison
426
+ [string.view.comparison.overloads]: #string.view.comparison.overloads
427
  [string.view.cons]: #string.view.cons
428
+ [string.view.deduct]: #string.view.deduct
429
  [string.view.find]: #string.view.find
430
  [string.view.hash]: #string.view.hash
431
  [string.view.io]: #string.view.io
432
  [string.view.iterators]: #string.view.iterators
433
  [string.view.literals]: #string.view.literals
 
435
  [string.view.ops]: #string.view.ops
436
  [string.view.synop]: #string.view.synop
437
  [string.view.template]: #string.view.template
438
  [strings]: #strings
439
  [strings.general]: #strings.general
440
+ [strings.summary]: #strings.summary
441
+ [support.signal]: support.md#support.signal
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
442
  [unord.hash]: utilities.md#unord.hash
443
  [utility.swap]: utilities.md#utility.swap
444
 
445
  [^1]: If `eof()` can be held in `char_type` then some iostreams
446
+ operations can give surprising results.
447
 
448
+ [^2]: For example, as an argument to non-member functions `swap()`
449
+ [[string.special]], `operator>{}>()` [[string.io]], and `getline()`
450
+ [[string.io]], or as an argument to `basic_string::swap()`.