From Jason Turner

[strings]

C++14 → C++17 144.4 KB 2371 lines
Current Draft | LaTeX Source
Archived: C++14 | C++17
Markdown: C++14 | C++17
Explore in Adventure Game
Large diff (144.4 KB) - rendering may be slow on some devices

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpv3canz8t/{from.md → to.md} +1766 -537
tmp/tmpv3canz8t/{from.md → to.md} RENAMED
@@ -1,24 +1,25 @@
1
  # Strings library <a id="strings">[[strings]]</a>
2
 
3
  ## General <a id="strings.general">[[strings.general]]</a>
4
 
5
  This Clause describes components for manipulating sequences of any
6
- non-array POD ([[basic.types]]) type. In this Clause such types are
7
- called *char-like types*, and objects of char-like types are called
8
- *char-like objects* or simply *characters*.
9
 
10
  The following subclauses describe a character traits class, a string
11
  class, and null-terminated sequence utilities, as summarized in Table 
12
  [[tab:strings.lib.summary]].
13
 
14
  **Table: Strings library summary** <a id="tab:strings.lib.summary">[tab:strings.lib.summary]</a>
15
 
16
  | Subclause | | Header |
17
- | ------------------ | ---------------------------------- | ----------- |
18
  | [[char.traits]] | Character traits | `<string>` |
19
  | [[string.classes]] | String classes | `<string>` |
 
20
  | | | `<cctype>` |
21
  | | | `<cwctype>` |
22
  | [[c.strings]] | Null-terminated sequence utilities | `<cstring>` |
23
  | | | `<cwchar>` |
24
  | | | `<cstdlib>` |
@@ -34,21 +35,21 @@ four specializations, `char_traits<char>`, `char_traits<char16_t>`,
34
  requirements.
35
 
36
  Most classes specified in Clauses  [[string.classes]] and 
37
  [[input.output]] need a set of related types and functions to complete
38
  the definition of their semantics. These types and functions are
39
- provided as a set of member typedefs and functions in the template
40
- parameter ‘traits’ used by each such template. This subclause defines
41
- the semantics of these members.
42
 
43
  To specialize those templates to generate a string or iostream class to
44
  handle a particular character container type `CharT`, that and its
45
  related character traits class `Traits` are passed as a pair of
46
  parameters to the string or iostream template as parameters `charT` and
47
  `traits`. `Traits::char_type` shall be the same as `CharT`.
48
 
49
- This subclause specifies a struct template, `char_traits<charT>`, and
50
  four explicit specializations of it, `char_traits<{}char>`,
51
  `char_traits<char16_t>`, `char_traits<char32_t>`, and
52
  `char_traits<wchar_t>`, all of which appear in the header `<string>` and
53
  satisfy the requirements below.
54
 
@@ -56,36 +57,36 @@ satisfy the requirements below.
56
 
57
  In Table  [[tab:char.traits.require]], `X` denotes a Traits class
58
  defining types and functions for the character container type `CharT`;
59
  `c` and `d` denote values of type `CharT`; `p` and `q` denote values of
60
  type `const CharT*`; `s` denotes a value of type `CharT*`; `n`, `i` and
61
- `j` denote values of type `std::size_t`; `e` and `f` denote values of
62
- type `X::int_type`; `pos` denotes a value of type `X::pos_type`; `state`
63
  denotes a value of type `X::state_type`; and `r` denotes an lvalue of
64
  type `CharT`. Operations on Traits shall not throw exceptions.
65
 
66
- The struct template
67
 
68
  ``` cpp
69
  template<class charT> struct char_traits;
70
  ```
71
 
72
  shall be provided in the header `<string>` as a basis for explicit
73
  specializations.
74
 
75
- ### traits typedefs <a id="char.traits.typedefs">[[char.traits.typedefs]]</a>
76
 
77
  ``` cpp
78
- typedef CHAR_T char_type;
79
  ```
80
 
81
  The type `char_type` is used to refer to the character container type in
82
  the implementation of the library classes defined in  [[string.classes]]
83
  and Clause  [[input.output]].
84
 
85
  ``` cpp
86
- typedef INT_T int_type;
87
  ```
88
 
89
  *Requires:* For a certain character container type `char_type`, a
90
  related container type `INT_T` shall be a type or class which can
91
  represent all of the valid characters converted from the corresponding
@@ -93,25 +94,25 @@ represent all of the valid characters converted from the corresponding
93
  `int_type` represents a character container type which can hold
94
  end-of-file to be used as a return type of the iostream class member
95
  functions.[^1]
96
 
97
  ``` cpp
98
- typedef implementation-defined off_type;
99
- typedef implementation-defined pos_type;
100
  ```
101
 
102
  *Requires:* Requirements for `off_type` and `pos_type` are described
103
  in  [[iostreams.limits.pos]] and [[iostream.forward]].
104
 
105
  ``` cpp
106
- typedef STATE_T state_type;
107
  ```
108
 
109
  *Requires:* `state_type` shall meet the requirements of `CopyAssignable`
110
- (Table  [[copyassignable]]), `CopyConstructible`
111
- (Table  [[copyconstructible]]), and `DefaultConstructible`
112
- (Table  [[defaultconstructible]]) types.
113
 
114
  ### `char_traits` specializations <a id="char.traits.specializations">[[char.traits.specializations]]</a>
115
 
116
  ``` cpp
117
  namespace std {
@@ -120,35 +121,35 @@ namespace std {
120
  template<> struct char_traits<char32_t>;
121
  template<> struct char_traits<wchar_t>;
122
  }
123
  ```
124
 
125
- The header `<string>` shall define four specializations of the template
126
- struct `char_traits`: `char_traits<{}char>`, `char_traits<char16_t>`,
127
  `char_traits<char32_t>`, and `char_traits<wchar_t>`.
128
 
129
  The requirements for the members of these specializations are given in
130
  Clause  [[char.traits.require]].
131
 
132
  #### `struct char_traits<char>` <a id="char.traits.specializations.char">[[char.traits.specializations.char]]</a>
133
 
134
  ``` cpp
135
  namespace std {
136
  template<> struct char_traits<char> {
137
- typedef char char_type;
138
- typedef int int_type;
139
- typedef streamoff off_type;
140
- typedef streampos pos_type;
141
- typedef mbstate_t state_type;
142
 
143
- static void assign(char_type& c1, const char_type& c2) noexcept;
144
  static constexpr bool eq(char_type c1, char_type c2) noexcept;
145
  static constexpr bool lt(char_type c1, char_type c2) noexcept;
146
 
147
- static int compare(const char_type* s1, const char_type* s2, size_t n);
148
- static size_t length(const char_type* s);
149
- static const char_type* find(const char_type* s, size_t n,
150
  const char_type& a);
151
  static char_type* move(char_type* s1, const char_type* s2, size_t n);
152
  static char_type* copy(char_type* s1, const char_type* s2, size_t n);
153
  static char_type* assign(char_type* s, size_t n, char_type a);
154
 
@@ -178,32 +179,32 @@ the conversion states that can occur in an *implementation-defined* set
178
  of supported multibyte character encoding rules.
179
 
180
  The two-argument member `assign` shall be defined identically to the
181
  built-in operator `=`. The two-argument members `eq` and `lt` shall be
182
  defined identically to the built-in operators `==` and `<` for type
183
- `unsigned` `char`.
184
 
185
  The member `eof()` shall return `EOF`.
186
 
187
  #### `struct char_traits<char16_t>` <a id="char.traits.specializations.char16_t">[[char.traits.specializations.char16_t]]</a>
188
 
189
  ``` cpp
190
  namespace std {
191
  template<> struct char_traits<char16_t> {
192
- typedef char16_t char_type;
193
- typedef uint_least16_t int_type;
194
- typedef streamoff off_type;
195
- typedef u16streampos pos_type;
196
- typedef mbstate_t state_type;
197
 
198
- static void assign(char_type& c1, const char_type& c2) noexcept;
199
  static constexpr bool eq(char_type c1, char_type c2) noexcept;
200
  static constexpr bool lt(char_type c1, char_type c2) noexcept;
201
 
202
- static int compare(const char_type* s1, const char_type* s2, size_t n);
203
- static size_t length(const char_type* s);
204
- static const char_type* find(const char_type* s, size_t n,
205
  const char_type& a);
206
  static char_type* move(char_type* s1, const char_type* s2, size_t n);
207
  static char_type* copy(char_type* s1, const char_type* s2, size_t n);
208
  static char_type* assign(char_type* s, size_t n, char_type a);
209
 
@@ -215,12 +216,12 @@ namespace std {
215
  };
216
  }
217
  ```
218
 
219
  The type `u16streampos` shall be an *implementation-defined* type that
220
- satisfies the requirements for pos_type in  [[iostreams.limits.pos]] and
221
- [[iostream.forward]].
222
 
223
  The two-argument members `assign`, `eq`, and `lt` shall be defined
224
  identically to the built-in operators `=`, `==`, and `<` respectively.
225
 
226
  The member `eof()` shall return an *implementation-defined* constant
@@ -229,23 +230,23 @@ that cannot appear as a valid UTF-16 code unit.
229
  #### `struct char_traits<char32_t>` <a id="char.traits.specializations.char32_t">[[char.traits.specializations.char32_t]]</a>
230
 
231
  ``` cpp
232
  namespace std {
233
  template<> struct char_traits<char32_t> {
234
- typedef char32_t char_type;
235
- typedef uint_least32_t int_type;
236
- typedef streamoff off_type;
237
- typedef u32streampos pos_type;
238
- typedef mbstate_t state_type;
239
 
240
- static void assign(char_type& c1, const char_type& c2) noexcept;
241
  static constexpr bool eq(char_type c1, char_type c2) noexcept;
242
  static constexpr bool lt(char_type c1, char_type c2) noexcept;
243
 
244
- static int compare(const char_type* s1, const char_type* s2, size_t n);
245
- static size_t length(const char_type* s);
246
- static const char_type* find(const char_type* s, size_t n,
247
  const char_type& a);
248
  static char_type* move(char_type* s1, const char_type* s2, size_t n);
249
  static char_type* copy(char_type* s1, const char_type* s2, size_t n);
250
  static char_type* assign(char_type* s, size_t n, char_type a);
251
 
@@ -257,12 +258,12 @@ namespace std {
257
  };
258
  }
259
  ```
260
 
261
  The type `u32streampos` shall be an *implementation-defined* type that
262
- satisfies the requirements for pos_type in  [[iostreams.limits.pos]] and
263
- [[iostream.forward]].
264
 
265
  The two-argument members `assign`, `eq`, and `lt` shall be defined
266
  identically to the built-in operators `=`, `==`, and `<` respectively.
267
 
268
  The member `eof()` shall return an *implementation-defined* constant
@@ -271,23 +272,23 @@ that cannot appear as a Unicode code point.
271
  #### `struct char_traits<wchar_t>` <a id="char.traits.specializations.wchar.t">[[char.traits.specializations.wchar.t]]</a>
272
 
273
  ``` cpp
274
  namespace std {
275
  template<> struct char_traits<wchar_t> {
276
- typedef wchar_t char_type;
277
- typedef wint_t int_type;
278
- typedef streamoff off_type;
279
- typedef wstreampos pos_type;
280
- typedef mbstate_t state_type;
281
 
282
- static void assign(char_type& c1, const char_type& c2) noexcept;
283
  static constexpr bool eq(char_type c1, char_type c2) noexcept;
284
  static constexpr bool lt(char_type c1, char_type c2) noexcept;
285
 
286
- static int compare(const char_type* s1, const char_type* s2, size_t n);
287
- static size_t length(const char_type* s);
288
- static const char_type* find(const char_type* s, size_t n,
289
  const char_type& a);
290
  static char_type* move(char_type* s1, const char_type* s2, size_t n);
291
  static char_type* copy(char_type* s1, const char_type* s2, size_t n);
292
  static char_type* assign(char_type* s, size_t n, char_type a);
293
 
@@ -302,12 +303,12 @@ namespace std {
302
 
303
  The defined types for `int_type`, `pos_type`, and `state_type` shall be
304
  `wint_t`, `wstreampos`, and `mbstate_t` respectively.
305
 
306
  The type `wstreampos` shall be an *implementation-defined* type that
307
- satisfies the requirements for pos_type in  [[iostreams.limits.pos]] and
308
- [[iostream.forward]].
309
 
310
  The type `mbstate_t` is defined in `<cwchar>` and can represent any of
311
  the conversion states that can occur in an *implementation-defined* set
312
  of supported multibyte character encoding rules.
313
 
@@ -318,27 +319,28 @@ The member `eof()` shall return `WEOF`.
318
 
319
  ## String classes <a id="string.classes">[[string.classes]]</a>
320
 
321
  The header `<string>` defines the `basic_string` class template for
322
  manipulating varying-length sequences of char-like objects and four
323
- typedefs, `string`, `u16string`, `u32string`, and `wstring`, that name
324
- the specializations `basic_string<char>`, `basic_string<char16_t>`,
325
  `basic_string<char32_t>`, and `basic_string<{}wchar_t>`, respectively.
326
 
 
 
327
  ``` cpp
328
  #include <initializer_list>
329
 
330
  namespace std {
331
-
332
- // [char.traits], character traits:
333
  template<class charT> struct char_traits;
334
  template<> struct char_traits<char>;
335
  template<> struct char_traits<char16_t>;
336
  template<> struct char_traits<char32_t>;
337
  template<> struct char_traits<wchar_t>;
338
 
339
- // [basic.string], basic_string:
340
  template<class charT, class traits = char_traits<charT>,
341
  class Allocator = allocator<charT>>
342
  class basic_string;
343
 
344
  template<class charT, class traits, class Allocator>
@@ -441,16 +443,17 @@ namespace std {
441
  const charT* rhs);
442
  template<class charT, class traits, class Allocator>
443
  bool operator>=(const charT* lhs,
444
  const basic_string<charT, traits, Allocator>& rhs);
445
 
446
- // [string.special], swap:
447
  template<class charT, class traits, class Allocator>
448
  void swap(basic_string<charT, traits, Allocator>& lhs,
449
- basic_string<charT,traits,Allocator>& rhs);
 
450
 
451
- // [string.io], inserters and extractors:
452
  template<class charT, class traits, class Allocator>
453
  basic_istream<charT, traits>&
454
  operator>>(basic_istream<charT, traits>& is,
455
  basic_string<charT, traits, Allocator>& str);
456
  template<class charT, class traits, class Allocator>
@@ -475,16 +478,16 @@ namespace std {
475
  basic_istream<charT, traits>&
476
  getline(basic_istream<charT, traits>&& is,
477
  basic_string<charT, traits, Allocator>& str);
478
 
479
  // basic_string typedef names
480
- typedef basic_string<char> string;
481
- typedef basic_string<char16_t> u16string;
482
- typedef basic_string<char32_t> u32string;
483
- typedef basic_string<wchar_t> wstring;
484
 
485
- // [string.conversions], numeric conversions:
486
  int stoi(const string& str, size_t* idx = 0, int base = 10);
487
  long stol(const string& str, size_t* idx = 0, int base = 10);
488
  unsigned long stoul(const string& str, size_t* idx = 0, int base = 10);
489
  long long stoll(const string& str, size_t* idx = 0, int base = 10);
490
  unsigned long long stoull(const string& str, size_t* idx = 0, int base = 10);
@@ -517,32 +520,41 @@ namespace std {
517
  wstring to_wstring(unsigned long long val);
518
  wstring to_wstring(float val);
519
  wstring to_wstring(double val);
520
  wstring to_wstring(long double val);
521
 
522
- // [basic.string.hash], hash support:
523
  template<class T> struct hash;
524
  template<> struct hash<string>;
525
  template<> struct hash<u16string>;
526
  template<> struct hash<u32string>;
527
  template<> struct hash<wstring>;
528
 
 
 
 
 
 
 
 
 
 
 
 
529
  inline namespace literals {
530
  inline namespace string_literals {
531
-
532
- // [basic.string.literals], suffix for basic_string literals:
533
  string operator""s(const char* str, size_t len);
534
  u16string operator""s(const char16_t* str, size_t len);
535
  u32string operator""s(const char32_t* str, size_t len);
536
  wstring operator""s(const wchar_t* str, size_t len);
537
-
538
  }
539
  }
540
  }
541
  ```
542
 
543
- ## Class template `basic_string` <a id="basic.string">[[basic.string]]</a>
544
 
545
  The class template `basic_string` describes objects that can store a
546
  sequence consisting of a varying number of arbitrary char-like objects
547
  with the first element of the sequence at position zero. Such a sequence
548
  is also called a “string” if the type of the char-like objects that it
@@ -552,12 +564,12 @@ char-like objects held in a `basic_string` object is designated by
552
 
553
  The member functions of `basic_string` use an object of the `Allocator`
554
  class passed as a template parameter to allocate and free storage for
555
  the contained char-like objects.[^2]
556
 
557
- The iterators supported by `basic_string` are random access iterators (
558
- [[random.access.iterators]]).
559
 
560
  In all cases, `size() <= capacity()`.
561
 
562
  The functions described in this Clause can report two kinds of errors,
563
  each associated with an exception type:
@@ -572,33 +584,39 @@ namespace std {
572
  template<class charT, class traits = char_traits<charT>,
573
  class Allocator = allocator<charT>>
574
  class basic_string {
575
  public:
576
  // types:
577
- typedef traits traits_type;
578
- typedef typename traits::char_type value_type;
579
- typedef Allocator allocator_type;
580
- typedef typename allocator_traits<Allocator>::size_type size_type;
581
- typedef typename allocator_traits<Allocator>::difference_type difference_type;
 
 
 
 
582
 
583
- typedef value_type& reference;
584
- typedef const value_type& const_reference;
585
- typedef typename allocator_traits<Allocator>::pointer pointer;
586
- typedef typename allocator_traits<Allocator>::const_pointer const_pointer;
587
-
588
- typedef implementation-defined iterator; // See [container.requirements]
589
- typedef implementation-defined const_iterator; // See [container.requirements]
590
- typedef std::reverse_iterator<iterator> reverse_iterator;
591
- typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
592
  static const size_type npos = -1;
593
 
594
- // [string.cons], construct/copy/destroy:
595
- basic_string() : basic_string(Allocator()) { }
596
- explicit basic_string(const Allocator& a);
597
  basic_string(const basic_string& str);
598
  basic_string(basic_string&& str) noexcept;
599
- basic_string(const basic_string& str, size_type pos, size_type n = npos,
 
 
 
 
 
 
 
600
  const Allocator& a = Allocator());
601
  basic_string(const charT* s,
602
  size_type n, const Allocator& a = Allocator());
603
  basic_string(const charT* s, const Allocator& a = Allocator());
604
  basic_string(size_type n, charT c, const Allocator& a = Allocator());
@@ -609,16 +627,19 @@ namespace std {
609
  basic_string(const basic_string&, const Allocator&);
610
  basic_string(basic_string&&, const Allocator&);
611
 
612
  ~basic_string();
613
  basic_string& operator=(const basic_string& str);
614
- basic_string& operator=(basic_string&& str) noexcept;
 
 
 
615
  basic_string& operator=(const charT* s);
616
  basic_string& operator=(charT c);
617
  basic_string& operator=(initializer_list<charT>);
618
 
619
- // [string.iterators], iterators:
620
  iterator begin() noexcept;
621
  const_iterator begin() const noexcept;
622
  iterator end() noexcept;
623
  const_iterator end() const noexcept;
624
 
@@ -630,11 +651,11 @@ namespace std {
630
  const_iterator cbegin() const noexcept;
631
  const_iterator cend() const noexcept;
632
  const_reverse_iterator crbegin() const noexcept;
633
  const_reverse_iterator crend() const noexcept;
634
 
635
- // [string.capacity], capacity:
636
  size_type size() const noexcept;
637
  size_type length() const noexcept;
638
  size_type max_size() const noexcept;
639
  void resize(size_type n, charT c);
640
  void resize(size_type n);
@@ -642,51 +663,64 @@ namespace std {
642
  void reserve(size_type res_arg = 0);
643
  void shrink_to_fit();
644
  void clear() noexcept;
645
  bool empty() const noexcept;
646
 
647
- // [string.access], element access:
648
  const_reference operator[](size_type pos) const;
649
  reference operator[](size_type pos);
650
  const_reference at(size_type n) const;
651
  reference at(size_type n);
652
 
653
  const charT& front() const;
654
  charT& front();
655
  const charT& back() const;
656
  charT& back();
657
 
658
- // [string.modifiers], modifiers:
659
  basic_string& operator+=(const basic_string& str);
 
660
  basic_string& operator+=(const charT* s);
661
  basic_string& operator+=(charT c);
662
  basic_string& operator+=(initializer_list<charT>);
663
  basic_string& append(const basic_string& str);
664
  basic_string& append(const basic_string& str, size_type pos,
665
  size_type n = npos);
 
 
 
666
  basic_string& append(const charT* s, size_type n);
667
  basic_string& append(const charT* s);
668
  basic_string& append(size_type n, charT c);
669
  template<class InputIterator>
670
  basic_string& append(InputIterator first, InputIterator last);
671
  basic_string& append(initializer_list<charT>);
672
  void push_back(charT c);
673
 
674
  basic_string& assign(const basic_string& str);
675
- basic_string& assign(basic_string&& str) noexcept;
 
 
676
  basic_string& assign(const basic_string& str, size_type pos,
677
  size_type n = npos);
 
 
 
678
  basic_string& assign(const charT* s, size_type n);
679
  basic_string& assign(const charT* s);
680
  basic_string& assign(size_type n, charT c);
681
  template<class InputIterator>
682
  basic_string& assign(InputIterator first, InputIterator last);
683
  basic_string& assign(initializer_list<charT>);
684
 
685
- basic_string& insert(size_type pos1, const basic_string& str);
686
  basic_string& insert(size_type pos1, const basic_string& str,
687
  size_type pos2, size_type n = npos);
 
 
 
 
688
  basic_string& insert(size_type pos, const charT* s, size_type n);
689
  basic_string& insert(size_type pos, const charT* s);
690
  basic_string& insert(size_type pos, size_type n, charT c);
691
  iterator insert(const_iterator p, charT c);
692
  iterator insert(const_iterator p, size_type n, charT c);
@@ -703,18 +737,25 @@ namespace std {
703
  basic_string& replace(size_type pos1, size_type n1,
704
  const basic_string& str);
705
  basic_string& replace(size_type pos1, size_type n1,
706
  const basic_string& str,
707
  size_type pos2, size_type n2 = npos);
 
 
 
 
 
708
  basic_string& replace(size_type pos, size_type n1, const charT* s,
709
  size_type n2);
710
  basic_string& replace(size_type pos, size_type n1, const charT* s);
711
  basic_string& replace(size_type pos, size_type n1, size_type n2,
712
  charT c);
713
 
714
  basic_string& replace(const_iterator i1, const_iterator i2,
715
  const basic_string& str);
 
 
716
  basic_string& replace(const_iterator i1, const_iterator i2, const charT* s,
717
  size_type n);
718
  basic_string& replace(const_iterator i1, const_iterator i2, const charT* s);
719
  basic_string& replace(const_iterator i1, const_iterator i2,
720
  size_type n, charT c);
@@ -722,54 +763,76 @@ namespace std {
722
  basic_string& replace(const_iterator i1, const_iterator i2,
723
  InputIterator j1, InputIterator j2);
724
  basic_string& replace(const_iterator, const_iterator, initializer_list<charT>);
725
 
726
  size_type copy(charT* s, size_type n, size_type pos = 0) const;
727
- void swap(basic_string& str);
 
 
728
 
729
- // [string.ops], string operations:
730
  const charT* c_str() const noexcept;
731
  const charT* data() const noexcept;
 
 
732
  allocator_type get_allocator() const noexcept;
733
 
 
 
734
  size_type find (const basic_string& str, size_type pos = 0) const noexcept;
735
  size_type find (const charT* s, size_type pos, size_type n) const;
736
  size_type find (const charT* s, size_type pos = 0) const;
737
  size_type find (charT c, size_type pos = 0) const;
 
 
738
  size_type rfind(const basic_string& str, size_type pos = npos) const noexcept;
739
  size_type rfind(const charT* s, size_type pos, size_type n) const;
740
  size_type rfind(const charT* s, size_type pos = npos) const;
741
  size_type rfind(charT c, size_type pos = npos) const;
742
 
 
 
743
  size_type find_first_of(const basic_string& str,
744
  size_type pos = 0) const noexcept;
745
  size_type find_first_of(const charT* s,
746
  size_type pos, size_type n) const;
747
  size_type find_first_of(const charT* s, size_type pos = 0) const;
748
  size_type find_first_of(charT c, size_type pos = 0) const;
 
 
749
  size_type find_last_of (const basic_string& str,
750
  size_type pos = npos) const noexcept;
751
  size_type find_last_of (const charT* s,
752
  size_type pos, size_type n) const;
753
  size_type find_last_of (const charT* s, size_type pos = npos) const;
754
  size_type find_last_of (charT c, size_type pos = npos) const;
755
 
 
 
756
  size_type find_first_not_of(const basic_string& str,
757
  size_type pos = 0) const noexcept;
758
  size_type find_first_not_of(const charT* s, size_type pos,
759
  size_type n) const;
760
  size_type find_first_not_of(const charT* s, size_type pos = 0) const;
761
  size_type find_first_not_of(charT c, size_type pos = 0) const;
 
 
762
  size_type find_last_not_of (const basic_string& str,
763
  size_type pos = npos) const noexcept;
764
  size_type find_last_not_of (const charT* s, size_type pos,
765
  size_type n) const;
766
  size_type find_last_not_of (const charT* s,
767
  size_type pos = npos) const;
768
  size_type find_last_not_of (charT c, size_type pos = npos) const;
769
 
770
  basic_string substr(size_type pos = 0, size_type n = npos) const;
 
 
 
 
 
 
771
  int compare(const basic_string& str) const noexcept;
772
  int compare(size_type pos1, size_type n1,
773
  const basic_string& str) const;
774
  int compare(size_type pos1, size_type n1,
775
  const basic_string& str,
@@ -778,14 +841,21 @@ namespace std {
778
  int compare(size_type pos1, size_type n1,
779
  const charT* s) const;
780
  int compare(size_type pos1, size_type n1,
781
  const charT* s, size_type n2) const;
782
  };
 
 
 
 
 
 
 
783
  }
784
  ```
785
 
786
- ### `basic_string` general requirements <a id="string.require">[[string.require]]</a>
787
 
788
  If any operation would cause `size()` to exceed `max_size()`, that
789
  operation shall throw an exception object of type `length_error`.
790
 
791
  If any member function or operator of `basic_string` throws an
@@ -795,30 +865,28 @@ In every specialization `basic_string<charT, traits, Allocator>`, the
795
  type `allocator_traits<Allocator>::value_type` shall name the same type
796
  as `charT`. Every object of type
797
  `basic_string<charT, traits, Allocator>` shall use an object of type
798
  `Allocator` to allocate and free storage for the contained `charT`
799
  objects as needed. The `Allocator` object used shall be obtained as
800
- described in [[container.requirements.general]].
801
-
802
- The char-like objects in a `basic_string` object shall be stored
803
- contiguously. That is, for any `basic_string` object `s`, the identity
804
- `&*(s.begin() + n) == &*s.begin() + n` shall hold for all values of `n`
805
- such that `0 <= n < s.size()`.
806
 
807
  References, pointers, and iterators referring to the elements of a
808
  `basic_string` sequence may be invalidated by the following uses of that
809
  `basic_string` object:
810
 
811
  - as an argument to any standard library function taking a reference to
812
  non-const `basic_string` as an argument.[^3]
813
- - Calling non-const member functions, except `operator[]`, `at`,
814
  `front`, `back`, `begin`, `rbegin`, `end`, and `rend`.
815
 
816
- ### `basic_string` constructors and assignment operators <a id="string.cons">[[string.cons]]</a>
817
 
818
  ``` cpp
819
- explicit basic_string(const Allocator& a);
820
  ```
821
 
822
  *Effects:* Constructs an object of class `basic_string`. The
823
  postconditions of this function are indicated in
824
  Table  [[tab:strings.ctr.1]].
@@ -847,32 +915,65 @@ valid state with an unspecified value.
847
  | `data()` | points at the first element of an allocated copy of the array whose first element is pointed at by `str.data()` |
848
  | `size()` | `str.size()` |
849
  | `capacity()` | a value at least as large as `size()` |
850
 
851
  ``` cpp
852
- basic_string(const basic_string& str,
853
- size_type pos, size_type n = npos,
854
  const Allocator& a = Allocator());
855
  ```
856
 
857
- *Requires:* `pos <= str.size()`
 
 
 
 
 
 
 
 
 
858
 
859
  *Throws:* `out_of_range` if `pos > str.size()`.
860
 
861
  *Effects:* Constructs an object of class `basic_string` and determines
862
  the effective length `rlen` of the initial string value as the smaller
863
  of `n` and `str.size() - pos`, as indicated in
864
  Table  [[tab:strings.ctr.2]].
865
 
866
- **Table: `basic_string(const basic_string&, size_type, size_type, const Allocator&)` effects** <a id="tab:strings.ctr.2">[tab:strings.ctr.2]</a>
 
867
 
868
  | Element | Value |
869
  | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
870
  | `data()` | points at the first element of an allocated copy of `rlen` consecutive elements of the string controlled by `str` beginning at position `pos` |
871
  | `size()` | `rlen` |
872
  | `capacity()` | a value at least as large as `size()` |
873
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
874
  ``` cpp
875
  basic_string(const charT* s, size_type n,
876
  const Allocator& a = Allocator());
877
  ```
878
 
@@ -909,18 +1010,15 @@ indicated in Table  [[tab:strings.ctr.4]].
909
  | ------------ | ------------------------------------------------------------------------------------------------------ |
910
  | `data()` | points at the first element of an allocated copy of the array whose first element is pointed at by `s` |
911
  | `size()` | `traits::length(s)` |
912
  | `capacity()` | a value at least as large as `size()` |
913
 
914
-
915
- *Remarks:* Uses `traits::length()`.
916
-
917
  ``` cpp
918
  basic_string(size_type n, charT c, const Allocator& a = Allocator());
919
  ```
920
 
921
- *Requires:* `n < npos`
922
 
923
  *Effects:* Constructs an object of class `basic_string` and determines
924
  its initial string value by repeating the char-like object `c` for all
925
  `n` elements, as indicated in Table  [[tab:strings.ctr.5]].
926
 
@@ -936,14 +1034,14 @@ its initial string value by repeating the char-like object `c` for all
936
  template<class InputIterator>
937
  basic_string(InputIterator begin, InputIterator end,
938
  const Allocator& a = Allocator());
939
  ```
940
 
941
- *Effects:* If `InputIterator` is an integral type, equivalent to
942
 
943
  ``` cpp
944
- basic_string(static_cast<size_type>(begin), static_cast<value_type>(end), a)
945
  ```
946
 
947
  Otherwise constructs a string from the values in the range \[`begin`,
948
  `end`), as indicated in the Sequence Requirements table
949
  (see  [[sequence.reqmts]]).
@@ -962,11 +1060,11 @@ basic_string(basic_string&& str, const Allocator& alloc);
962
  *Effects:* Constructs an object of class `basic_string` as indicated in
963
  Table  [[tab:strings.ctr.6]]. The stored allocator is constructed from
964
  `alloc`. In the second form, `str` is left in a valid state with an
965
  unspecified value.
966
 
967
- **Table: `basic_string(const basic_string&, const Allocator&)` and
968
  `basic_string(basic_string&&, const Allocator&)` effects** <a id="tab:strings.ctr.6">[tab:strings.ctr.6]</a>
969
 
970
  | Element | Value |
971
  | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
972
  | `data()` | points at the first element of an allocated copy of the array whose first element is pointed at by the original value of `str.data()`. |
@@ -976,48 +1074,60 @@ unspecified value.
976
 
977
 
978
  *Throws:* The second form throws nothing if
979
  `alloc == str.get_allocator()`.
980
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
981
  ``` cpp
982
  basic_string& operator=(const basic_string& str);
983
  ```
984
 
985
  *Effects:* If `*this` and `str` are not the same object, modifies
986
  `*this` as shown in Table  [[tab:strings.op=]].
987
 
988
  If `*this` and `str` are the same object, the member has no effect.
989
 
990
- *Returns:* `*this`
991
 
992
  **Table: `operator=(const basic_string&)` effects** <a id="tab:strings.op=">[tab:strings.op=]</a>
993
 
994
  | Element | Value |
995
  | ------------ | --------------------------------------------------------------------------------------------------------------- |
996
  | `data()` | points at the first element of an allocated copy of the array whose first element is pointed at by `str.data()` |
997
  | `size()` | `str.size()` |
998
  | `capacity()` | a value at least as large as `size()` |
999
 
1000
  ``` cpp
1001
- basic_string& operator=(basic_string&& str) noexcept;
 
 
1002
  ```
1003
 
1004
- *Effects:* If `*this` and `str` are not the same object, modifies
1005
- `*this` as shown in Table  [[tab:strings.op=rv]]. A valid implementation
1006
- is `swap(str)`.
1007
 
1008
- If `*this` and `str` are the same object, the member has no effect.
1009
 
1010
- *Returns:* `*this`
1011
-
1012
- **Table: `operator=(basic_string&&)` effects** <a id="tab:strings.op=rv">[tab:strings.op=rv]</a>
1013
 
1014
- | Element | Value |
1015
- | ------------ | ---------------------------------------------------------------------- |
1016
- | `data()` | points at the array whose first element was pointed at by `str.data()` |
1017
- | `size()` | previous value of `str.size()` |
1018
- | `capacity()` | a value at least as large as `size()` |
1019
 
1020
  ``` cpp
1021
  basic_string& operator=(const charT* s);
1022
  ```
1023
 
@@ -1033,15 +1143,15 @@ basic_string& operator=(charT c);
1033
 
1034
  ``` cpp
1035
  basic_string& operator=(initializer_list<charT> il);
1036
  ```
1037
 
1038
- *Effects:* `*this = basic_string(il)`.
1039
 
1040
  *Returns:* `*this`.
1041
 
1042
- ### `basic_string` iterator support <a id="string.iterators">[[string.iterators]]</a>
1043
 
1044
  ``` cpp
1045
  iterator begin() noexcept;
1046
  const_iterator begin() const noexcept;
1047
  const_iterator cbegin() const noexcept;
@@ -1073,11 +1183,11 @@ const_reverse_iterator crend() const noexcept;
1073
  ```
1074
 
1075
  *Returns:* An iterator which is semantically equivalent to
1076
  `reverse_iterator(begin())`.
1077
 
1078
- ### `basic_string` capacity <a id="string.capacity">[[string.capacity]]</a>
1079
 
1080
  ``` cpp
1081
  size_type size() const noexcept;
1082
  ```
1083
 
@@ -1094,20 +1204,19 @@ size_type length() const noexcept;
1094
 
1095
  ``` cpp
1096
  size_type max_size() const noexcept;
1097
  ```
1098
 
1099
- *Returns:* The size of the largest possible string.
 
1100
 
1101
  *Complexity:* Constant time.
1102
 
1103
  ``` cpp
1104
  void resize(size_type n, charT c);
1105
  ```
1106
 
1107
- *Requires:* `n <= max_size()`
1108
-
1109
  *Throws:* `length_error` if `n > max_size()`.
1110
 
1111
  *Effects:* Alters the length of the string designated by `*this` as
1112
  follows:
1113
 
@@ -1121,11 +1230,11 @@ follows:
1121
 
1122
  ``` cpp
1123
  void resize(size_type n);
1124
  ```
1125
 
1126
- *Effects:* `resize(n,charT())`.
1127
 
1128
  ``` cpp
1129
  size_type capacity() const noexcept;
1130
  ```
1131
 
@@ -1138,24 +1247,37 @@ void reserve(size_type res_arg=0);
1138
  The member function `reserve()` is a directive that informs a
1139
  `basic_string` object of a planned change in size, so that it can manage
1140
  the storage allocation accordingly.
1141
 
1142
  *Effects:* After `reserve()`, `capacity()` is greater or equal to the
1143
- argument of `reserve`. Calling `reserve()` with a `res_arg` argument
1144
- less than `capacity()` is in effect a non-binding shrink request. A call
1145
- with `res_arg <= size()` is in effect a non-binding shrink-to-fit
1146
- request.
 
 
1147
 
1148
  *Throws:* `length_error` if `res_arg > max_size()`.[^4]
1149
 
1150
  ``` cpp
1151
  void shrink_to_fit();
1152
  ```
1153
 
1154
- *Remarks:* `shrink_to_fit` is a non-binding request to reduce
1155
- `capacity()` to `size()`. The request is non-binding to allow latitude
1156
- for implementation-specific optimizations.
 
 
 
 
 
 
 
 
 
 
 
1157
 
1158
  ``` cpp
1159
  void clear() noexcept;
1160
  ```
1161
 
@@ -1169,22 +1291,23 @@ erase(begin(), end());
1169
  bool empty() const noexcept;
1170
  ```
1171
 
1172
  *Returns:* `size() == 0`.
1173
 
1174
- ### `basic_string` element access <a id="string.access">[[string.access]]</a>
1175
 
1176
  ``` cpp
1177
  const_reference operator[](size_type pos) const;
1178
  reference operator[](size_type pos);
1179
  ```
1180
 
1181
  *Requires:* `pos <= size()`.
1182
 
1183
  *Returns:* `*(begin() + pos)` if `pos < size()`. Otherwise, returns a
1184
  reference to an object of type `charT` with value `charT()`, where
1185
- modifying the object leads to undefined behavior.
 
1186
 
1187
  *Throws:* Nothing.
1188
 
1189
  *Complexity:* Constant time.
1190
 
@@ -1200,36 +1323,44 @@ reference at(size_type pos);
1200
  ``` cpp
1201
  const charT& front() const;
1202
  charT& front();
1203
  ```
1204
 
1205
- *Requires:* `!empty()`
1206
 
1207
- *Effects:* Equivalent to `operator[](0)`.
1208
 
1209
  ``` cpp
1210
  const charT& back() const;
1211
  charT& back();
1212
  ```
1213
 
1214
- *Requires:* `!empty()`
1215
 
1216
- *Effects:* Equivalent to `operator[](size() - 1)`.
1217
 
1218
- ### `basic_string` modifiers <a id="string.modifiers">[[string.modifiers]]</a>
1219
 
1220
- #### `basic_string::operator+=` <a id="string::op+=">[[string::op+=]]</a>
1221
 
1222
  ``` cpp
1223
  basic_string&
1224
  operator+=(const basic_string& str);
1225
  ```
1226
 
1227
  *Effects:* Calls `append(str)`.
1228
 
1229
  *Returns:* `*this`.
1230
 
 
 
 
 
 
 
 
 
1231
  ``` cpp
1232
  basic_string& operator+=(const charT* s);
1233
  ```
1234
 
1235
  *Effects:* Calls `append(s)`.
@@ -1250,11 +1381,11 @@ basic_string& operator+=(initializer_list<charT> il);
1250
 
1251
  *Effects:* Calls `append(il)`.
1252
 
1253
  *Returns:* `*this`.
1254
 
1255
- #### `basic_string::append` <a id="string::append">[[string::append]]</a>
1256
 
1257
  ``` cpp
1258
  basic_string&
1259
  append(const basic_string& str);
1260
  ```
@@ -1266,20 +1397,42 @@ basic_string&
1266
  ``` cpp
1267
  basic_string&
1268
  append(const basic_string& str, size_type pos, size_type n = npos);
1269
  ```
1270
 
1271
- *Requires:* `pos <= str.size()`
1272
-
1273
  *Throws:* `out_of_range` if `pos > str.size()`.
1274
 
1275
  *Effects:* Determines the effective length `rlen` of the string to
1276
  append as the smaller of `n` and `str``.size() - ``pos` and calls
1277
  `append(str.data() + pos, rlen)`.
1278
 
1279
  *Returns:* `*this`.
1280
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1281
  ``` cpp
1282
  basic_string&
1283
  append(const charT* s, size_type n);
1284
  ```
1285
 
@@ -1318,11 +1471,12 @@ template<class InputIterator>
1318
  basic_string& append(InputIterator first, InputIterator last);
1319
  ```
1320
 
1321
  *Requires:* \[`first`, `last`) is a valid range.
1322
 
1323
- *Effects:* Equivalent to `append(basic_string(first, last))`.
 
1324
 
1325
  *Returns:* `*this`.
1326
 
1327
  ``` cpp
1328
  basic_string& append(initializer_list<charT> il);
@@ -1336,43 +1490,65 @@ basic_string& append(initializer_list<charT> il);
1336
  void push_back(charT c);
1337
  ```
1338
 
1339
  *Effects:* Equivalent to `append(static_cast<size_type>(1), c)`.
1340
 
1341
- #### `basic_string::assign` <a id="string::assign">[[string::assign]]</a>
1342
 
1343
  ``` cpp
1344
  basic_string& assign(const basic_string& str);
1345
  ```
1346
 
1347
- *Effects:* Equivalent to `assign(str, 0, npos)`.
1348
 
1349
  *Returns:* `*this`.
1350
 
1351
  ``` cpp
1352
- basic_string& assign(basic_string&& str) noexcept;
 
 
1353
  ```
1354
 
1355
- *Effects:* The function replaces the string controlled by `*this` with a
1356
- string of length `str.size()` whose elements are a copy of the string
1357
- controlled by `str`. A valid implementation is `swap(str)`.
1358
 
1359
  *Returns:* `*this`.
1360
 
1361
  ``` cpp
1362
  basic_string&
1363
  assign(const basic_string& str, size_type pos,
1364
  size_type n = npos);
1365
  ```
1366
 
1367
- *Requires:* `pos <= str.size()`
1368
-
1369
  *Throws:* `out_of_range` if `pos > str.size()`.
1370
 
1371
  *Effects:* Determines the effective length `rlen` of the string to
1372
  assign as the smaller of `n` and `str``.size() - ``pos` and calls
1373
- `assign(str.data() + pos rlen)`.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1374
 
1375
  *Returns:* `*this`.
1376
 
1377
  ``` cpp
1378
  basic_string& assign(const charT* s, size_type n);
@@ -1417,54 +1593,71 @@ basic_string& assign(size_type n, charT c);
1417
  ``` cpp
1418
  template<class InputIterator>
1419
  basic_string& assign(InputIterator first, InputIterator last);
1420
  ```
1421
 
1422
- *Effects:* Equivalent to `assign(basic_string(first, last))`.
 
1423
 
1424
  *Returns:* `*this`.
1425
 
1426
- #### `basic_string::insert` <a id="string::insert">[[string::insert]]</a>
1427
 
1428
  ``` cpp
1429
  basic_string&
1430
- insert(size_type pos1,
1431
  const basic_string& str);
1432
  ```
1433
 
1434
- *Requires:* `pos <= size()`.
1435
-
1436
- *Throws:* `out_of_range` if `pos > size()`.
1437
-
1438
- *Effects:* Calls `insert(pos, str.data(), str.size())`.
1439
-
1440
- *Returns:* `*this`.
1441
 
1442
  ``` cpp
1443
  basic_string&
1444
  insert(size_type pos1,
1445
  const basic_string& str,
1446
  size_type pos2, size_type n = npos);
1447
  ```
1448
 
1449
- *Requires:* `pos1 <= size()` and `pos2 <= str.size()`
1450
-
1451
  *Throws:* `out_of_range` if `pos1 > size()` or `pos2 > str.size()`.
1452
 
1453
  *Effects:* Determines the effective length `rlen` of the string to
1454
  insert as the smaller of `n` and `str.size() - pos2` and calls
1455
  `insert(pos1, str.data() + pos2, rlen)`.
1456
 
1457
  *Returns:* `*this`.
1458
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1459
  ``` cpp
1460
  basic_string&
1461
  insert(size_type pos, const charT* s, size_type n);
1462
  ```
1463
 
1464
- *Requires:* `s` points to an array of at least `n` elements of `charT`
1465
- and `pos <= size()`.
1466
 
1467
  *Throws:* `out_of_range` if `pos > size()` or `length_error` if
1468
  `size() + n > max_size()`.
1469
 
1470
  *Effects:* Replaces the string controlled by `*this` with a string of
@@ -1479,16 +1672,14 @@ by `*this`.
1479
  ``` cpp
1480
  basic_string&
1481
  insert(size_type pos, const charT* s);
1482
  ```
1483
 
1484
- *Requires:* `pos <= size()` and `s` points to an array of at least
1485
- `traits::length(s) + 1` elements of `charT`.
1486
 
1487
- *Effects:* Equivalent to `insert(pos, s, traits::length(s))`.
1488
-
1489
- *Returns:* `*this`.
1490
 
1491
  ``` cpp
1492
  basic_string&
1493
  insert(size_type pos, size_type n, charT c);
1494
  ```
@@ -1501,11 +1692,11 @@ basic_string&
1501
  iterator insert(const_iterator p, charT c);
1502
  ```
1503
 
1504
  *Requires:* `p` is a valid iterator on `*this`.
1505
 
1506
- *Effects:* inserts a copy of `c` before the character referred to by
1507
  `p`.
1508
 
1509
  *Returns:* An iterator which refers to the copy of the inserted
1510
  character.
1511
 
@@ -1513,11 +1704,11 @@ character.
1513
  iterator insert(const_iterator p, size_type n, charT c);
1514
  ```
1515
 
1516
  *Requires:* `p` is a valid iterator on `*this`.
1517
 
1518
- *Effects:* inserts `n` copies of `c` before the character referred to by
1519
  `p`.
1520
 
1521
  *Returns:* An iterator which refers to the copy of the first inserted
1522
  character, or `p` if `n == 0`.
1523
 
@@ -1528,32 +1719,30 @@ template<class InputIterator>
1528
 
1529
  *Requires:* `p` is a valid iterator on `*this`. `[first, last)` is a
1530
  valid range.
1531
 
1532
  *Effects:* Equivalent to
1533
- `insert(p - begin(), basic_string(first, last))`.
1534
 
1535
  *Returns:* An iterator which refers to the copy of the first inserted
1536
  character, or `p` if `first == last`.
1537
 
1538
  ``` cpp
1539
  iterator insert(const_iterator p, initializer_list<charT> il);
1540
  ```
1541
 
1542
- *Effects:* `insert(p, il.begin(), il.end())`.
1543
 
1544
  *Returns:* An iterator which refers to the copy of the first inserted
1545
  character, or `p` if `i1` is empty.
1546
 
1547
- #### `basic_string::erase` <a id="string::erase">[[string::erase]]</a>
1548
 
1549
  ``` cpp
1550
  basic_string& erase(size_type pos = 0, size_type n = npos);
1551
  ```
1552
 
1553
- *Requires:* `pos` ` <= size()`
1554
-
1555
  *Throws:* `out_of_range` if `pos` `> size()`.
1556
 
1557
  *Effects:* Determines the effective length `xlen` of the string to be
1558
  removed as the smaller of `n` and `size() - pos`.
1559
 
@@ -1569,11 +1758,11 @@ string controlled by `*this` beginning at position `pos + xlen`.
1569
  iterator erase(const_iterator p);
1570
  ```
1571
 
1572
  *Throws:* Nothing.
1573
 
1574
- *Effects:* removes the character referred to by `p`.
1575
 
1576
  *Returns:* An iterator which points to the element immediately following
1577
  `p` prior to the element being erased. If no such element exists,
1578
  `end()` is returned.
1579
 
@@ -1584,66 +1773,86 @@ iterator erase(const_iterator first, const_iterator last);
1584
  *Requires:* `first` and `last` are valid iterators on `*this`, defining
1585
  a range `[first, last)`.
1586
 
1587
  *Throws:* Nothing.
1588
 
1589
- *Effects:* removes the characters in the range `[first,last)`.
1590
 
1591
  *Returns:* An iterator which points to the element pointed to by `last`
1592
  prior to the other elements being erased. If no such element exists,
1593
  `end()` is returned.
1594
 
1595
  ``` cpp
1596
  void pop_back();
1597
  ```
1598
 
1599
- *Requires:* `!empty()`
1600
 
1601
  *Throws:* Nothing.
1602
 
1603
  *Effects:* Equivalent to `erase(size() - 1, 1)`.
1604
 
1605
- #### `basic_string::replace` <a id="string::replace">[[string::replace]]</a>
1606
 
1607
  ``` cpp
1608
  basic_string&
1609
  replace(size_type pos1, size_type n1,
1610
  const basic_string& str);
1611
  ```
1612
 
1613
- *Requires:* `pos1 <= size()`.
1614
-
1615
- *Throws:* `out_of_range` if `pos1 > size()`.
1616
-
1617
- *Effects:* Calls `replace(pos1, n1, str.data(), str.size())`.
1618
-
1619
- *Returns:* `*this`.
1620
 
1621
  ``` cpp
1622
  basic_string&
1623
  replace(size_type pos1, size_type n1,
1624
  const basic_string& str,
1625
  size_type pos2, size_type n2 = npos);
1626
  ```
1627
 
1628
- *Requires:* `pos1 <= size()` and `pos2 <= str.size()`.
1629
-
1630
  *Throws:* `out_of_range` if `pos1 > size()` or `pos2 > str.size()`.
1631
 
1632
  *Effects:* Determines the effective length `rlen` of the string to be
1633
  inserted as the smaller of `n2` and `str.size() - pos2` and calls
1634
  `replace(pos1, n1, str.data() + pos2, rlen)`.
1635
 
1636
  *Returns:* `*this`.
1637
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1638
  ``` cpp
1639
  basic_string&
1640
  replace(size_type pos1, size_type n1, const charT* s, size_type n2);
1641
  ```
1642
 
1643
- *Requires:* `pos1 <= size()` and `s` points to an array of at least `n2`
1644
- elements of `charT`.
1645
 
1646
  *Throws:* `out_of_range` if `pos1 > size()` or `length_error` if the
1647
  length of the resulting string would exceed `max_size()` (see below).
1648
 
1649
  *Effects:* Determines the effective length `xlen` of the string to be
@@ -1661,16 +1870,15 @@ string controlled by `*this` beginning at position `pos + xlen`.
1661
  ``` cpp
1662
  basic_string&
1663
  replace(size_type pos, size_type n, const charT* s);
1664
  ```
1665
 
1666
- *Requires:* `pos <= size()` and `s` points to an array of at least
1667
- `traits::length(s) + 1` elements of `charT`.
1668
 
1669
- *Effects:* Calls `replace(pos, n, s, traits::length(s))`.
1670
-
1671
- *Returns:* `*this`.
1672
 
1673
  ``` cpp
1674
  basic_string&
1675
  replace(size_type pos1, size_type n1,
1676
  size_type n2, charT c);
@@ -1688,10 +1896,21 @@ basic_string& replace(const_iterator i1, const_iterator i2, const basic_string&
1688
 
1689
  *Effects:* Calls `replace(i1 - begin(), i2 - i1, str)`.
1690
 
1691
  *Returns:* `*this`.
1692
 
 
 
 
 
 
 
 
 
 
 
 
1693
  ``` cpp
1694
  basic_string&
1695
  replace(const_iterator i1, const_iterator i2, const charT* s, size_type n);
1696
  ```
1697
 
@@ -1732,11 +1951,12 @@ template<class InputIterator>
1732
  ```
1733
 
1734
  *Requires:* \[`begin()`, `i1`), \[`i1`, `i2`) and \[`j1`, `j2`) are
1735
  valid ranges.
1736
 
1737
- *Effects:* Calls `replace(i1 - begin(), i2 - i1, basic_string(j1, j2))`.
 
1738
 
1739
  *Returns:* `*this`.
1740
 
1741
  ``` cpp
1742
  basic_string& replace(const_iterator i1, const_iterator i2,
@@ -1748,49 +1968,48 @@ basic_string& replace(const_iterator i1, const_iterator i2,
1748
  *Effects:* Calls
1749
  `replace(i1 - begin(), i2 - i1, il.begin(), il.size())`.
1750
 
1751
  *Returns:* `*this`.
1752
 
1753
- #### `basic_string::copy` <a id="string::copy">[[string::copy]]</a>
1754
 
1755
  ``` cpp
1756
  size_type copy(charT* s, size_type n, size_type pos = 0) const;
1757
  ```
1758
 
1759
- *Requires:* `pos <= size()`
1760
 
1761
  *Throws:* `out_of_range` if `pos > size()`.
1762
 
1763
- *Effects:* Determines the effective length `rlen` of the string to copy
1764
- as the smaller of `n` and `size() - pos`. `s` shall designate an array
1765
- of at least `rlen` elements.
1766
 
1767
- The function then replaces the string designated by `s` with a string of
1768
- length `rlen` whose elements are a copy of the string controlled by
1769
- `*this` beginning at position `pos`.
1770
 
1771
- The function does not append a null object to the string designated by
1772
- `s`.
1773
 
1774
  *Returns:* `rlen`.
1775
 
1776
- #### `basic_string::swap` <a id="string::swap">[[string::swap]]</a>
1777
 
1778
  ``` cpp
1779
- void swap(basic_string& s);
 
 
1780
  ```
1781
 
1782
- `*this` contains the same sequence of characters that was in `s`, `s`
1783
- contains the same sequence of characters that was in `*this`.
 
1784
 
1785
  *Throws:* Nothing.
1786
 
1787
  *Complexity:* Constant time.
1788
 
1789
- ### `basic_string` string operations <a id="string.ops">[[string.ops]]</a>
1790
 
1791
- #### `basic_string` accessors <a id="string.accessors">[[string.accessors]]</a>
1792
 
1793
  ``` cpp
1794
  const charT* c_str() const noexcept;
1795
  const charT* data() const noexcept;
1796
  ```
@@ -1801,379 +2020,462 @@ const charT* data() const noexcept;
1801
  *Complexity:* Constant time.
1802
 
1803
  *Requires:* The program shall not alter any of the values stored in the
1804
  character array.
1805
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1806
  ``` cpp
1807
  allocator_type get_allocator() const noexcept;
1808
  ```
1809
 
1810
  *Returns:* A copy of the `Allocator` object used to construct the string
1811
  or, if that allocator has been replaced, a copy of the most recent
1812
  replacement.
1813
 
1814
- #### `basic_string::find` <a id="string::find">[[string::find]]</a>
1815
 
1816
  ``` cpp
1817
- size_type find(const basic_string& str,
1818
- size_type pos = 0) const noexcept;
1819
  ```
1820
 
1821
  *Effects:* Determines the lowest position `xpos`, if possible, such that
1822
- both of the following conditions obtain:
1823
 
1824
- - `pos <= xpos` and `xpos + str.size() <= size()`;
1825
- - `traits::eq(at(xpos+I), str.at(I))` for all elements `I` of the string
1826
- controlled by `str`.
1827
 
1828
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
1829
  Otherwise, returns `npos`.
1830
 
1831
- *Remarks:* Uses `traits::eq()`.
 
 
 
 
 
1832
 
1833
  ``` cpp
1834
  size_type find(const charT* s, size_type pos, size_type n) const;
1835
  ```
1836
 
1837
- *Returns:* `find(basic_string(s,n),pos)`.
1838
 
1839
  ``` cpp
1840
  size_type find(const charT* s, size_type pos = 0) const;
1841
  ```
1842
 
1843
  *Requires:* `s` points to an array of at least `traits::length(s) + 1`
1844
  elements of `charT`.
1845
 
1846
- *Returns:* `find(basic_string(s), pos)`.
1847
 
1848
  ``` cpp
1849
  size_type find(charT c, size_type pos = 0) const;
1850
  ```
1851
 
1852
  *Returns:* `find(basic_string(1, c), pos)`.
1853
 
1854
- #### `basic_string::rfind` <a id="string::rfind">[[string::rfind]]</a>
1855
 
1856
  ``` cpp
1857
- size_type rfind(const basic_string& str,
1858
- size_type pos = npos) const noexcept;
1859
  ```
1860
 
1861
  *Effects:* Determines the highest position `xpos`, if possible, such
1862
- that both of the following conditions obtain:
1863
 
1864
- - `xpos <= pos` and `xpos + str.size() <= size()`;
1865
- - `traits::eq(at(xpos+I), str.at(I))` for all elements `I` of the string
1866
- controlled by `str`.
1867
 
1868
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
1869
  Otherwise, returns `npos`.
1870
 
1871
- *Remarks:* Uses `traits::eq()`.
 
 
 
 
 
1872
 
1873
  ``` cpp
1874
  size_type rfind(const charT* s, size_type pos, size_type n) const;
1875
  ```
1876
 
1877
- *Returns:* `rfind(basic_string(s, n), pos)`.
1878
 
1879
  ``` cpp
1880
  size_type rfind(const charT* s, size_type pos = npos) const;
1881
  ```
1882
 
1883
- *Requires:* s points to an array of at least `traits::length(s) + 1`
1884
  elements of `charT`.
1885
 
1886
- *Returns:* `rfind(basic_string(s), pos)`.
1887
 
1888
  ``` cpp
1889
  size_type rfind(charT c, size_type pos = npos) const;
1890
  ```
1891
 
1892
  *Returns:* `rfind(basic_string(1, c), pos)`.
1893
 
1894
- #### `basic_string::find_first_of` <a id="string::find.first.of">[[string::find.first.of]]</a>
1895
 
1896
  ``` cpp
1897
- size_type
1898
- find_first_of(const basic_string& str,
1899
- size_type pos = 0) const noexcept;
1900
  ```
1901
 
1902
  *Effects:* Determines the lowest position `xpos`, if possible, such that
1903
- both of the following conditions obtain:
1904
 
1905
  - `pos <= xpos` and `xpos < size()`;
1906
- - `traits::eq(at(xpos), str.at(I))` for some element `I` of the string
1907
- controlled by `str`.
1908
 
1909
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
1910
  Otherwise, returns `npos`.
1911
 
1912
- *Remarks:* Uses `traits::eq()`.
 
 
 
 
 
1913
 
1914
  ``` cpp
1915
- size_type
1916
- find_first_of(const charT* s, size_type pos, size_type n) const;
1917
  ```
1918
 
1919
- *Returns:* `find_first_of(basic_string(s, n), pos)`.
1920
 
1921
  ``` cpp
1922
  size_type find_first_of(const charT* s, size_type pos = 0) const;
1923
  ```
1924
 
1925
  *Requires:* `s` points to an array of at least `traits::length(s) + 1`
1926
  elements of `charT`.
1927
 
1928
- *Returns:* `find_first_of(basic_string(s), pos)`.
1929
 
1930
  ``` cpp
1931
  size_type find_first_of(charT c, size_type pos = 0) const;
1932
  ```
1933
 
1934
  *Returns:* `find_first_of(basic_string(1, c), pos)`.
1935
 
1936
- #### `basic_string::find_last_of` <a id="string::find.last.of">[[string::find.last.of]]</a>
1937
 
1938
  ``` cpp
1939
- size_type
1940
- find_last_of(const basic_string& str,
1941
- size_type pos = npos) const noexcept;
1942
  ```
1943
 
1944
  *Effects:* Determines the highest position `xpos`, if possible, such
1945
- that both of the following conditions obtain:
1946
 
1947
  - `xpos <= pos` and `xpos < size()`;
1948
- - `traits::eq(at(xpos), str.at(I))` for some element `I` of the string
1949
- controlled by `str`.
1950
 
1951
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
1952
  Otherwise, returns `npos`.
1953
 
1954
- *Remarks:* Uses `traits::eq()`.
 
 
 
 
 
1955
 
1956
  ``` cpp
1957
  size_type find_last_of(const charT* s, size_type pos, size_type n) const;
1958
  ```
1959
 
1960
- *Returns:* `find_last_of(basic_string(s, n), pos)`.
1961
 
1962
  ``` cpp
1963
  size_type find_last_of(const charT* s, size_type pos = npos) const;
1964
  ```
1965
 
1966
  *Requires:* `s` points to an array of at least `traits::length(s) + 1`
1967
  elements of `charT`.
1968
 
1969
- *Returns:* `find_last_of(basic_string(s), pos)`.
1970
 
1971
  ``` cpp
1972
  size_type find_last_of(charT c, size_type pos = npos) const;
1973
  ```
1974
 
1975
  *Returns:* `find_last_of(basic_string(1, c), pos)`.
1976
 
1977
- #### `basic_string::find_first_not_of` <a id="string::find.first.not.of">[[string::find.first.not.of]]</a>
1978
 
1979
  ``` cpp
1980
- size_type
1981
- find_first_not_of(const basic_string& str,
1982
  size_type pos = 0) const noexcept;
1983
  ```
1984
 
1985
  *Effects:* Determines the lowest position `xpos`, if possible, such that
1986
- both of the following conditions obtain:
1987
 
1988
  - `pos <= xpos` and `xpos < size()`;
1989
- - `traits::eq(at(xpos), str.at(I))` for no element `I` of the string
1990
- controlled by `str`.
1991
 
1992
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
1993
  Otherwise, returns `npos`.
1994
 
1995
- *Remarks:* Uses `traits::eq()`.
 
 
 
 
 
 
 
 
1996
 
1997
  ``` cpp
1998
- size_type
1999
- find_first_not_of(const charT* s, size_type pos, size_type n) const;
2000
  ```
2001
 
2002
- *Returns:* `find_first_not_of(basic_string(s, n), pos)`.
 
2003
 
2004
  ``` cpp
2005
  size_type find_first_not_of(const charT* s, size_type pos = 0) const;
2006
  ```
2007
 
2008
  *Requires:* `s` points to an array of at least `traits::length(s) + 1`
2009
  elements of `charT`.
2010
 
2011
- *Returns:* `find_first_not_of(basic_string(s), pos)`.
 
2012
 
2013
  ``` cpp
2014
  size_type find_first_not_of(charT c, size_type pos = 0) const;
2015
  ```
2016
 
2017
  *Returns:* `find_first_not_of(basic_string(1, c), pos)`.
2018
 
2019
- #### `basic_string::find_last_not_of` <a id="string::find.last.not.of">[[string::find.last.not.of]]</a>
2020
 
2021
  ``` cpp
2022
- size_type
2023
- find_last_not_of(const basic_string& str,
2024
  size_type pos = npos) const noexcept;
2025
  ```
2026
 
2027
  *Effects:* Determines the highest position `xpos`, if possible, such
2028
- that both of the following conditions obtain:
2029
 
2030
  - `xpos <= pos` and `xpos < size()`;
2031
- - `traits::eq(at(xpos), str.at(I))` for no element `I` of the string
2032
- controlled by `str`.
2033
 
2034
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
2035
  Otherwise, returns `npos`.
2036
 
2037
- *Remarks:* Uses `traits::eq()`.
 
 
 
 
 
 
 
 
2038
 
2039
  ``` cpp
2040
- size_type find_last_not_of(const charT* s, size_type pos,
2041
- size_type n) const;
2042
  ```
2043
 
2044
- *Returns:* `find_last_not_of(basic_string(s, n), pos)`.
 
2045
 
2046
  ``` cpp
2047
  size_type find_last_not_of(const charT* s, size_type pos = npos) const;
2048
  ```
2049
 
2050
  *Requires:* `s` points to an array of at least `traits::length(s) + 1`
2051
  elements of `charT`.
2052
 
2053
- *Returns:* `find_last_not_of(basic_string(s), pos)`.
2054
 
2055
  ``` cpp
2056
  size_type find_last_not_of(charT c, size_type pos = npos) const;
2057
  ```
2058
 
2059
  *Returns:* `find_last_not_of(basic_string(1, c), pos)`.
2060
 
2061
- #### `basic_string::substr` <a id="string::substr">[[string::substr]]</a>
2062
 
2063
  ``` cpp
2064
  basic_string substr(size_type pos = 0, size_type n = npos) const;
2065
  ```
2066
 
2067
- *Requires:* `pos <= size()`
2068
-
2069
  *Throws:* `out_of_range` if `pos > size()`.
2070
 
2071
  *Effects:* Determines the effective length `rlen` of the string to copy
2072
  as the smaller of `n` and `size() - pos`.
2073
 
2074
  *Returns:* `basic_string(data()+pos, rlen)`.
2075
 
2076
- #### `basic_string::compare` <a id="string::compare">[[string::compare]]</a>
2077
 
2078
  ``` cpp
2079
- int compare(const basic_string& str) const noexcept;
2080
  ```
2081
 
2082
- *Effects:* Determines the effective length *rlen* of the strings to
2083
- compare as the smallest of `size()` and `str.size()`. The function then
2084
  compares the two strings by calling
2085
- `traits::compare(data(), str.data(), rlen)`.
2086
 
2087
  *Returns:* The nonzero result if the result of the comparison is
2088
  nonzero. Otherwise, returns a value as indicated in
2089
  Table  [[tab:strings.compare]].
2090
 
2091
  **Table: `compare()` results** <a id="tab:strings.compare">[tab:strings.compare]</a>
2092
 
2093
  | Condition | Return Value |
2094
- | ---------------------- | ------------ |
2095
- | `size() < str.size()` | `< 0` |
2096
- | `size() == str.size()` | ` 0` |
2097
- | `size() > str.size()` | `> 0` |
2098
 
2099
  ``` cpp
2100
- int compare(size_type pos1, size_type n1,
2101
- const basic_string& str) const;
2102
  ```
2103
 
2104
- *Returns:* `basic_string(*this,pos1,n1).compare(str)`.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2105
 
2106
  ``` cpp
2107
  int compare(size_type pos1, size_type n1,
2108
  const basic_string& str,
2109
  size_type pos2, size_type n2 = npos) const;
2110
  ```
2111
 
2112
- *Returns:*
2113
- `basic_string(*this, pos1, n1).compare(basic_string(str, pos2, n2))`.
 
 
 
2114
 
2115
  ``` cpp
2116
  int compare(const charT* s) const;
2117
  ```
2118
 
2119
  *Returns:* `compare(basic_string(s))`.
2120
 
2121
  ``` cpp
2122
- int compare(size_type pos, size_type n1,
2123
- const charT* s) const;
2124
  ```
2125
 
2126
  *Returns:* `basic_string(*this, pos, n1).compare(basic_string(s))`.
2127
 
2128
  ``` cpp
2129
- int compare(size_type pos, size_type n1,
2130
- const charT* s, size_type n2) const;
2131
  ```
2132
 
2133
  *Returns:* `basic_string(*this, pos, n1).compare(basic_string(s, n2))`.
2134
 
2135
  ### `basic_string` non-member functions <a id="string.nonmembers">[[string.nonmembers]]</a>
2136
 
2137
- #### `operator+` <a id="string::op+">[[string::op+]]</a>
2138
 
2139
  ``` cpp
2140
  template<class charT, class traits, class Allocator>
2141
  basic_string<charT, traits, Allocator>
2142
  operator+(const basic_string<charT, traits, Allocator>& lhs,
2143
  const basic_string<charT, traits, Allocator>& rhs);
2144
  ```
2145
 
2146
- *Returns:* `basic_string<charT,traits,Allocator>(lhs).append(rhs)`
2147
 
2148
  ``` cpp
2149
  template<class charT, class traits, class Allocator>
2150
  basic_string<charT, traits, Allocator>
2151
  operator+(basic_string<charT, traits, Allocator>&& lhs,
2152
  const basic_string<charT, traits, Allocator>& rhs);
2153
  ```
2154
 
2155
- *Returns:* `std::move(lhs.append(rhs))`
2156
 
2157
  ``` cpp
2158
  template<class charT, class traits, class Allocator>
2159
  basic_string<charT, traits, Allocator>
2160
  operator+(const basic_string<charT, traits, Allocator>& lhs,
2161
  basic_string<charT, traits, Allocator>&& rhs);
2162
  ```
2163
 
2164
- *Returns:* `std::move(rhs.insert(0, lhs))`
2165
 
2166
  ``` cpp
2167
  template<class charT, class traits, class Allocator>
2168
  basic_string<charT, traits, Allocator>
2169
  operator+(basic_string<charT, traits, Allocator>&& lhs,
2170
  basic_string<charT, traits, Allocator>&& rhs);
2171
  ```
2172
 
2173
- *Returns:* `std::move(lhs.append(rhs))` Or equivalently
2174
- `std::move(rhs.insert(0, lhs))`
 
 
2175
 
2176
  ``` cpp
2177
  template<class charT, class traits, class Allocator>
2178
  basic_string<charT, traits, Allocator>
2179
  operator+(const charT* lhs,
@@ -2251,11 +2553,11 @@ template<class charT, class traits, class Allocator>
2251
  charT rhs);
2252
  ```
2253
 
2254
  *Returns:* `std::move(lhs.append(1, rhs))`.
2255
 
2256
- #### `operator==` <a id="string::operator==">[[string::operator==]]</a>
2257
 
2258
  ``` cpp
2259
  template<class charT, class traits, class Allocator>
2260
  bool operator==(const basic_string<charT, traits, Allocator>& lhs,
2261
  const basic_string<charT, traits, Allocator>& rhs) noexcept;
@@ -2280,11 +2582,11 @@ template<class charT, class traits, class Allocator>
2280
  *Requires:* `rhs` points to an array of at least
2281
  `traits::length(rhs) + 1` elements of `charT`.
2282
 
2283
  *Returns:* `lhs.compare(rhs) == 0`.
2284
 
2285
- #### `operator!=` <a id="string::op!=">[[string::op!=]]</a>
2286
 
2287
  ``` cpp
2288
  template<class charT, class traits, class Allocator>
2289
  bool operator!=(const basic_string<charT, traits, Allocator>& lhs,
2290
  const basic_string<charT, traits, Allocator>& rhs) noexcept;
@@ -2309,11 +2611,11 @@ template<class charT, class traits, class Allocator>
2309
  *Requires:* `rhs` points to an array of at least
2310
  `traits::length(rhs) + 1` elements of `charT`.
2311
 
2312
  *Returns:* `lhs.compare(rhs) != 0`.
2313
 
2314
- #### `operator<` <a id="string::op<">[[string::op<]]</a>
2315
 
2316
  ``` cpp
2317
  template<class charT, class traits, class Allocator>
2318
  bool operator< (const basic_string<charT, traits, Allocator>& lhs,
2319
  const basic_string<charT, traits, Allocator>& rhs) noexcept;
@@ -2335,11 +2637,11 @@ template<class charT, class traits, class Allocator>
2335
  const charT* rhs);
2336
  ```
2337
 
2338
  *Returns:* `lhs.compare(rhs) < 0`.
2339
 
2340
- #### `operator>` <a id="string::op>">[[string::op>]]</a>
2341
 
2342
  ``` cpp
2343
  template<class charT, class traits, class Allocator>
2344
  bool operator> (const basic_string<charT, traits, Allocator>& lhs,
2345
  const basic_string<charT, traits, Allocator>& rhs) noexcept;
@@ -2361,11 +2663,11 @@ template<class charT, class traits, class Allocator>
2361
  const charT* rhs);
2362
  ```
2363
 
2364
  *Returns:* `lhs.compare(rhs) > 0`.
2365
 
2366
- #### `operator<=` <a id="string::op<=">[[string::op<=]]</a>
2367
 
2368
  ``` cpp
2369
  template<class charT, class traits, class Allocator>
2370
  bool operator<=(const basic_string<charT, traits, Allocator>& lhs,
2371
  const basic_string<charT, traits, Allocator>& rhs) noexcept;
@@ -2387,11 +2689,11 @@ template<class charT, class traits, class Allocator>
2387
  const charT* rhs);
2388
  ```
2389
 
2390
  *Returns:* `lhs.compare(rhs) <= 0`.
2391
 
2392
- #### `operator>=` <a id="string::op>=">[[string::op>=]]</a>
2393
 
2394
  ``` cpp
2395
  template<class charT, class traits, class Allocator>
2396
  bool operator>=(const basic_string<charT, traits, Allocator>& lhs,
2397
  const basic_string<charT, traits, Allocator>& rhs) noexcept;
@@ -2418,14 +2720,15 @@ template<class charT, class traits, class Allocator>
2418
  #### `swap` <a id="string.special">[[string.special]]</a>
2419
 
2420
  ``` cpp
2421
  template<class charT, class traits, class Allocator>
2422
  void swap(basic_string<charT, traits, Allocator>& lhs,
2423
- basic_string<charT,traits,Allocator>& rhs);
 
2424
  ```
2425
 
2426
- *Effects:* Equivalent to `lhs.swap(rhs);`
2427
 
2428
  #### Inserters and extractors <a id="string.io">[[string.io]]</a>
2429
 
2430
  ``` cpp
2431
  template<class charT, class traits, class Allocator>
@@ -2434,47 +2737,40 @@ template<class charT, class traits, class Allocator>
2434
  basic_string<charT, traits, Allocator>& str);
2435
  ```
2436
 
2437
  *Effects:* Behaves as a formatted input
2438
  function ([[istream.formatted.reqmts]]). After constructing a `sentry`
2439
- object, if the sentry converts to true, calls `str.erase()` and then
2440
  extracts characters from `is` and appends them to `str` as if by calling
2441
  `str.append(1, c)`. If `is.width()` is greater than zero, the maximum
2442
  number `n` of characters appended is `is.width()`; otherwise `n` is
2443
  `str.max_size()`. Characters are extracted and appended until any of the
2444
  following occurs:
2445
 
2446
  - *n* characters are stored;
2447
  - end-of-file occurs on the input sequence;
2448
- - `isspace(c,is.getloc())` is true for the next available input
2449
  character *c*.
2450
 
2451
  After the last character (if any) is extracted, `is.width(0)` is called
2452
- and the `sentry` object `k` is destroyed.
2453
 
2454
  If the function extracts no characters, it calls
2455
  `is.setstate(ios::failbit)`, which may throw
2456
  `ios_base::failure` ([[iostate.flags]]).
2457
 
2458
- *Returns:* `is`
2459
 
2460
  ``` cpp
2461
  template<class charT, class traits, class Allocator>
2462
  basic_ostream<charT, traits>&
2463
  operator<<(basic_ostream<charT, traits>& os,
2464
  const basic_string<charT, traits, Allocator>& str);
2465
  ```
2466
 
2467
- *Effects:* Behaves as a formatted output
2468
- function ([[ostream.formatted.reqmts]]) of `os`. Forms a character
2469
- sequence `seq`, initially consisting of the elements defined by the
2470
- range \[`str.begin(), str.end()`). Determines padding for `seq` as
2471
- described in  [[ostream.formatted.reqmts]]. Then inserts `seq` as if by
2472
- calling `os.rdbuf()->sputn(seq, n)`, where `n` is the larger of
2473
- `os.width()` and `str.size()`; then calls `os.width(0)`.
2474
-
2475
- *Returns:* `os`
2476
 
2477
  ``` cpp
2478
  template<class charT, class traits, class Allocator>
2479
  basic_istream<charT, traits>&
2480
  getline(basic_istream<charT, traits>& is,
@@ -2488,11 +2784,11 @@ template<class charT, class traits, class Allocator>
2488
  ```
2489
 
2490
  *Effects:* Behaves as an unformatted input
2491
  function ([[istream.unformatted]]), except that it does not affect the
2492
  value returned by subsequent calls to `basic_istream<>::gcount()`. After
2493
- constructing a `sentry` object, if the sentry converts to true, calls
2494
  `str.erase()` and then extracts characters from `is` and appends them to
2495
  `str` as if by calling `str.append(1, c)` until any of the following
2496
  occurs:
2497
 
2498
  - end-of-file occurs on the input sequence (in which case, the `getline`
@@ -2501,11 +2797,11 @@ occurs:
2501
  which case, *c* is extracted but not appended) ([[iostate.flags]])
2502
  - `str.max_size()` characters are stored (in which case, the function
2503
  calls `is.setstate(ios_base::failbit))` ([[iostate.flags]])
2504
 
2505
  The conditions are tested in the order shown. In any case, after the
2506
- last character is extracted, the `sentry` object `k` is destroyed.
2507
 
2508
  If the function extracts no characters, it calls
2509
  `is.setstate(ios_base::failbit)` which may throw
2510
  `ios_base::failure` ([[iostate.flags]]).
2511
 
@@ -2520,13 +2816,13 @@ template<class charT, class traits, class Allocator>
2520
  basic_istream<charT, traits>&
2521
  getline(basic_istream<charT, traits>&& is,
2522
  basic_string<charT, traits, Allocator>& str);
2523
  ```
2524
 
2525
- *Returns:* `getline(is,str,is.widen(’\n’))`
2526
 
2527
- ## Numeric conversions <a id="string.conversions">[[string.conversions]]</a>
2528
 
2529
  ``` cpp
2530
  int stoi(const string& str, size_t* idx = 0, int base = 10);
2531
  long stol(const string& str, size_t* idx = 0, int base = 10);
2532
  unsigned long stoul(const string& str, size_t* idx = 0, int base = 10);
@@ -2556,24 +2852,25 @@ representable values for the return type.
2556
  float stof(const string& str, size_t* idx = 0);
2557
  double stod(const string& str, size_t* idx = 0);
2558
  long double stold(const string& str, size_t* idx = 0);
2559
  ```
2560
 
2561
- *Effects:* the first two functions call `strtod(str.c_str(), ptr)` and
2562
- the third function calls `strtold(str.c_str(), ptr)`. Each function
2563
- returns the converted result, if any. The argument `ptr` designates a
2564
- pointer to an object internal to the function that is used to determine
2565
- what to store at `*idx`. If the function does not throw an exception and
2566
- `idx != 0`, the function stores in `*idx` the index of the first
2567
- unconverted element of `str`.
2568
 
2569
  *Returns:* The converted result.
2570
 
2571
- *Throws:* `invalid_argument` if `strtod` or `strtold` reports that no
2572
- conversion could be performed. Throws `out_of_range` if `strtod` or
2573
- `strtold` sets `errno` to `ERANGE` or if the converted value is outside
2574
- the range of representable values for the return type.
 
2575
 
2576
  ``` cpp
2577
  string to_string(int val);
2578
  string to_string(unsigned val);
2579
  string to_string(long val);
@@ -2621,23 +2918,23 @@ representable values for the return type.
2621
  float stof(const wstring& str, size_t* idx = 0);
2622
  double stod(const wstring& str, size_t* idx = 0);
2623
  long double stold(const wstring& str, size_t* idx = 0);
2624
  ```
2625
 
2626
- *Effects:* the first two functions call `wcstod(str.c_str(), ptr)` and
2627
- the third function calls `wcstold(str.c_str(), ptr)`. Each function
2628
- returns the converted result, if any. The argument `ptr` designates a
2629
- pointer to an object internal to the function that is used to determine
2630
- what to store at `*idx`. If the function does not throw an exception and
2631
- `idx != 0`, the function stores in `*idx` the index of the first
2632
- unconverted element of `str`.
2633
 
2634
  *Returns:* The converted result.
2635
 
2636
- *Throws:* `invalid_argument` if `wcstod` or `wcstold` reports that no
2637
- conversion could be performed. Throws `out_of_range` if `wcstod` or
2638
- `wcstold` sets `errno` to `ERANGE`.
2639
 
2640
  ``` cpp
2641
  wstring to_wstring(int val);
2642
  wstring to_wstring(unsigned val);
2643
  wstring to_wstring(long val);
@@ -2654,284 +2951,1216 @@ character representation of the value of its argument that would be
2654
  generated by calling `swprintf(buf, buffsz, fmt, val)` with a format
2655
  specifier of `L"%d"`, `L"%u"`, `L"%ld"`, `L"%lu"`, `L"%lld"`, `L"%llu"`,
2656
  `L"%f"`, `L"%f"`, or `L"%Lf"`, respectively, where `buf` designates an
2657
  internal character buffer of sufficient size `buffsz`.
2658
 
2659
- ## Hash support <a id="basic.string.hash">[[basic.string.hash]]</a>
2660
 
2661
  ``` cpp
2662
  template<> struct hash<string>;
2663
  template<> struct hash<u16string>;
2664
  template<> struct hash<u32string>;
2665
  template<> struct hash<wstring>;
2666
  ```
2667
 
2668
- The template specializations shall meet the requirements of class
2669
- template `hash` ([[unord.hash]]).
 
2670
 
2671
- ## Suffix for `basic_string` literals <a id="basic.string.literals">[[basic.string.literals]]</a>
2672
 
2673
  ``` cpp
2674
  string operator""s(const char* str, size_t len);
2675
  ```
2676
 
2677
- *Returns:* `string{str,len}`
2678
 
2679
  ``` cpp
2680
  u16string operator""s(const char16_t* str, size_t len);
2681
  ```
2682
 
2683
- *Returns:* `u16string{str,len}`
2684
 
2685
  ``` cpp
2686
  u32string operator""s(const char32_t* str, size_t len);
2687
  ```
2688
 
2689
- *Returns:* `u32string{str,len}`
2690
 
2691
  ``` cpp
2692
  wstring operator""s(const wchar_t* str, size_t len);
2693
  ```
2694
 
2695
- *Returns:* `wstring{str,len}`
2696
 
2697
- The same suffix `s` is used for `chrono::duration` literals denoting
2698
- seconds but there is no conflict, since duration suffixes apply to
2699
- numbers and string literal suffixes apply to character array literals.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2700
 
2701
  ## Null-terminated sequence utilities <a id="c.strings">[[c.strings]]</a>
2702
 
2703
- Tables  [[tab:strings.hdr.cctype]], [[tab:strings.hdr.cwctype]],
2704
- [[tab:strings.hdr.cstring]], [[tab:strings.hdr.cwchar]],
2705
- [[tab:strings.hdr.cstdlib]], and [[tab:strings.hdr.cuchar]] describe
2706
- headers `<cctype>`, `<cwctype>`, `<cstring>`, `<cwchar>`, `<cstdlib>`
2707
- (character conversions), and `<cuchar>`, respectively.
2708
-
2709
- The contents of these headers shall be the same as the Standard C
2710
- Library headers `<ctype.h>`, `<wctype.h>`, `<string.h>`, `<wchar.h>`,
2711
- and `<stdlib.h>` and the C Unicode TR header `<uchar.h>`, respectively,
2712
- with the following modifications:
2713
-
2714
- The headers shall not define the types `char16_t`, `char32_t`, and
2715
- `wchar_t` ([[lex.key]]).
2716
-
2717
- The function signature `strchr(const char*, int)` shall be replaced by
2718
- the two declarations:
2719
-
2720
- ``` cpp
2721
- const char* strchr(const char* s, int c);
2722
- char* strchr( char* s, int c);
2723
- ```
2724
-
2725
- both of which shall have the same behavior as the original declaration.
2726
-
2727
- The function signature `strpbrk(const char*, const char*)` shall be
2728
- replaced by the two declarations:
2729
-
2730
- ``` cpp
2731
- const char* strpbrk(const char* s1, const char* s2);
2732
- char* strpbrk( char* s1, const char* s2);
2733
- ```
2734
-
2735
- both of which shall have the same behavior as the original declaration.
2736
-
2737
- The function signature `strrchr(const char*, int)` shall be replaced by
2738
- the two declarations:
2739
-
2740
- ``` cpp
2741
- const char* strrchr(const char* s, int c);
2742
- char* strrchr( char* s, int c);
2743
- ```
2744
-
2745
- both of which shall have the same behavior as the original declaration.
2746
-
2747
- The function signature `strstr(const char*, const char*)` shall be
2748
- replaced by the two declarations:
2749
 
2750
  ``` cpp
2751
- const char* strstr(const char* s1, const char* s2);
2752
- char* strstr( char* s1, const char* s2);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2753
  ```
2754
 
2755
- both of which shall have the same behavior as the original declaration.
 
2756
 
2757
- The function signature `memchr(const void*, int, size_t)` shall be
2758
- replaced by the two declarations:
2759
 
2760
- ``` cpp
2761
- const void* memchr(const void* s, int c, size_t n);
2762
- void* memchr( void* s, int c, size_t n);
2763
- ```
2764
-
2765
- both of which shall have the same behavior as the original declaration.
2766
-
2767
- The function signature `wcschr(const wchar_t*, wchar_t)` shall be
2768
- replaced by the two declarations:
2769
-
2770
- ``` cpp
2771
- const wchar_t* wcschr(const wchar_t* s, wchar_t c);
2772
- wchar_t* wcschr( wchar_t* s, wchar_t c);
2773
- ```
2774
-
2775
- both of which shall have the same behavior as the original declaration.
2776
-
2777
- The function signature `wcspbrk(const wchar_t*, const wchar_t*)` shall
2778
- be replaced by the two declarations:
2779
 
2780
  ``` cpp
2781
- const wchar_t* wcspbrk(const wchar_t* s1, const wchar_t* s2);
2782
- wchar_t* wcspbrk( wchar_t* s1, const wchar_t* s2);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2783
  ```
2784
 
2785
- both of which shall have the same behavior as the original declaration.
2786
-
2787
- The function signature `wcsrchr(const wchar_t*, wchar_t)` shall be
2788
- replaced by the two declarations:
2789
-
2790
- ``` cpp
2791
- const wchar_t* wcsrchr(const wchar_t* s, wchar_t c);
2792
- wchar_t* wcsrchr( wchar_t* s, wchar_t c);
2793
- ```
2794
-
2795
- both of which shall have the same behavior as the original declaration.
2796
-
2797
- The function signature `wcsstr(const wchar_t*, const wchar_t*)` shall be
2798
- replaced by the two declarations:
2799
-
2800
- ``` cpp
2801
- const wchar_t* wcsstr(const wchar_t* s1, const wchar_t* s2);
2802
- wchar_t* wcsstr( wchar_t* s1, const wchar_t* s2);
2803
- ```
2804
 
2805
- both of which shall have the same behavior as the original declaration.
2806
 
2807
- The function signature `wmemchr(const wwchar_t*, int, size_t)` shall be
2808
- replaced by the two declarations:
2809
 
2810
  ``` cpp
2811
- const wchar_t* wmemchr(const wchar_t* s, wchar_t c, size_t n);
2812
- wchar_t* wmemchr( wchar_t* s, wchar_t c, size_t n);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2813
  ```
2814
 
2815
- both of which shall have the same behavior as the original declaration.
 
2816
 
2817
  The functions `strerror` and `strtok` are not required to avoid data
2818
  races ([[res.on.data.races]]).
2819
 
2820
- Calling the functions listed in Table  [[tab:mbstate.data.races]] with
2821
- an `mbstate_t*` argument of `NULL` may introduce a data race (
2822
- [[res.on.data.races]]) with other calls to these functions with an
2823
- `mbstate_t*` argument of `NULL`.
2824
 
2825
- **Table: Potential `mbstate_t` data races** <a id="tab:mbstate.data.races">[tab:mbstate.data.races]</a>
 
 
 
2826
 
2827
- | | | | | |
2828
- | ---------- | --------- | ---------- | -------- | --------- |
2829
- | `mbrlen` | `mbrtowc` | `mbsrtowc` | `mbtowc` | `wcrtomb` |
2830
- | `wcsrtomb` | `wctomb` | | | |
2831
 
 
2832
 
2833
- ISO C 7.3, 7.10.7, 7.10.8, and 7.11. Amendment 1 4.4, 4.5, and 4.6.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2834
 
2835
  <!-- Link reference definitions -->
2836
  [basic.string]: #basic.string
2837
  [basic.string.hash]: #basic.string.hash
2838
  [basic.string.literals]: #basic.string.literals
2839
  [basic.types]: basic.md#basic.types
 
2840
  [c.strings]: #c.strings
 
2841
  [char.traits]: #char.traits
2842
  [char.traits.require]: #char.traits.require
2843
  [char.traits.specializations]: #char.traits.specializations
2844
  [char.traits.specializations.char]: #char.traits.specializations.char
2845
  [char.traits.specializations.char16_t]: #char.traits.specializations.char16_t
2846
  [char.traits.specializations.char32_t]: #char.traits.specializations.char32_t
2847
  [char.traits.specializations.wchar.t]: #char.traits.specializations.wchar.t
2848
  [char.traits.typedefs]: #char.traits.typedefs
 
2849
  [container.requirements.general]: containers.md#container.requirements.general
2850
- [copyassignable]: #copyassignable
2851
- [copyconstructible]: #copyconstructible
2852
- [defaultconstructible]: #defaultconstructible
 
 
 
2853
  [input.output]: input.md#input.output
2854
  [iostate.flags]: input.md#iostate.flags
2855
  [iostream.forward]: input.md#iostream.forward
2856
  [iostreams.limits.pos]: input.md#iostreams.limits.pos
2857
  [istream.formatted.reqmts]: input.md#istream.formatted.reqmts
2858
  [istream.unformatted]: input.md#istream.unformatted
 
 
2859
  [length.error]: diagnostics.md#length.error
2860
- [lex.key]: lex.md#lex.key
2861
  [ostream.formatted.reqmts]: input.md#ostream.formatted.reqmts
2862
  [out.of.range]: diagnostics.md#out.of.range
2863
  [random.access.iterators]: iterators.md#random.access.iterators
2864
  [res.on.data.races]: library.md#res.on.data.races
2865
  [sequence.reqmts]: containers.md#sequence.reqmts
2866
  [string.access]: #string.access
2867
  [string.accessors]: #string.accessors
 
 
2868
  [string.capacity]: #string.capacity
2869
  [string.classes]: #string.classes
 
2870
  [string.cons]: #string.cons
2871
  [string.conversions]: #string.conversions
 
 
 
 
 
 
 
 
2872
  [string.io]: #string.io
2873
  [string.iterators]: #string.iterators
2874
  [string.modifiers]: #string.modifiers
2875
  [string.nonmembers]: #string.nonmembers
 
 
 
 
 
 
 
 
2876
  [string.ops]: #string.ops
 
2877
  [string.require]: #string.require
 
2878
  [string.special]: #string.special
2879
- [string::append]: #string::append
2880
- [string::assign]: #string::assign
2881
- [string::compare]: #string::compare
2882
- [string::copy]: #string::copy
2883
- [string::erase]: #string::erase
2884
- [string::find]: #string::find
2885
- [string::find.first.not.of]: #string::find.first.not.of
2886
- [string::find.first.of]: #string::find.first.of
2887
- [string::find.last.not.of]: #string::find.last.not.of
2888
- [string::find.last.of]: #string::find.last.of
2889
- [string::insert]: #string::insert
2890
- [string::op!=]: #string::op!=
2891
- [string::op+]: #string::op+
2892
- [string::op+=]: #string::op+=
2893
- [string::op<]: #string::op<
2894
- [string::op<=]: #string::op<=
2895
- [string::op>]: #string::op>
2896
- [string::op>=]: #string::op>=
2897
- [string::operator==]: #string::operator==
2898
- [string::replace]: #string::replace
2899
- [string::rfind]: #string::rfind
2900
- [string::substr]: #string::substr
2901
- [string::swap]: #string::swap
2902
  [strings]: #strings
2903
  [strings.general]: #strings.general
2904
  [tab:char.traits.require]: #tab:char.traits.require
2905
- [tab:mbstate.data.races]: #tab:mbstate.data.races
 
 
 
 
 
 
2906
  [tab:strings.compare]: #tab:strings.compare
2907
  [tab:strings.ctr.1]: #tab:strings.ctr.1
2908
  [tab:strings.ctr.2]: #tab:strings.ctr.2
2909
  [tab:strings.ctr.3]: #tab:strings.ctr.3
2910
  [tab:strings.ctr.4]: #tab:strings.ctr.4
2911
  [tab:strings.ctr.5]: #tab:strings.ctr.5
2912
  [tab:strings.ctr.6]: #tab:strings.ctr.6
2913
  [tab:strings.ctr.cpy]: #tab:strings.ctr.cpy
2914
- [tab:strings.hdr.cctype]: #tab:strings.hdr.cctype
2915
- [tab:strings.hdr.cstdlib]: #tab:strings.hdr.cstdlib
2916
- [tab:strings.hdr.cstring]: #tab:strings.hdr.cstring
2917
- [tab:strings.hdr.cuchar]: #tab:strings.hdr.cuchar
2918
- [tab:strings.hdr.cwchar]: #tab:strings.hdr.cwchar
2919
- [tab:strings.hdr.cwctype]: #tab:strings.hdr.cwctype
2920
  [tab:strings.lib.summary]: #tab:strings.lib.summary
2921
  [tab:strings.op=]: #tab:strings.op=
2922
- [tab:strings.op=rv]: #tab:strings.op=rv
2923
  [unord.hash]: utilities.md#unord.hash
 
2924
 
2925
  [^1]: If `eof()` can be held in `char_type` then some iostreams
2926
  operations may give surprising results.
2927
 
2928
  [^2]: `Allocator::value_type` must name the same type as `charT` (
2929
  [[string.require]]).
2930
 
2931
  [^3]: For example, as an argument to non-member functions `swap()` (
2932
  [[string.special]]), `operator>{}>()` ([[string.io]]), and
2933
  `getline()` ([[string.io]]), or as an argument to
2934
- `basic_string::swap()`
2935
 
2936
  [^4]: `reserve()` uses `allocator_traits<Allocator>::allocate()` which
2937
  may throw an appropriate exception.
 
1
  # Strings library <a id="strings">[[strings]]</a>
2
 
3
  ## General <a id="strings.general">[[strings.general]]</a>
4
 
5
  This Clause describes components for manipulating sequences of any
6
+ non-array POD ([[basic.types]]) type. Such types are called *char-like
7
+ types*, and objects of char-like types are called *char-like objects* or
8
+ simply *characters*.
9
 
10
  The following subclauses describe a character traits class, a string
11
  class, and null-terminated sequence utilities, as summarized in Table 
12
  [[tab:strings.lib.summary]].
13
 
14
  **Table: Strings library summary** <a id="tab:strings.lib.summary">[tab:strings.lib.summary]</a>
15
 
16
  | Subclause | | Header |
17
+ | ------------------ | ---------------------------------- | --------------- |
18
  | [[char.traits]] | Character traits | `<string>` |
19
  | [[string.classes]] | String classes | `<string>` |
20
+ | [[string.view]] | String view classes | `<string_view>` |
21
  | | | `<cctype>` |
22
  | | | `<cwctype>` |
23
  | [[c.strings]] | Null-terminated sequence utilities | `<cstring>` |
24
  | | | `<cwchar>` |
25
  | | | `<cstdlib>` |
 
35
  requirements.
36
 
37
  Most classes specified in Clauses  [[string.classes]] and 
38
  [[input.output]] need a set of related types and functions to complete
39
  the definition of their semantics. These types and functions are
40
+ provided as a set of member *typedef-name*s and functions in the
41
+ template parameter `traits` used by each such template. This subclause
42
+ defines the semantics of these members.
43
 
44
  To specialize those templates to generate a string or iostream class to
45
  handle a particular character container type `CharT`, that and its
46
  related character traits class `Traits` are passed as a pair of
47
  parameters to the string or iostream template as parameters `charT` and
48
  `traits`. `Traits::char_type` shall be the same as `CharT`.
49
 
50
+ This subclause specifies a class template, `char_traits<charT>`, and
51
  four explicit specializations of it, `char_traits<{}char>`,
52
  `char_traits<char16_t>`, `char_traits<char32_t>`, and
53
  `char_traits<wchar_t>`, all of which appear in the header `<string>` and
54
  satisfy the requirements below.
55
 
 
57
 
58
  In Table  [[tab:char.traits.require]], `X` denotes a Traits class
59
  defining types and functions for the character container type `CharT`;
60
  `c` and `d` denote values of type `CharT`; `p` and `q` denote values of
61
  type `const CharT*`; `s` denotes a value of type `CharT*`; `n`, `i` and
62
+ `j` denote values of type `size_t`; `e` and `f` denote values of type
63
+ `X::int_type`; `pos` denotes a value of type `X::pos_type`; `state`
64
  denotes a value of type `X::state_type`; and `r` denotes an lvalue of
65
  type `CharT`. Operations on Traits shall not throw exceptions.
66
 
67
+ The class template
68
 
69
  ``` cpp
70
  template<class charT> struct char_traits;
71
  ```
72
 
73
  shall be provided in the header `<string>` as a basis for explicit
74
  specializations.
75
 
76
+ ### Traits typedefs <a id="char.traits.typedefs">[[char.traits.typedefs]]</a>
77
 
78
  ``` cpp
79
+ using char_type = CHAR_T;
80
  ```
81
 
82
  The type `char_type` is used to refer to the character container type in
83
  the implementation of the library classes defined in  [[string.classes]]
84
  and Clause  [[input.output]].
85
 
86
  ``` cpp
87
+ using int_type = INT_T;
88
  ```
89
 
90
  *Requires:* For a certain character container type `char_type`, a
91
  related container type `INT_T` shall be a type or class which can
92
  represent all of the valid characters converted from the corresponding
 
94
  `int_type` represents a character container type which can hold
95
  end-of-file to be used as a return type of the iostream class member
96
  functions.[^1]
97
 
98
  ``` cpp
99
+ using off_type = implementation-defined;
100
+ using pos_type = implementation-defined;
101
  ```
102
 
103
  *Requires:* Requirements for `off_type` and `pos_type` are described
104
  in  [[iostreams.limits.pos]] and [[iostream.forward]].
105
 
106
  ``` cpp
107
+ using state_type = STATE_T;
108
  ```
109
 
110
  *Requires:* `state_type` shall meet the requirements of `CopyAssignable`
111
+ (Table  [[tab:copyassignable]]), `CopyConstructible`
112
+ (Table  [[tab:copyconstructible]]), and `DefaultConstructible`
113
+ (Table  [[tab:defaultconstructible]]) types.
114
 
115
  ### `char_traits` specializations <a id="char.traits.specializations">[[char.traits.specializations]]</a>
116
 
117
  ``` cpp
118
  namespace std {
 
121
  template<> struct char_traits<char32_t>;
122
  template<> struct char_traits<wchar_t>;
123
  }
124
  ```
125
 
126
+ The header `<string>` shall define four specializations of the class
127
+ template `char_traits`: `char_traits<{}char>`, `char_traits<char16_t>`,
128
  `char_traits<char32_t>`, and `char_traits<wchar_t>`.
129
 
130
  The requirements for the members of these specializations are given in
131
  Clause  [[char.traits.require]].
132
 
133
  #### `struct char_traits<char>` <a id="char.traits.specializations.char">[[char.traits.specializations.char]]</a>
134
 
135
  ``` cpp
136
  namespace std {
137
  template<> struct char_traits<char> {
138
+ using char_type = char;
139
+ using int_type = int;
140
+ using off_type = streamoff;
141
+ using pos_type = streampos;
142
+ using state_type = mbstate_t;
143
 
144
+ static constexpr void assign(char_type& c1, const char_type& c2) noexcept;
145
  static constexpr bool eq(char_type c1, char_type c2) noexcept;
146
  static constexpr bool lt(char_type c1, char_type c2) noexcept;
147
 
148
+ static constexpr int compare(const char_type* s1, const char_type* s2, size_t n);
149
+ static constexpr size_t length(const char_type* s);
150
+ static constexpr const char_type* find(const char_type* s, size_t n,
151
  const char_type& a);
152
  static char_type* move(char_type* s1, const char_type* s2, size_t n);
153
  static char_type* copy(char_type* s1, const char_type* s2, size_t n);
154
  static char_type* assign(char_type* s, size_t n, char_type a);
155
 
 
179
  of supported multibyte character encoding rules.
180
 
181
  The two-argument member `assign` shall be defined identically to the
182
  built-in operator `=`. The two-argument members `eq` and `lt` shall be
183
  defined identically to the built-in operators `==` and `<` for type
184
+ `unsigned char`.
185
 
186
  The member `eof()` shall return `EOF`.
187
 
188
  #### `struct char_traits<char16_t>` <a id="char.traits.specializations.char16_t">[[char.traits.specializations.char16_t]]</a>
189
 
190
  ``` cpp
191
  namespace std {
192
  template<> struct char_traits<char16_t> {
193
+ using char_type = char16_t;
194
+ using int_type = uint_least16_t;
195
+ using off_type = streamoff;
196
+ using pos_type = u16streampos;
197
+ using state_type = mbstate_t;
198
 
199
+ static constexpr void assign(char_type& c1, const char_type& c2) noexcept;
200
  static constexpr bool eq(char_type c1, char_type c2) noexcept;
201
  static constexpr bool lt(char_type c1, char_type c2) noexcept;
202
 
203
+ static constexpr int compare(const char_type* s1, const char_type* s2, size_t n);
204
+ static constexpr size_t length(const char_type* s);
205
+ static constexpr const char_type* find(const char_type* s, size_t n,
206
  const char_type& a);
207
  static char_type* move(char_type* s1, const char_type* s2, size_t n);
208
  static char_type* copy(char_type* s1, const char_type* s2, size_t n);
209
  static char_type* assign(char_type* s, size_t n, char_type a);
210
 
 
216
  };
217
  }
218
  ```
219
 
220
  The type `u16streampos` shall be an *implementation-defined* type that
221
+ satisfies the requirements for `pos_type` in  [[iostreams.limits.pos]]
222
+ and [[iostream.forward]].
223
 
224
  The two-argument members `assign`, `eq`, and `lt` shall be defined
225
  identically to the built-in operators `=`, `==`, and `<` respectively.
226
 
227
  The member `eof()` shall return an *implementation-defined* constant
 
230
  #### `struct char_traits<char32_t>` <a id="char.traits.specializations.char32_t">[[char.traits.specializations.char32_t]]</a>
231
 
232
  ``` cpp
233
  namespace std {
234
  template<> struct char_traits<char32_t> {
235
+ using char_type = char32_t;
236
+ using int_type = uint_least32_t;
237
+ using off_type = streamoff;
238
+ using pos_type = u32streampos;
239
+ using state_type = mbstate_t;
240
 
241
+ static constexpr void assign(char_type& c1, const char_type& c2) noexcept;
242
  static constexpr bool eq(char_type c1, char_type c2) noexcept;
243
  static constexpr bool lt(char_type c1, char_type c2) noexcept;
244
 
245
+ static constexpr int compare(const char_type* s1, const char_type* s2, size_t n);
246
+ static constexpr size_t length(const char_type* s);
247
+ static constexpr const char_type* find(const char_type* s, size_t n,
248
  const char_type& a);
249
  static char_type* move(char_type* s1, const char_type* s2, size_t n);
250
  static char_type* copy(char_type* s1, const char_type* s2, size_t n);
251
  static char_type* assign(char_type* s, size_t n, char_type a);
252
 
 
258
  };
259
  }
260
  ```
261
 
262
  The type `u32streampos` shall be an *implementation-defined* type that
263
+ satisfies the requirements for `pos_type` in  [[iostreams.limits.pos]]
264
+ and [[iostream.forward]].
265
 
266
  The two-argument members `assign`, `eq`, and `lt` shall be defined
267
  identically to the built-in operators `=`, `==`, and `<` respectively.
268
 
269
  The member `eof()` shall return an *implementation-defined* constant
 
272
  #### `struct char_traits<wchar_t>` <a id="char.traits.specializations.wchar.t">[[char.traits.specializations.wchar.t]]</a>
273
 
274
  ``` cpp
275
  namespace std {
276
  template<> struct char_traits<wchar_t> {
277
+ using char_type = wchar_t;
278
+ using int_type = wint_t;
279
+ using off_type = streamoff;
280
+ using pos_type = wstreampos;
281
+ using state_type = mbstate_t;
282
 
283
+ static constexpr void assign(char_type& c1, const char_type& c2) noexcept;
284
  static constexpr bool eq(char_type c1, char_type c2) noexcept;
285
  static constexpr bool lt(char_type c1, char_type c2) noexcept;
286
 
287
+ static constexpr int compare(const char_type* s1, const char_type* s2, size_t n);
288
+ static constexpr size_t length(const char_type* s);
289
+ static constexpr const char_type* find(const char_type* s, size_t n,
290
  const char_type& a);
291
  static char_type* move(char_type* s1, const char_type* s2, size_t n);
292
  static char_type* copy(char_type* s1, const char_type* s2, size_t n);
293
  static char_type* assign(char_type* s, size_t n, char_type a);
294
 
 
303
 
304
  The defined types for `int_type`, `pos_type`, and `state_type` shall be
305
  `wint_t`, `wstreampos`, and `mbstate_t` respectively.
306
 
307
  The type `wstreampos` shall be an *implementation-defined* type that
308
+ satisfies the requirements for `pos_type` in  [[iostreams.limits.pos]]
309
+ and [[iostream.forward]].
310
 
311
  The type `mbstate_t` is defined in `<cwchar>` and can represent any of
312
  the conversion states that can occur in an *implementation-defined* set
313
  of supported multibyte character encoding rules.
314
 
 
319
 
320
  ## String classes <a id="string.classes">[[string.classes]]</a>
321
 
322
  The header `<string>` defines the `basic_string` class template for
323
  manipulating varying-length sequences of char-like objects and four
324
+ *typedef-name*s, `string`, `u16string`, `u32string`, and `wstring`, that
325
+ name the specializations `basic_string<char>`, `basic_string<char16_t>`,
326
  `basic_string<char32_t>`, and `basic_string<{}wchar_t>`, respectively.
327
 
328
+ ### Header `<string>` synopsis <a id="string.syn">[[string.syn]]</a>
329
+
330
  ``` cpp
331
  #include <initializer_list>
332
 
333
  namespace std {
334
+ // [char.traits], character traits
 
335
  template<class charT> struct char_traits;
336
  template<> struct char_traits<char>;
337
  template<> struct char_traits<char16_t>;
338
  template<> struct char_traits<char32_t>;
339
  template<> struct char_traits<wchar_t>;
340
 
341
+ // [basic.string], basic_string
342
  template<class charT, class traits = char_traits<charT>,
343
  class Allocator = allocator<charT>>
344
  class basic_string;
345
 
346
  template<class charT, class traits, class Allocator>
 
443
  const charT* rhs);
444
  template<class charT, class traits, class Allocator>
445
  bool operator>=(const charT* lhs,
446
  const basic_string<charT, traits, Allocator>& rhs);
447
 
448
+ // [string.special], swap
449
  template<class charT, class traits, class Allocator>
450
  void swap(basic_string<charT, traits, Allocator>& lhs,
451
+ basic_string<charT, traits, Allocator>& rhs)
452
+ noexcept(noexcept(lhs.swap(rhs)));
453
 
454
+ // [string.io], inserters and extractors
455
  template<class charT, class traits, class Allocator>
456
  basic_istream<charT, traits>&
457
  operator>>(basic_istream<charT, traits>& is,
458
  basic_string<charT, traits, Allocator>& str);
459
  template<class charT, class traits, class Allocator>
 
478
  basic_istream<charT, traits>&
479
  getline(basic_istream<charT, traits>&& is,
480
  basic_string<charT, traits, Allocator>& str);
481
 
482
  // basic_string typedef names
483
+ using string = basic_string<char>;
484
+ using u16string = basic_string<char16_t>;
485
+ using u32string = basic_string<char32_t>;
486
+ using wstring = basic_string<wchar_t>;
487
 
488
+ // [string.conversions], numeric conversions
489
  int stoi(const string& str, size_t* idx = 0, int base = 10);
490
  long stol(const string& str, size_t* idx = 0, int base = 10);
491
  unsigned long stoul(const string& str, size_t* idx = 0, int base = 10);
492
  long long stoll(const string& str, size_t* idx = 0, int base = 10);
493
  unsigned long long stoull(const string& str, size_t* idx = 0, int base = 10);
 
520
  wstring to_wstring(unsigned long long val);
521
  wstring to_wstring(float val);
522
  wstring to_wstring(double val);
523
  wstring to_wstring(long double val);
524
 
525
+ // [basic.string.hash], hash support
526
  template<class T> struct hash;
527
  template<> struct hash<string>;
528
  template<> struct hash<u16string>;
529
  template<> struct hash<u32string>;
530
  template<> struct hash<wstring>;
531
 
532
+ namespace pmr {
533
+ template <class charT, class traits = char_traits<charT>>
534
+ using basic_string =
535
+ std::basic_string<charT, traits, polymorphic_allocator<charT>>;
536
+
537
+ using string = basic_string<char>;
538
+ using u16string = basic_string<char16_t>;
539
+ using u32string = basic_string<char32_t>;
540
+ using wstring = basic_string<wchar_t>;
541
+ }
542
+
543
  inline namespace literals {
544
  inline namespace string_literals {
545
+ // [basic.string.literals], suffix for basic_string literals
 
546
  string operator""s(const char* str, size_t len);
547
  u16string operator""s(const char16_t* str, size_t len);
548
  u32string operator""s(const char32_t* str, size_t len);
549
  wstring operator""s(const wchar_t* str, size_t len);
 
550
  }
551
  }
552
  }
553
  ```
554
 
555
+ ### Class template `basic_string` <a id="basic.string">[[basic.string]]</a>
556
 
557
  The class template `basic_string` describes objects that can store a
558
  sequence consisting of a varying number of arbitrary char-like objects
559
  with the first element of the sequence at position zero. Such a sequence
560
  is also called a “string” if the type of the char-like objects that it
 
564
 
565
  The member functions of `basic_string` use an object of the `Allocator`
566
  class passed as a template parameter to allocate and free storage for
567
  the contained char-like objects.[^2]
568
 
569
+ A `basic_string` is a contiguous container (
570
+ [[container.requirements.general]]).
571
 
572
  In all cases, `size() <= capacity()`.
573
 
574
  The functions described in this Clause can report two kinds of errors,
575
  each associated with an exception type:
 
584
  template<class charT, class traits = char_traits<charT>,
585
  class Allocator = allocator<charT>>
586
  class basic_string {
587
  public:
588
  // types:
589
+ using traits_type = traits;
590
+ using value_type = charT;
591
+ using allocator_type = Allocator;
592
+ using size_type = typename allocator_traits<Allocator>::size_type;
593
+ using difference_type = typename allocator_traits<Allocator>::difference_type;
594
+ using pointer = typename allocator_traits<Allocator>::pointer;
595
+ using const_pointer = typename allocator_traits<Allocator>::const_pointer;
596
+ using reference = value_type&;
597
+ using const_reference = const value_type&;
598
 
599
+ using iterator = implementation-defined // type of basic_string::iterator; // see [container.requirements]
600
+ using const_iterator = implementation-defined // type of basic_string::const_iterator; // see [container.requirements]
601
+ using reverse_iterator = std::reverse_iterator<iterator>;
602
+ using const_reverse_iterator = std::reverse_iterator<const_iterator>;
 
 
 
 
 
603
  static const size_type npos = -1;
604
 
605
+ // [string.cons], construct/copy/destroy
606
+ basic_string() noexcept(noexcept(Allocator())) : basic_string(Allocator()) { }
607
+ explicit basic_string(const Allocator& a) noexcept;
608
  basic_string(const basic_string& str);
609
  basic_string(basic_string&& str) noexcept;
610
+ basic_string(const basic_string& str, size_type pos,
611
+ const Allocator& a = Allocator());
612
+ basic_string(const basic_string& str, size_type pos, size_type n,
613
+ const Allocator& a = Allocator());
614
+ template<class T>
615
+ basic_string(const T& t, size_type pos, size_type n,
616
+ const Allocator& a = Allocator());
617
+ explicit basic_string(basic_string_view<charT, traits> sv,
618
  const Allocator& a = Allocator());
619
  basic_string(const charT* s,
620
  size_type n, const Allocator& a = Allocator());
621
  basic_string(const charT* s, const Allocator& a = Allocator());
622
  basic_string(size_type n, charT c, const Allocator& a = Allocator());
 
627
  basic_string(const basic_string&, const Allocator&);
628
  basic_string(basic_string&&, const Allocator&);
629
 
630
  ~basic_string();
631
  basic_string& operator=(const basic_string& str);
632
+ basic_string& operator=(basic_string&& str)
633
+ noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
634
+ allocator_traits<Allocator>::is_always_equal::value);
635
+ basic_string& operator=(basic_string_view<charT, traits> sv);
636
  basic_string& operator=(const charT* s);
637
  basic_string& operator=(charT c);
638
  basic_string& operator=(initializer_list<charT>);
639
 
640
+ // [string.iterators], iterators
641
  iterator begin() noexcept;
642
  const_iterator begin() const noexcept;
643
  iterator end() noexcept;
644
  const_iterator end() const noexcept;
645
 
 
651
  const_iterator cbegin() const noexcept;
652
  const_iterator cend() const noexcept;
653
  const_reverse_iterator crbegin() const noexcept;
654
  const_reverse_iterator crend() const noexcept;
655
 
656
+ // [string.capacity], capacity
657
  size_type size() const noexcept;
658
  size_type length() const noexcept;
659
  size_type max_size() const noexcept;
660
  void resize(size_type n, charT c);
661
  void resize(size_type n);
 
663
  void reserve(size_type res_arg = 0);
664
  void shrink_to_fit();
665
  void clear() noexcept;
666
  bool empty() const noexcept;
667
 
668
+ // [string.access], element access
669
  const_reference operator[](size_type pos) const;
670
  reference operator[](size_type pos);
671
  const_reference at(size_type n) const;
672
  reference at(size_type n);
673
 
674
  const charT& front() const;
675
  charT& front();
676
  const charT& back() const;
677
  charT& back();
678
 
679
+ // [string.modifiers], modifiers
680
  basic_string& operator+=(const basic_string& str);
681
+ basic_string& operator+=(basic_string_view<charT, traits> sv);
682
  basic_string& operator+=(const charT* s);
683
  basic_string& operator+=(charT c);
684
  basic_string& operator+=(initializer_list<charT>);
685
  basic_string& append(const basic_string& str);
686
  basic_string& append(const basic_string& str, size_type pos,
687
  size_type n = npos);
688
+ basic_string& append(basic_string_view<charT, traits> sv);
689
+ template<class T>
690
+ basic_string& append(const T& t, size_type pos, size_type n = npos);
691
  basic_string& append(const charT* s, size_type n);
692
  basic_string& append(const charT* s);
693
  basic_string& append(size_type n, charT c);
694
  template<class InputIterator>
695
  basic_string& append(InputIterator first, InputIterator last);
696
  basic_string& append(initializer_list<charT>);
697
  void push_back(charT c);
698
 
699
  basic_string& assign(const basic_string& str);
700
+ basic_string& assign(basic_string&& str)
701
+ noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
702
+ allocator_traits<Allocator>::is_always_equal::value);
703
  basic_string& assign(const basic_string& str, size_type pos,
704
  size_type n = npos);
705
+ basic_string& assign(basic_string_view<charT, traits> sv);
706
+ template<class T>
707
+ basic_string& assign(const T& t, size_type pos, size_type n = npos);
708
  basic_string& assign(const charT* s, size_type n);
709
  basic_string& assign(const charT* s);
710
  basic_string& assign(size_type n, charT c);
711
  template<class InputIterator>
712
  basic_string& assign(InputIterator first, InputIterator last);
713
  basic_string& assign(initializer_list<charT>);
714
 
715
+ basic_string& insert(size_type pos, const basic_string& str);
716
  basic_string& insert(size_type pos1, const basic_string& str,
717
  size_type pos2, size_type n = npos);
718
+ basic_string& insert(size_type pos, basic_string_view<charT, traits> sv);
719
+ template<class T>
720
+ basic_string& insert(size_type pos1, const T& t,
721
+ size_type pos2, size_type n = npos);
722
  basic_string& insert(size_type pos, const charT* s, size_type n);
723
  basic_string& insert(size_type pos, const charT* s);
724
  basic_string& insert(size_type pos, size_type n, charT c);
725
  iterator insert(const_iterator p, charT c);
726
  iterator insert(const_iterator p, size_type n, charT c);
 
737
  basic_string& replace(size_type pos1, size_type n1,
738
  const basic_string& str);
739
  basic_string& replace(size_type pos1, size_type n1,
740
  const basic_string& str,
741
  size_type pos2, size_type n2 = npos);
742
+ basic_string& replace(size_type pos1, size_type n1,
743
+ basic_string_view<charT, traits> sv);
744
+ template<class T>
745
+ basic_string& replace(size_type pos1, size_type n1, const T& t,
746
+ size_type pos2, size_type n2 = npos);
747
  basic_string& replace(size_type pos, size_type n1, const charT* s,
748
  size_type n2);
749
  basic_string& replace(size_type pos, size_type n1, const charT* s);
750
  basic_string& replace(size_type pos, size_type n1, size_type n2,
751
  charT c);
752
 
753
  basic_string& replace(const_iterator i1, const_iterator i2,
754
  const basic_string& str);
755
+ basic_string& replace(const_iterator i1, const_iterator i2,
756
+ basic_string_view<charT, traits> sv);
757
  basic_string& replace(const_iterator i1, const_iterator i2, const charT* s,
758
  size_type n);
759
  basic_string& replace(const_iterator i1, const_iterator i2, const charT* s);
760
  basic_string& replace(const_iterator i1, const_iterator i2,
761
  size_type n, charT c);
 
763
  basic_string& replace(const_iterator i1, const_iterator i2,
764
  InputIterator j1, InputIterator j2);
765
  basic_string& replace(const_iterator, const_iterator, initializer_list<charT>);
766
 
767
  size_type copy(charT* s, size_type n, size_type pos = 0) const;
768
+ void swap(basic_string& str)
769
+ noexcept(allocator_traits<Allocator>::propagate_on_container_swap::value ||
770
+ allocator_traits<Allocator>::is_always_equal::value);
771
 
772
+ // [string.ops], string operations
773
  const charT* c_str() const noexcept;
774
  const charT* data() const noexcept;
775
+ charT* data() noexcept;
776
+ operator basic_string_view<charT, traits>() const noexcept;
777
  allocator_type get_allocator() const noexcept;
778
 
779
+ size_type find (basic_string_view<charT, traits> sv,
780
+ size_type pos = 0) const noexcept;
781
  size_type find (const basic_string& str, size_type pos = 0) const noexcept;
782
  size_type find (const charT* s, size_type pos, size_type n) const;
783
  size_type find (const charT* s, size_type pos = 0) const;
784
  size_type find (charT c, size_type pos = 0) const;
785
+ size_type rfind(basic_string_view<charT, traits> sv,
786
+ size_type pos = npos) const noexcept;
787
  size_type rfind(const basic_string& str, size_type pos = npos) const noexcept;
788
  size_type rfind(const charT* s, size_type pos, size_type n) const;
789
  size_type rfind(const charT* s, size_type pos = npos) const;
790
  size_type rfind(charT c, size_type pos = npos) const;
791
 
792
+ size_type find_first_of(basic_string_view<charT, traits> sv,
793
+ size_type pos = 0) const noexcept;
794
  size_type find_first_of(const basic_string& str,
795
  size_type pos = 0) const noexcept;
796
  size_type find_first_of(const charT* s,
797
  size_type pos, size_type n) const;
798
  size_type find_first_of(const charT* s, size_type pos = 0) const;
799
  size_type find_first_of(charT c, size_type pos = 0) const;
800
+ size_type find_last_of (basic_string_view<charT, traits> sv,
801
+ size_type pos = npos) const noexcept;
802
  size_type find_last_of (const basic_string& str,
803
  size_type pos = npos) const noexcept;
804
  size_type find_last_of (const charT* s,
805
  size_type pos, size_type n) const;
806
  size_type find_last_of (const charT* s, size_type pos = npos) const;
807
  size_type find_last_of (charT c, size_type pos = npos) const;
808
 
809
+ size_type find_first_not_of(basic_string_view<charT, traits> sv,
810
+ size_type pos = 0) const noexcept;
811
  size_type find_first_not_of(const basic_string& str,
812
  size_type pos = 0) const noexcept;
813
  size_type find_first_not_of(const charT* s, size_type pos,
814
  size_type n) const;
815
  size_type find_first_not_of(const charT* s, size_type pos = 0) const;
816
  size_type find_first_not_of(charT c, size_type pos = 0) const;
817
+ size_type find_last_not_of (basic_string_view<charT, traits> sv,
818
+ size_type pos = npos) const noexcept;
819
  size_type find_last_not_of (const basic_string& str,
820
  size_type pos = npos) const noexcept;
821
  size_type find_last_not_of (const charT* s, size_type pos,
822
  size_type n) const;
823
  size_type find_last_not_of (const charT* s,
824
  size_type pos = npos) const;
825
  size_type find_last_not_of (charT c, size_type pos = npos) const;
826
 
827
  basic_string substr(size_type pos = 0, size_type n = npos) const;
828
+ int compare(basic_string_view<charT, traits> sv) const noexcept;
829
+ int compare(size_type pos1, size_type n1,
830
+ basic_string_view<charT, traits> sv) const;
831
+ template<class T>
832
+ int compare(size_type pos1, size_type n1, const T& t,
833
+ size_type pos2, size_type n2 = npos) const;
834
  int compare(const basic_string& str) const noexcept;
835
  int compare(size_type pos1, size_type n1,
836
  const basic_string& str) const;
837
  int compare(size_type pos1, size_type n1,
838
  const basic_string& str,
 
841
  int compare(size_type pos1, size_type n1,
842
  const charT* s) const;
843
  int compare(size_type pos1, size_type n1,
844
  const charT* s, size_type n2) const;
845
  };
846
+
847
+ template<class InputIterator,
848
+ class Allocator = allocator<typename iterator_traits<InputIterator>::value_type>>
849
+ basic_string(InputIterator, InputIterator, Allocator = Allocator())
850
+ -> basic_string<typename iterator_traits<InputIterator>::value_type,
851
+ char_traits<typename iterator_traits<InputIterator>::value_type>,
852
+ Allocator>;
853
  }
854
  ```
855
 
856
+ #### `basic_string` general requirements <a id="string.require">[[string.require]]</a>
857
 
858
  If any operation would cause `size()` to exceed `max_size()`, that
859
  operation shall throw an exception object of type `length_error`.
860
 
861
  If any member function or operator of `basic_string` throws an
 
865
  type `allocator_traits<Allocator>::value_type` shall name the same type
866
  as `charT`. Every object of type
867
  `basic_string<charT, traits, Allocator>` shall use an object of type
868
  `Allocator` to allocate and free storage for the contained `charT`
869
  objects as needed. The `Allocator` object used shall be obtained as
870
+ described in [[container.requirements.general]]. In every specialization
871
+ `basic_string<charT, traits, Allocator>`, the type `traits` shall
872
+ satisfy the character traits requirements ([[char.traits]]), and the
873
+ type `traits::char_type` shall name the same type as `charT`.
 
 
874
 
875
  References, pointers, and iterators referring to the elements of a
876
  `basic_string` sequence may be invalidated by the following uses of that
877
  `basic_string` object:
878
 
879
  - as an argument to any standard library function taking a reference to
880
  non-const `basic_string` as an argument.[^3]
881
+ - Calling non-const member functions, except `operator[]`, `at`, `data`,
882
  `front`, `back`, `begin`, `rbegin`, `end`, and `rend`.
883
 
884
+ #### `basic_string` constructors and assignment operators <a id="string.cons">[[string.cons]]</a>
885
 
886
  ``` cpp
887
+ explicit basic_string(const Allocator& a) noexcept;
888
  ```
889
 
890
  *Effects:* Constructs an object of class `basic_string`. The
891
  postconditions of this function are indicated in
892
  Table  [[tab:strings.ctr.1]].
 
915
  | `data()` | points at the first element of an allocated copy of the array whose first element is pointed at by `str.data()` |
916
  | `size()` | `str.size()` |
917
  | `capacity()` | a value at least as large as `size()` |
918
 
919
  ``` cpp
920
+ basic_string(const basic_string& str, size_type pos,
 
921
  const Allocator& a = Allocator());
922
  ```
923
 
924
+ *Throws:* `out_of_range` if `pos > str.size()`.
925
+
926
+ *Effects:* Constructs an object of class `basic_string` and determines
927
+ the effective length `rlen` of the initial string value as
928
+ `str.size() - pos`, as indicated in Table  [[tab:strings.ctr.2]].
929
+
930
+ ``` cpp
931
+ basic_string(const basic_string& str, size_type pos, size_type n,
932
+ const Allocator& a = Allocator());
933
+ ```
934
 
935
  *Throws:* `out_of_range` if `pos > str.size()`.
936
 
937
  *Effects:* Constructs an object of class `basic_string` and determines
938
  the effective length `rlen` of the initial string value as the smaller
939
  of `n` and `str.size() - pos`, as indicated in
940
  Table  [[tab:strings.ctr.2]].
941
 
942
+ **Table: `basic_string(const basic_string&, size_type, const Allocator&)`\protect\mbox{ }and\protect
943
+ `basic_string(const basic_string&, size_type, size_type, const Allocator&)` effects** <a id="tab:strings.ctr.2">[tab:strings.ctr.2]</a>
944
 
945
  | Element | Value |
946
  | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
947
  | `data()` | points at the first element of an allocated copy of `rlen` consecutive elements of the string controlled by `str` beginning at position `pos` |
948
  | `size()` | `rlen` |
949
  | `capacity()` | a value at least as large as `size()` |
950
 
951
+ ``` cpp
952
+ template<class T>
953
+ basic_string(const T& t, size_type pos, size_type n,
954
+ const Allocator& a = Allocator());
955
+ ```
956
+
957
+ *Effects:* Creates a variable, `sv`, as if by
958
+ `basic_string_view<charT, traits> sv = t;` and then behaves the same as:
959
+
960
+ ``` cpp
961
+ basic_string(sv.substr(pos, n), a);
962
+ ```
963
+
964
+ *Remarks:* This constructor shall not participate in overload resolution
965
+ unless `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
966
+ `true`.
967
+
968
+ ``` cpp
969
+ explicit basic_string(basic_string_view<charT, traits> sv,
970
+ const Allocator& a = Allocator());
971
+ ```
972
+
973
+ *Effects:* Same as `basic_string(sv.data(), sv.size(), a)`.
974
+
975
  ``` cpp
976
  basic_string(const charT* s, size_type n,
977
  const Allocator& a = Allocator());
978
  ```
979
 
 
1010
  | ------------ | ------------------------------------------------------------------------------------------------------ |
1011
  | `data()` | points at the first element of an allocated copy of the array whose first element is pointed at by `s` |
1012
  | `size()` | `traits::length(s)` |
1013
  | `capacity()` | a value at least as large as `size()` |
1014
 
 
 
 
1015
  ``` cpp
1016
  basic_string(size_type n, charT c, const Allocator& a = Allocator());
1017
  ```
1018
 
1019
+ *Requires:* `n < npos`.
1020
 
1021
  *Effects:* Constructs an object of class `basic_string` and determines
1022
  its initial string value by repeating the char-like object `c` for all
1023
  `n` elements, as indicated in Table  [[tab:strings.ctr.5]].
1024
 
 
1034
  template<class InputIterator>
1035
  basic_string(InputIterator begin, InputIterator end,
1036
  const Allocator& a = Allocator());
1037
  ```
1038
 
1039
+ *Effects:* If `InputIterator` is an integral type, equivalent to:
1040
 
1041
  ``` cpp
1042
+ basic_string(static_cast<size_type>(begin), static_cast<value_type>(end), a);
1043
  ```
1044
 
1045
  Otherwise constructs a string from the values in the range \[`begin`,
1046
  `end`), as indicated in the Sequence Requirements table
1047
  (see  [[sequence.reqmts]]).
 
1060
  *Effects:* Constructs an object of class `basic_string` as indicated in
1061
  Table  [[tab:strings.ctr.6]]. The stored allocator is constructed from
1062
  `alloc`. In the second form, `str` is left in a valid state with an
1063
  unspecified value.
1064
 
1065
+ **Table: `basic_string(const basic_string&, const Allocator&)`\protect and
1066
  `basic_string(basic_string&&, const Allocator&)` effects** <a id="tab:strings.ctr.6">[tab:strings.ctr.6]</a>
1067
 
1068
  | Element | Value |
1069
  | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
1070
  | `data()` | points at the first element of an allocated copy of the array whose first element is pointed at by the original value of `str.data()`. |
 
1074
 
1075
 
1076
  *Throws:* The second form throws nothing if
1077
  `alloc == str.get_allocator()`.
1078
 
1079
+ ``` cpp
1080
+ template<class InputIterator,
1081
+ class Allocator = allocator<typename iterator_traits<InputIterator>::value_type>>
1082
+ basic_string(InputIterator, InputIterator, Allocator = Allocator())
1083
+ -> basic_string<typename iterator_traits<InputIterator>::value_type,
1084
+ char_traits<typename iterator_traits<InputIterator>::value_type>,
1085
+ Allocator>;
1086
+ ```
1087
+
1088
+ *Remarks:* Shall not participate in overload resolution if
1089
+ `InputIterator` is a type that does not qualify as an input iterator, or
1090
+ if `Allocator` is a type that does not qualify as an
1091
+ allocator ([[container.requirements.general]]).
1092
+
1093
  ``` cpp
1094
  basic_string& operator=(const basic_string& str);
1095
  ```
1096
 
1097
  *Effects:* If `*this` and `str` are not the same object, modifies
1098
  `*this` as shown in Table  [[tab:strings.op=]].
1099
 
1100
  If `*this` and `str` are the same object, the member has no effect.
1101
 
1102
+ *Returns:* `*this`.
1103
 
1104
  **Table: `operator=(const basic_string&)` effects** <a id="tab:strings.op=">[tab:strings.op=]</a>
1105
 
1106
  | Element | Value |
1107
  | ------------ | --------------------------------------------------------------------------------------------------------------- |
1108
  | `data()` | points at the first element of an allocated copy of the array whose first element is pointed at by `str.data()` |
1109
  | `size()` | `str.size()` |
1110
  | `capacity()` | a value at least as large as `size()` |
1111
 
1112
  ``` cpp
1113
+ basic_string& operator=(basic_string&& str)
1114
+ noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
1115
+ allocator_traits<Allocator>::is_always_equal::value);
1116
  ```
1117
 
1118
+ *Effects:* Move assigns as a sequence
1119
+ container ([[container.requirements]]), except that iterators, pointers
1120
+ and references may be invalidated.
1121
 
1122
+ *Returns:* `*this`.
1123
 
1124
+ ``` cpp
1125
+ basic_string& operator=(basic_string_view<charT, traits> sv);
1126
+ ```
1127
 
1128
+ *Effects:* Equivalent to: `return assign(sv);`
 
 
 
 
1129
 
1130
  ``` cpp
1131
  basic_string& operator=(const charT* s);
1132
  ```
1133
 
 
1143
 
1144
  ``` cpp
1145
  basic_string& operator=(initializer_list<charT> il);
1146
  ```
1147
 
1148
+ *Effects:* As if by: `*this = basic_string(il);`
1149
 
1150
  *Returns:* `*this`.
1151
 
1152
+ #### `basic_string` iterator support <a id="string.iterators">[[string.iterators]]</a>
1153
 
1154
  ``` cpp
1155
  iterator begin() noexcept;
1156
  const_iterator begin() const noexcept;
1157
  const_iterator cbegin() const noexcept;
 
1183
  ```
1184
 
1185
  *Returns:* An iterator which is semantically equivalent to
1186
  `reverse_iterator(begin())`.
1187
 
1188
+ #### `basic_string` capacity <a id="string.capacity">[[string.capacity]]</a>
1189
 
1190
  ``` cpp
1191
  size_type size() const noexcept;
1192
  ```
1193
 
 
1204
 
1205
  ``` cpp
1206
  size_type max_size() const noexcept;
1207
  ```
1208
 
1209
+ *Returns:* The largest possible number of char-like objects that can be
1210
+ stored in a `basic_string`.
1211
 
1212
  *Complexity:* Constant time.
1213
 
1214
  ``` cpp
1215
  void resize(size_type n, charT c);
1216
  ```
1217
 
 
 
1218
  *Throws:* `length_error` if `n > max_size()`.
1219
 
1220
  *Effects:* Alters the length of the string designated by `*this` as
1221
  follows:
1222
 
 
1230
 
1231
  ``` cpp
1232
  void resize(size_type n);
1233
  ```
1234
 
1235
+ *Effects:* As if by `resize(n, charT())`.
1236
 
1237
  ``` cpp
1238
  size_type capacity() const noexcept;
1239
  ```
1240
 
 
1247
  The member function `reserve()` is a directive that informs a
1248
  `basic_string` object of a planned change in size, so that it can manage
1249
  the storage allocation accordingly.
1250
 
1251
  *Effects:* After `reserve()`, `capacity()` is greater or equal to the
1252
+ argument of `reserve`.
1253
+
1254
+ [*Note 1*: Calling `reserve()` with a `res_arg` argument less than
1255
+ `capacity()` is in effect a non-binding shrink request. A call with
1256
+ `res_arg <= size()` is in effect a non-binding shrink-to-fit
1257
+ request. — *end note*]
1258
 
1259
  *Throws:* `length_error` if `res_arg > max_size()`.[^4]
1260
 
1261
  ``` cpp
1262
  void shrink_to_fit();
1263
  ```
1264
 
1265
+ *Effects:* `shrink_to_fit` is a non-binding request to reduce
1266
+ `capacity()` to `size()`.
1267
+
1268
+ [*Note 2*: The request is non-binding to allow latitude for
1269
+ implementation-specific optimizations. — *end note*]
1270
+
1271
+ It does not increase `capacity()`, but may reduce `capacity()` by
1272
+ causing reallocation.
1273
+
1274
+ *Complexity:* Linear in the size of the sequence.
1275
+
1276
+ *Remarks:* Reallocation invalidates all the references, pointers, and
1277
+ iterators referring to the elements in the sequence as well as the
1278
+ past-the-end iterator. If no reallocation happens, they remain valid.
1279
 
1280
  ``` cpp
1281
  void clear() noexcept;
1282
  ```
1283
 
 
1291
  bool empty() const noexcept;
1292
  ```
1293
 
1294
  *Returns:* `size() == 0`.
1295
 
1296
+ #### `basic_string` element access <a id="string.access">[[string.access]]</a>
1297
 
1298
  ``` cpp
1299
  const_reference operator[](size_type pos) const;
1300
  reference operator[](size_type pos);
1301
  ```
1302
 
1303
  *Requires:* `pos <= size()`.
1304
 
1305
  *Returns:* `*(begin() + pos)` if `pos < size()`. Otherwise, returns a
1306
  reference to an object of type `charT` with value `charT()`, where
1307
+ modifying the object to any value other than `charT()` leads to
1308
+ undefined behavior.
1309
 
1310
  *Throws:* Nothing.
1311
 
1312
  *Complexity:* Constant time.
1313
 
 
1323
  ``` cpp
1324
  const charT& front() const;
1325
  charT& front();
1326
  ```
1327
 
1328
+ *Requires:* `!empty()`.
1329
 
1330
+ *Effects:* Equivalent to: `return operator[](0);`
1331
 
1332
  ``` cpp
1333
  const charT& back() const;
1334
  charT& back();
1335
  ```
1336
 
1337
+ *Requires:* `!empty()`.
1338
 
1339
+ *Effects:* Equivalent to: `return operator[](size() - 1);`
1340
 
1341
+ #### `basic_string` modifiers <a id="string.modifiers">[[string.modifiers]]</a>
1342
 
1343
+ ##### `basic_string::operator+=` <a id="string.op+=">[[string.op+=]]</a>
1344
 
1345
  ``` cpp
1346
  basic_string&
1347
  operator+=(const basic_string& str);
1348
  ```
1349
 
1350
  *Effects:* Calls `append(str)`.
1351
 
1352
  *Returns:* `*this`.
1353
 
1354
+ ``` cpp
1355
+ basic_string& operator+=(basic_string_view<charT, traits> sv);
1356
+ ```
1357
+
1358
+ *Effects:* Calls `append(sv)`.
1359
+
1360
+ *Returns:* `*this`.
1361
+
1362
  ``` cpp
1363
  basic_string& operator+=(const charT* s);
1364
  ```
1365
 
1366
  *Effects:* Calls `append(s)`.
 
1381
 
1382
  *Effects:* Calls `append(il)`.
1383
 
1384
  *Returns:* `*this`.
1385
 
1386
+ ##### `basic_string::append` <a id="string.append">[[string.append]]</a>
1387
 
1388
  ``` cpp
1389
  basic_string&
1390
  append(const basic_string& str);
1391
  ```
 
1397
  ``` cpp
1398
  basic_string&
1399
  append(const basic_string& str, size_type pos, size_type n = npos);
1400
  ```
1401
 
 
 
1402
  *Throws:* `out_of_range` if `pos > str.size()`.
1403
 
1404
  *Effects:* Determines the effective length `rlen` of the string to
1405
  append as the smaller of `n` and `str``.size() - ``pos` and calls
1406
  `append(str.data() + pos, rlen)`.
1407
 
1408
  *Returns:* `*this`.
1409
 
1410
+ ``` cpp
1411
+ basic_string& append(basic_string_view<charT, traits> sv);
1412
+ ```
1413
+
1414
+ *Effects:* Equivalent to: `return append(sv.data(), sv.size());`
1415
+
1416
+ ``` cpp
1417
+ template<class T>
1418
+ basic_string& append(const T& t, size_type pos, size_type n = npos);
1419
+ ```
1420
+
1421
+ *Throws:* `out_of_range` if `pos > sv.size()`.
1422
+
1423
+ *Effects:* Creates a variable, `sv`, as if by
1424
+ `basic_string_view<charT, traits> sv = t`. Determines the effective
1425
+ length `rlen` of the string to append as the smaller of `n` and
1426
+ `sv.size() - pos` and calls `append(sv.data() + pos, rlen)`.
1427
+
1428
+ *Remarks:* This function shall not participate in overload resolution
1429
+ unless `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
1430
+ `true` and `is_convertible_v<const T&, const charT*>` is `false`.
1431
+
1432
+ *Returns:* `*this`.
1433
+
1434
  ``` cpp
1435
  basic_string&
1436
  append(const charT* s, size_type n);
1437
  ```
1438
 
 
1471
  basic_string& append(InputIterator first, InputIterator last);
1472
  ```
1473
 
1474
  *Requires:* \[`first`, `last`) is a valid range.
1475
 
1476
+ *Effects:* Equivalent to
1477
+ `append(basic_string(first, last, get_allocator()))`.
1478
 
1479
  *Returns:* `*this`.
1480
 
1481
  ``` cpp
1482
  basic_string& append(initializer_list<charT> il);
 
1490
  void push_back(charT c);
1491
  ```
1492
 
1493
  *Effects:* Equivalent to `append(static_cast<size_type>(1), c)`.
1494
 
1495
+ ##### `basic_string::assign` <a id="string.assign">[[string.assign]]</a>
1496
 
1497
  ``` cpp
1498
  basic_string& assign(const basic_string& str);
1499
  ```
1500
 
1501
+ *Effects:* Equivalent to `*this = str`.
1502
 
1503
  *Returns:* `*this`.
1504
 
1505
  ``` cpp
1506
+ basic_string& assign(basic_string&& str)
1507
+ noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
1508
+ allocator_traits<Allocator>::is_always_equal::value);
1509
  ```
1510
 
1511
+ *Effects:* Equivalent to `*this = std::move(str)`.
 
 
1512
 
1513
  *Returns:* `*this`.
1514
 
1515
  ``` cpp
1516
  basic_string&
1517
  assign(const basic_string& str, size_type pos,
1518
  size_type n = npos);
1519
  ```
1520
 
 
 
1521
  *Throws:* `out_of_range` if `pos > str.size()`.
1522
 
1523
  *Effects:* Determines the effective length `rlen` of the string to
1524
  assign as the smaller of `n` and `str``.size() - ``pos` and calls
1525
+ `assign(str.data() + pos, rlen)`.
1526
+
1527
+ *Returns:* `*this`.
1528
+
1529
+ ``` cpp
1530
+ basic_string& assign(basic_string_view<charT, traits> sv);
1531
+ ```
1532
+
1533
+ *Effects:* Equivalent to: `return assign(sv.data(), sv.size());`
1534
+
1535
+ ``` cpp
1536
+ template<class T>
1537
+ basic_string& assign(const T& t, size_type pos, size_type n = npos);
1538
+ ```
1539
+
1540
+ *Throws:* `out_of_range` if `pos > sv.size()`.
1541
+
1542
+ *Effects:* Creates a variable, `sv`, as if by
1543
+ `basic_string_view<charT, traits> sv = t`. Determines the effective
1544
+ length `rlen` of the string to assign as the smaller of `n` and
1545
+ `sv.size() - pos` and calls `assign(sv.data() + pos, rlen)`.
1546
+
1547
+ *Remarks:* This function shall not participate in overload resolution
1548
+ unless `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
1549
+ `true` and `is_convertible_v<const T&, const charT*>` is `false`.
1550
 
1551
  *Returns:* `*this`.
1552
 
1553
  ``` cpp
1554
  basic_string& assign(const charT* s, size_type n);
 
1593
  ``` cpp
1594
  template<class InputIterator>
1595
  basic_string& assign(InputIterator first, InputIterator last);
1596
  ```
1597
 
1598
+ *Effects:* Equivalent to
1599
+ `assign(basic_string(first, last, get_allocator()))`.
1600
 
1601
  *Returns:* `*this`.
1602
 
1603
+ ##### `basic_string::insert` <a id="string.insert">[[string.insert]]</a>
1604
 
1605
  ``` cpp
1606
  basic_string&
1607
+ insert(size_type pos,
1608
  const basic_string& str);
1609
  ```
1610
 
1611
+ *Effects:* Equivalent to: `return insert(pos, str.data(), str.size());`
 
 
 
 
 
 
1612
 
1613
  ``` cpp
1614
  basic_string&
1615
  insert(size_type pos1,
1616
  const basic_string& str,
1617
  size_type pos2, size_type n = npos);
1618
  ```
1619
 
 
 
1620
  *Throws:* `out_of_range` if `pos1 > size()` or `pos2 > str.size()`.
1621
 
1622
  *Effects:* Determines the effective length `rlen` of the string to
1623
  insert as the smaller of `n` and `str.size() - pos2` and calls
1624
  `insert(pos1, str.data() + pos2, rlen)`.
1625
 
1626
  *Returns:* `*this`.
1627
 
1628
+ ``` cpp
1629
+ basic_string& insert(size_type pos, basic_string_view<charT, traits> sv);
1630
+ ```
1631
+
1632
+ *Effects:* Equivalent to: `return insert(pos, sv.data(), sv.size());`
1633
+
1634
+ ``` cpp
1635
+ template<class T>
1636
+ basic_string& insert(size_type pos1, const T& t,
1637
+ size_type pos2, size_type n = npos);
1638
+ ```
1639
+
1640
+ *Throws:* `out_of_range` if `pos1 > size()` or `pos2 > sv.size()`.
1641
+
1642
+ *Effects:* Creates a variable, `sv`, as if by
1643
+ `basic_string_view<charT, traits> sv = t`. Determines the effective
1644
+ length `rlen` of the string to assign as the smaller of `n` and
1645
+ `sv.size() - pos2` and calls `insert(pos1, sv.data() + pos2, rlen)`.
1646
+
1647
+ *Remarks:* This function shall not participate in overload resolution
1648
+ unless `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
1649
+ `true` and `is_convertible_v<const T&, const charT*>` is `false`.
1650
+
1651
+ *Returns:* `*this`.
1652
+
1653
  ``` cpp
1654
  basic_string&
1655
  insert(size_type pos, const charT* s, size_type n);
1656
  ```
1657
 
1658
+ *Requires:* `s` points to an array of at least `n` elements of `charT`.
 
1659
 
1660
  *Throws:* `out_of_range` if `pos > size()` or `length_error` if
1661
  `size() + n > max_size()`.
1662
 
1663
  *Effects:* Replaces the string controlled by `*this` with a string of
 
1672
  ``` cpp
1673
  basic_string&
1674
  insert(size_type pos, const charT* s);
1675
  ```
1676
 
1677
+ *Requires:* `s` points to an array of at least `traits::length(s) + 1`
1678
+ elements of `charT`.
1679
 
1680
+ *Effects:* Equivalent to: `return insert(pos, s, traits::length(s));`
 
 
1681
 
1682
  ``` cpp
1683
  basic_string&
1684
  insert(size_type pos, size_type n, charT c);
1685
  ```
 
1692
  iterator insert(const_iterator p, charT c);
1693
  ```
1694
 
1695
  *Requires:* `p` is a valid iterator on `*this`.
1696
 
1697
+ *Effects:* Inserts a copy of `c` before the character referred to by
1698
  `p`.
1699
 
1700
  *Returns:* An iterator which refers to the copy of the inserted
1701
  character.
1702
 
 
1704
  iterator insert(const_iterator p, size_type n, charT c);
1705
  ```
1706
 
1707
  *Requires:* `p` is a valid iterator on `*this`.
1708
 
1709
+ *Effects:* Inserts `n` copies of `c` before the character referred to by
1710
  `p`.
1711
 
1712
  *Returns:* An iterator which refers to the copy of the first inserted
1713
  character, or `p` if `n == 0`.
1714
 
 
1719
 
1720
  *Requires:* `p` is a valid iterator on `*this`. `[first, last)` is a
1721
  valid range.
1722
 
1723
  *Effects:* Equivalent to
1724
+ `insert(p - begin(), basic_string(first, last, get_allocator()))`.
1725
 
1726
  *Returns:* An iterator which refers to the copy of the first inserted
1727
  character, or `p` if `first == last`.
1728
 
1729
  ``` cpp
1730
  iterator insert(const_iterator p, initializer_list<charT> il);
1731
  ```
1732
 
1733
+ *Effects:* As if by `insert(p, il.begin(), il.end())`.
1734
 
1735
  *Returns:* An iterator which refers to the copy of the first inserted
1736
  character, or `p` if `i1` is empty.
1737
 
1738
+ ##### `basic_string::erase` <a id="string.erase">[[string.erase]]</a>
1739
 
1740
  ``` cpp
1741
  basic_string& erase(size_type pos = 0, size_type n = npos);
1742
  ```
1743
 
 
 
1744
  *Throws:* `out_of_range` if `pos` `> size()`.
1745
 
1746
  *Effects:* Determines the effective length `xlen` of the string to be
1747
  removed as the smaller of `n` and `size() - pos`.
1748
 
 
1758
  iterator erase(const_iterator p);
1759
  ```
1760
 
1761
  *Throws:* Nothing.
1762
 
1763
+ *Effects:* Removes the character referred to by `p`.
1764
 
1765
  *Returns:* An iterator which points to the element immediately following
1766
  `p` prior to the element being erased. If no such element exists,
1767
  `end()` is returned.
1768
 
 
1773
  *Requires:* `first` and `last` are valid iterators on `*this`, defining
1774
  a range `[first, last)`.
1775
 
1776
  *Throws:* Nothing.
1777
 
1778
+ *Effects:* Removes the characters in the range `[first, last)`.
1779
 
1780
  *Returns:* An iterator which points to the element pointed to by `last`
1781
  prior to the other elements being erased. If no such element exists,
1782
  `end()` is returned.
1783
 
1784
  ``` cpp
1785
  void pop_back();
1786
  ```
1787
 
1788
+ *Requires:* `!empty()`.
1789
 
1790
  *Throws:* Nothing.
1791
 
1792
  *Effects:* Equivalent to `erase(size() - 1, 1)`.
1793
 
1794
+ ##### `basic_string::replace` <a id="string.replace">[[string.replace]]</a>
1795
 
1796
  ``` cpp
1797
  basic_string&
1798
  replace(size_type pos1, size_type n1,
1799
  const basic_string& str);
1800
  ```
1801
 
1802
+ *Effects:* Equivalent to:
1803
+ `return replace(pos1, n1, str.data(), str.size());`
 
 
 
 
 
1804
 
1805
  ``` cpp
1806
  basic_string&
1807
  replace(size_type pos1, size_type n1,
1808
  const basic_string& str,
1809
  size_type pos2, size_type n2 = npos);
1810
  ```
1811
 
 
 
1812
  *Throws:* `out_of_range` if `pos1 > size()` or `pos2 > str.size()`.
1813
 
1814
  *Effects:* Determines the effective length `rlen` of the string to be
1815
  inserted as the smaller of `n2` and `str.size() - pos2` and calls
1816
  `replace(pos1, n1, str.data() + pos2, rlen)`.
1817
 
1818
  *Returns:* `*this`.
1819
 
1820
+ ``` cpp
1821
+ basic_string& replace(size_type pos1, size_type n1,
1822
+ basic_string_view<charT, traits> sv);
1823
+ ```
1824
+
1825
+ *Effects:* Equivalent to:
1826
+ `return replace(pos1, n1, sv.data(), sv.size());`
1827
+
1828
+ ``` cpp
1829
+ template<class T>
1830
+ basic_string& replace(size_type pos1, size_type n1, const T& t,
1831
+ size_type pos2, size_type n2 = npos);
1832
+ ```
1833
+
1834
+ *Throws:* `out_of_range` if `pos1 > size()` or `pos2 > sv.size()`.
1835
+
1836
+ *Effects:* Creates a variable, `sv`, as if by
1837
+ `basic_string_view<charT, traits> sv = t`. Determines the effective
1838
+ length `rlen` of the string to be inserted as the smaller of `n2` and
1839
+ `sv.size() - pos2` and calls
1840
+ `replace(pos1, n1, sv.data() + pos2, rlen)`.
1841
+
1842
+ *Remarks:* This function shall not participate in overload resolution
1843
+ unless `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
1844
+ `true` and `is_convertible_v<const T&, const charT*>` is `false`.
1845
+
1846
+ *Returns:* `*this`.
1847
+
1848
  ``` cpp
1849
  basic_string&
1850
  replace(size_type pos1, size_type n1, const charT* s, size_type n2);
1851
  ```
1852
 
1853
+ *Requires:* `s` points to an array of at least `n2` elements of `charT`.
 
1854
 
1855
  *Throws:* `out_of_range` if `pos1 > size()` or `length_error` if the
1856
  length of the resulting string would exceed `max_size()` (see below).
1857
 
1858
  *Effects:* Determines the effective length `xlen` of the string to be
 
1870
  ``` cpp
1871
  basic_string&
1872
  replace(size_type pos, size_type n, const charT* s);
1873
  ```
1874
 
1875
+ *Requires:* `s` points to an array of at least `traits::length(s) + 1`
1876
+ elements of `charT`.
1877
 
1878
+ *Effects:* Equivalent to:
1879
+ `return replace(pos, n, s, traits::length(s));`
 
1880
 
1881
  ``` cpp
1882
  basic_string&
1883
  replace(size_type pos1, size_type n1,
1884
  size_type n2, charT c);
 
1896
 
1897
  *Effects:* Calls `replace(i1 - begin(), i2 - i1, str)`.
1898
 
1899
  *Returns:* `*this`.
1900
 
1901
+ ``` cpp
1902
+ basic_string& replace(const_iterator i1, const_iterator i2,
1903
+ basic_string_view<charT, traits> sv);
1904
+ ```
1905
+
1906
+ *Requires:* \[`begin()`, `i1`) and \[`i1`, `i2`) are valid ranges.
1907
+
1908
+ *Effects:* Calls `replace(i1 - begin(), i2 - i1, sv)`.
1909
+
1910
+ *Returns:* `*this`.
1911
+
1912
  ``` cpp
1913
  basic_string&
1914
  replace(const_iterator i1, const_iterator i2, const charT* s, size_type n);
1915
  ```
1916
 
 
1951
  ```
1952
 
1953
  *Requires:* \[`begin()`, `i1`), \[`i1`, `i2`) and \[`j1`, `j2`) are
1954
  valid ranges.
1955
 
1956
+ *Effects:* Calls
1957
+ `replace(i1 - begin(), i2 - i1, basic_string(j1, j2, get_allocator()))`.
1958
 
1959
  *Returns:* `*this`.
1960
 
1961
  ``` cpp
1962
  basic_string& replace(const_iterator i1, const_iterator i2,
 
1968
  *Effects:* Calls
1969
  `replace(i1 - begin(), i2 - i1, il.begin(), il.size())`.
1970
 
1971
  *Returns:* `*this`.
1972
 
1973
+ ##### `basic_string::copy` <a id="string.copy">[[string.copy]]</a>
1974
 
1975
  ``` cpp
1976
  size_type copy(charT* s, size_type n, size_type pos = 0) const;
1977
  ```
1978
 
1979
+ Let `rlen` be the smaller of `n` and `size() - pos`.
1980
 
1981
  *Throws:* `out_of_range` if `pos > size()`.
1982
 
1983
+ *Requires:* \[`s`, `s + rlen`) is a valid range.
 
 
1984
 
1985
+ *Effects:* Equivalent to: `traits::copy(s, data() + pos, rlen)`.
 
 
1986
 
1987
+ [*Note 1*: This does not terminate `s` with a null
1988
+ object. — *end note*]
1989
 
1990
  *Returns:* `rlen`.
1991
 
1992
+ ##### `basic_string::swap` <a id="string.swap">[[string.swap]]</a>
1993
 
1994
  ``` cpp
1995
+ void swap(basic_string& s)
1996
+ noexcept(allocator_traits<Allocator>::propagate_on_container_swap::value ||
1997
+ allocator_traits<Allocator>::is_always_equal::value);
1998
  ```
1999
 
2000
+ *Postconditions:* `*this` contains the same sequence of characters that
2001
+ was in `s`, `s` contains the same sequence of characters that was in
2002
+ `*this`.
2003
 
2004
  *Throws:* Nothing.
2005
 
2006
  *Complexity:* Constant time.
2007
 
2008
+ #### `basic_string` string operations <a id="string.ops">[[string.ops]]</a>
2009
 
2010
+ ##### `basic_string` accessors <a id="string.accessors">[[string.accessors]]</a>
2011
 
2012
  ``` cpp
2013
  const charT* c_str() const noexcept;
2014
  const charT* data() const noexcept;
2015
  ```
 
2020
  *Complexity:* Constant time.
2021
 
2022
  *Requires:* The program shall not alter any of the values stored in the
2023
  character array.
2024
 
2025
+ ``` cpp
2026
+ charT* data() noexcept;
2027
+ ```
2028
+
2029
+ *Returns:* A pointer `p` such that `p + i == &operator[](i)` for each
2030
+ `i` in \[`0`, `size()`\].
2031
+
2032
+ *Complexity:* Constant time.
2033
+
2034
+ *Requires:* The program shall not alter the value stored at
2035
+ `p + size()`.
2036
+
2037
+ ``` cpp
2038
+ operator basic_string_view<charT, traits>() const noexcept;
2039
+ ```
2040
+
2041
+ *Effects:* Equivalent to:
2042
+ `return basic_string_view<charT, traits>(data(), size());`
2043
+
2044
  ``` cpp
2045
  allocator_type get_allocator() const noexcept;
2046
  ```
2047
 
2048
  *Returns:* A copy of the `Allocator` object used to construct the string
2049
  or, if that allocator has been replaced, a copy of the most recent
2050
  replacement.
2051
 
2052
+ ##### `basic_string::find` <a id="string.find">[[string.find]]</a>
2053
 
2054
  ``` cpp
2055
+ size_type find(basic_string_view<charT, traits> sv, size_type pos = 0) const noexcept;
 
2056
  ```
2057
 
2058
  *Effects:* Determines the lowest position `xpos`, if possible, such that
2059
+ both of the following conditions hold:
2060
 
2061
+ - `pos <= xpos` and `xpos + sv.size() <= size()`;
2062
+ - `traits::eq(at(xpos + I), sv.at(I))` for all elements `I` of the data
2063
+ referenced by `sv`.
2064
 
2065
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
2066
  Otherwise, returns `npos`.
2067
 
2068
+ ``` cpp
2069
+ size_type find(const basic_string& str, size_type pos = 0) const noexcept;
2070
+ ```
2071
+
2072
+ *Effects:* Equivalent to:
2073
+ `return find(basic_string_view<charT, traits>(str), pos);`
2074
 
2075
  ``` cpp
2076
  size_type find(const charT* s, size_type pos, size_type n) const;
2077
  ```
2078
 
2079
+ *Returns:* `find(basic_string_view<charT, traits>(s, n), pos)`.
2080
 
2081
  ``` cpp
2082
  size_type find(const charT* s, size_type pos = 0) const;
2083
  ```
2084
 
2085
  *Requires:* `s` points to an array of at least `traits::length(s) + 1`
2086
  elements of `charT`.
2087
 
2088
+ *Returns:* `find(basic_string_view<charT, traits>(s), pos)`.
2089
 
2090
  ``` cpp
2091
  size_type find(charT c, size_type pos = 0) const;
2092
  ```
2093
 
2094
  *Returns:* `find(basic_string(1, c), pos)`.
2095
 
2096
+ ##### `basic_string::rfind` <a id="string.rfind">[[string.rfind]]</a>
2097
 
2098
  ``` cpp
2099
+ size_type rfind(basic_string_view<charT, traits> sv, size_type pos = npos) const noexcept;
 
2100
  ```
2101
 
2102
  *Effects:* Determines the highest position `xpos`, if possible, such
2103
+ that both of the following conditions hold:
2104
 
2105
+ - `xpos <= pos` and `xpos + sv.size() <= size()`;
2106
+ - `traits::eq(at(xpos + I), sv.at(I))` for all elements `I` of the data
2107
+ referenced by `sv`.
2108
 
2109
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
2110
  Otherwise, returns `npos`.
2111
 
2112
+ ``` cpp
2113
+ size_type rfind(const basic_string& str, size_type pos = npos) const noexcept;
2114
+ ```
2115
+
2116
+ *Effects:* Equivalent to:
2117
+ `return rfind(basic_string_view<charT, traits>(str), pos);`
2118
 
2119
  ``` cpp
2120
  size_type rfind(const charT* s, size_type pos, size_type n) const;
2121
  ```
2122
 
2123
+ *Returns:* `rfind(basic_string_view<charT, traits>(s, n), pos)`.
2124
 
2125
  ``` cpp
2126
  size_type rfind(const charT* s, size_type pos = npos) const;
2127
  ```
2128
 
2129
+ *Requires:* `s` points to an array of at least `traits::length(s) + 1`
2130
  elements of `charT`.
2131
 
2132
+ *Returns:* `rfind(basic_string_view<charT, traits>(s), pos)`.
2133
 
2134
  ``` cpp
2135
  size_type rfind(charT c, size_type pos = npos) const;
2136
  ```
2137
 
2138
  *Returns:* `rfind(basic_string(1, c), pos)`.
2139
 
2140
+ ##### `basic_string::find_first_of` <a id="string.find.first.of">[[string.find.first.of]]</a>
2141
 
2142
  ``` cpp
2143
+ size_type find_first_of(basic_string_view<charT, traits> sv, size_type pos = 0) const noexcept;
 
 
2144
  ```
2145
 
2146
  *Effects:* Determines the lowest position `xpos`, if possible, such that
2147
+ both of the following conditions hold:
2148
 
2149
  - `pos <= xpos` and `xpos < size()`;
2150
+ - `traits::eq(at(xpos), sv.at(I))` for some element `I` of the data
2151
+ referenced by `sv`.
2152
 
2153
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
2154
  Otherwise, returns `npos`.
2155
 
2156
+ ``` cpp
2157
+ size_type find_first_of(const basic_string& str, size_type pos = 0) const noexcept;
2158
+ ```
2159
+
2160
+ *Effects:* Equivalent to:
2161
+ `return find_first_of(basic_string_view<charT, traits>(str), pos);`
2162
 
2163
  ``` cpp
2164
+ size_type find_first_of(const charT* s, size_type pos, size_type n) const;
 
2165
  ```
2166
 
2167
+ *Returns:* `find_first_of(basic_string_view<charT, traits>(s, n), pos)`.
2168
 
2169
  ``` cpp
2170
  size_type find_first_of(const charT* s, size_type pos = 0) const;
2171
  ```
2172
 
2173
  *Requires:* `s` points to an array of at least `traits::length(s) + 1`
2174
  elements of `charT`.
2175
 
2176
+ *Returns:* `find_first_of(basic_string_view<charT, traits>(s), pos)`.
2177
 
2178
  ``` cpp
2179
  size_type find_first_of(charT c, size_type pos = 0) const;
2180
  ```
2181
 
2182
  *Returns:* `find_first_of(basic_string(1, c), pos)`.
2183
 
2184
+ ##### `basic_string::find_last_of` <a id="string.find.last.of">[[string.find.last.of]]</a>
2185
 
2186
  ``` cpp
2187
+ size_type find_last_of(basic_string_view<charT, traits> sv, size_type pos = npos) const noexcept;
 
 
2188
  ```
2189
 
2190
  *Effects:* Determines the highest position `xpos`, if possible, such
2191
+ that both of the following conditions hold:
2192
 
2193
  - `xpos <= pos` and `xpos < size()`;
2194
+ - `traits::eq(at(xpos), sv.at(I))` for some element `I` of the data
2195
+ referenced by `sv`.
2196
 
2197
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
2198
  Otherwise, returns `npos`.
2199
 
2200
+ ``` cpp
2201
+ size_type find_last_of(const basic_string& str, size_type pos = npos) const noexcept;
2202
+ ```
2203
+
2204
+ *Effects:* Equivalent to:
2205
+ `return find_last_of(basic_string_view<charT, traits>(str), pos);`
2206
 
2207
  ``` cpp
2208
  size_type find_last_of(const charT* s, size_type pos, size_type n) const;
2209
  ```
2210
 
2211
+ *Returns:* `find_last_of(basic_string_view<charT, traits>(s, n), pos)`.
2212
 
2213
  ``` cpp
2214
  size_type find_last_of(const charT* s, size_type pos = npos) const;
2215
  ```
2216
 
2217
  *Requires:* `s` points to an array of at least `traits::length(s) + 1`
2218
  elements of `charT`.
2219
 
2220
+ *Returns:* `find_last_of(basic_string_view<charT, traits>(s), pos)`.
2221
 
2222
  ``` cpp
2223
  size_type find_last_of(charT c, size_type pos = npos) const;
2224
  ```
2225
 
2226
  *Returns:* `find_last_of(basic_string(1, c), pos)`.
2227
 
2228
+ ##### `basic_string::find_first_not_of` <a id="string.find.first.not.of">[[string.find.first.not.of]]</a>
2229
 
2230
  ``` cpp
2231
+ size_type find_first_not_of(basic_string_view<charT, traits> sv,
 
2232
  size_type pos = 0) const noexcept;
2233
  ```
2234
 
2235
  *Effects:* Determines the lowest position `xpos`, if possible, such that
2236
+ both of the following conditions hold:
2237
 
2238
  - `pos <= xpos` and `xpos < size()`;
2239
+ - `traits::eq(at(xpos), sv.at(I))` for no element `I` of the data
2240
+ referenced by `sv`.
2241
 
2242
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
2243
  Otherwise, returns `npos`.
2244
 
2245
+ ``` cpp
2246
+ size_type find_first_not_of(const basic_string& str, size_type pos = 0) const noexcept;
2247
+ ```
2248
+
2249
+ *Effects:* Equivalent to:
2250
+
2251
+ ``` cpp
2252
+ return find_first_not_of(basic_string_view<charT, traits>(str), pos);
2253
+ ```
2254
 
2255
  ``` cpp
2256
+ size_type find_first_not_of(const charT* s, size_type pos, size_type n) const;
 
2257
  ```
2258
 
2259
+ *Returns:*
2260
+ `find_first_not_of(basic_string_view<charT, traits>(s, n), pos)`.
2261
 
2262
  ``` cpp
2263
  size_type find_first_not_of(const charT* s, size_type pos = 0) const;
2264
  ```
2265
 
2266
  *Requires:* `s` points to an array of at least `traits::length(s) + 1`
2267
  elements of `charT`.
2268
 
2269
+ *Returns:*
2270
+ `find_first_not_of(basic_string_view<charT, traits>(s), pos)`.
2271
 
2272
  ``` cpp
2273
  size_type find_first_not_of(charT c, size_type pos = 0) const;
2274
  ```
2275
 
2276
  *Returns:* `find_first_not_of(basic_string(1, c), pos)`.
2277
 
2278
+ ##### `basic_string::find_last_not_of` <a id="string.find.last.not.of">[[string.find.last.not.of]]</a>
2279
 
2280
  ``` cpp
2281
+ size_type find_last_not_of(basic_string_view<charT, traits> sv,
 
2282
  size_type pos = npos) const noexcept;
2283
  ```
2284
 
2285
  *Effects:* Determines the highest position `xpos`, if possible, such
2286
+ that both of the following conditions hold:
2287
 
2288
  - `xpos <= pos` and `xpos < size()`;
2289
+ - `traits::eq(at(xpos), sv.at(I))` for no element `I` of the data
2290
+ referenced by `sv`.
2291
 
2292
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
2293
  Otherwise, returns `npos`.
2294
 
2295
+ ``` cpp
2296
+ size_type find_last_not_of(const basic_string& str, size_type pos = npos) const noexcept;
2297
+ ```
2298
+
2299
+ *Effects:* Equivalent to:
2300
+
2301
+ ``` cpp
2302
+ return find_last_not_of(basic_string_view<charT, traits>(str), pos);
2303
+ ```
2304
 
2305
  ``` cpp
2306
+ size_type find_last_not_of(const charT* s, size_type pos, size_type n) const;
 
2307
  ```
2308
 
2309
+ *Returns:*
2310
+ `find_last_not_of(basic_string_view<charT, traits>(s, n), pos)`.
2311
 
2312
  ``` cpp
2313
  size_type find_last_not_of(const charT* s, size_type pos = npos) const;
2314
  ```
2315
 
2316
  *Requires:* `s` points to an array of at least `traits::length(s) + 1`
2317
  elements of `charT`.
2318
 
2319
+ *Returns:* `find_last_not_of(basic_string_view<charT, traits>(s), pos)`.
2320
 
2321
  ``` cpp
2322
  size_type find_last_not_of(charT c, size_type pos = npos) const;
2323
  ```
2324
 
2325
  *Returns:* `find_last_not_of(basic_string(1, c), pos)`.
2326
 
2327
+ ##### `basic_string::substr` <a id="string.substr">[[string.substr]]</a>
2328
 
2329
  ``` cpp
2330
  basic_string substr(size_type pos = 0, size_type n = npos) const;
2331
  ```
2332
 
 
 
2333
  *Throws:* `out_of_range` if `pos > size()`.
2334
 
2335
  *Effects:* Determines the effective length `rlen` of the string to copy
2336
  as the smaller of `n` and `size() - pos`.
2337
 
2338
  *Returns:* `basic_string(data()+pos, rlen)`.
2339
 
2340
+ ##### `basic_string::compare` <a id="string.compare">[[string.compare]]</a>
2341
 
2342
  ``` cpp
2343
+ int compare(basic_string_view<charT, traits> sv) const noexcept;
2344
  ```
2345
 
2346
+ *Effects:* Determines the effective length `rlen` of the strings to
2347
+ compare as the smaller of `size()` and `sv.size()`. The function then
2348
  compares the two strings by calling
2349
+ `traits::compare(data(), sv.data(), rlen)`.
2350
 
2351
  *Returns:* The nonzero result if the result of the comparison is
2352
  nonzero. Otherwise, returns a value as indicated in
2353
  Table  [[tab:strings.compare]].
2354
 
2355
  **Table: `compare()` results** <a id="tab:strings.compare">[tab:strings.compare]</a>
2356
 
2357
  | Condition | Return Value |
2358
+ | --------------------- | ------------ |
2359
+ | `size() < sv.size()` | `< 0` |
2360
+ | `size() == sv.size()` | ` 0` |
2361
+ | `size() > sv.size()` | `> 0` |
2362
 
2363
  ``` cpp
2364
+ int compare(size_type pos1, size_type n1, basic_string_view<charT, traits> sv) const;
 
2365
  ```
2366
 
2367
+ *Effects:* Equivalent to:
2368
+
2369
+ ``` cpp
2370
+ return basic_string_view<charT, traits>(data(), size()).substr(pos1, n1).compare(sv);
2371
+ ```
2372
+
2373
+ ``` cpp
2374
+ template<class T>
2375
+ int compare(size_type pos1, size_type n1, const T& t,
2376
+ size_type pos2, size_type n2 = npos) const;
2377
+ ```
2378
+
2379
+ *Effects:* Equivalent to:
2380
+
2381
+ ``` cpp
2382
+ basic_string_view<charT, traits> sv = t;
2383
+ return basic_string_view<charT, traits>(
2384
+ data(), size()).substr(pos1, n1).compare(sv.substr(pos2, n2));
2385
+ ```
2386
+
2387
+ *Remarks:* This function shall not participate in overload resolution
2388
+ unless `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
2389
+ `true` and `is_convertible_v<const T&, const charT*>` is `false`.
2390
+
2391
+ ``` cpp
2392
+ int compare(const basic_string& str) const noexcept;
2393
+ ```
2394
+
2395
+ *Effects:* Equivalent to:
2396
+ `return compare(basic_string_view<charT, traits>(str));`
2397
+
2398
+ ``` cpp
2399
+ int compare(size_type pos1, size_type n1, const basic_string& str) const;
2400
+ ```
2401
+
2402
+ *Effects:* Equivalent to:
2403
+ `return compare(pos1, n1, basic_string_view<charT, traits>(str));`
2404
 
2405
  ``` cpp
2406
  int compare(size_type pos1, size_type n1,
2407
  const basic_string& str,
2408
  size_type pos2, size_type n2 = npos) const;
2409
  ```
2410
 
2411
+ *Effects:* Equivalent to:
2412
+
2413
+ ``` cpp
2414
+ return compare(pos1, n1, basic_string_view<charT, traits>(str), pos2, n2);
2415
+ ```
2416
 
2417
  ``` cpp
2418
  int compare(const charT* s) const;
2419
  ```
2420
 
2421
  *Returns:* `compare(basic_string(s))`.
2422
 
2423
  ``` cpp
2424
+ int compare(size_type pos, size_type n1, const charT* s) const;
 
2425
  ```
2426
 
2427
  *Returns:* `basic_string(*this, pos, n1).compare(basic_string(s))`.
2428
 
2429
  ``` cpp
2430
+ int compare(size_type pos, size_type n1, const charT* s, size_type n2) const;
 
2431
  ```
2432
 
2433
  *Returns:* `basic_string(*this, pos, n1).compare(basic_string(s, n2))`.
2434
 
2435
  ### `basic_string` non-member functions <a id="string.nonmembers">[[string.nonmembers]]</a>
2436
 
2437
+ #### `operator+` <a id="string.op+">[[string.op+]]</a>
2438
 
2439
  ``` cpp
2440
  template<class charT, class traits, class Allocator>
2441
  basic_string<charT, traits, Allocator>
2442
  operator+(const basic_string<charT, traits, Allocator>& lhs,
2443
  const basic_string<charT, traits, Allocator>& rhs);
2444
  ```
2445
 
2446
+ *Returns:* `basic_string<charT, traits, Allocator>(lhs).append(rhs)`.
2447
 
2448
  ``` cpp
2449
  template<class charT, class traits, class Allocator>
2450
  basic_string<charT, traits, Allocator>
2451
  operator+(basic_string<charT, traits, Allocator>&& lhs,
2452
  const basic_string<charT, traits, Allocator>& rhs);
2453
  ```
2454
 
2455
+ *Returns:* `std::move(lhs.append(rhs))`.
2456
 
2457
  ``` cpp
2458
  template<class charT, class traits, class Allocator>
2459
  basic_string<charT, traits, Allocator>
2460
  operator+(const basic_string<charT, traits, Allocator>& lhs,
2461
  basic_string<charT, traits, Allocator>&& rhs);
2462
  ```
2463
 
2464
+ *Returns:* `std::move(rhs.insert(0, lhs))`.
2465
 
2466
  ``` cpp
2467
  template<class charT, class traits, class Allocator>
2468
  basic_string<charT, traits, Allocator>
2469
  operator+(basic_string<charT, traits, Allocator>&& lhs,
2470
  basic_string<charT, traits, Allocator>&& rhs);
2471
  ```
2472
 
2473
+ *Returns:* `std::move(lhs.append(rhs))`.
2474
+
2475
+ [*Note 1*: Or equivalently,
2476
+ `std::move(rhs.insert(0, lhs))`. — *end note*]
2477
 
2478
  ``` cpp
2479
  template<class charT, class traits, class Allocator>
2480
  basic_string<charT, traits, Allocator>
2481
  operator+(const charT* lhs,
 
2553
  charT rhs);
2554
  ```
2555
 
2556
  *Returns:* `std::move(lhs.append(1, rhs))`.
2557
 
2558
+ #### `operator==` <a id="string.operator==">[[string.operator==]]</a>
2559
 
2560
  ``` cpp
2561
  template<class charT, class traits, class Allocator>
2562
  bool operator==(const basic_string<charT, traits, Allocator>& lhs,
2563
  const basic_string<charT, traits, Allocator>& rhs) noexcept;
 
2582
  *Requires:* `rhs` points to an array of at least
2583
  `traits::length(rhs) + 1` elements of `charT`.
2584
 
2585
  *Returns:* `lhs.compare(rhs) == 0`.
2586
 
2587
+ #### `operator!=` <a id="string.op!=">[[string.op!=]]</a>
2588
 
2589
  ``` cpp
2590
  template<class charT, class traits, class Allocator>
2591
  bool operator!=(const basic_string<charT, traits, Allocator>& lhs,
2592
  const basic_string<charT, traits, Allocator>& rhs) noexcept;
 
2611
  *Requires:* `rhs` points to an array of at least
2612
  `traits::length(rhs) + 1` elements of `charT`.
2613
 
2614
  *Returns:* `lhs.compare(rhs) != 0`.
2615
 
2616
+ #### `operator<` <a id="string.op<">[[string.op<]]</a>
2617
 
2618
  ``` cpp
2619
  template<class charT, class traits, class Allocator>
2620
  bool operator< (const basic_string<charT, traits, Allocator>& lhs,
2621
  const basic_string<charT, traits, Allocator>& rhs) noexcept;
 
2637
  const charT* rhs);
2638
  ```
2639
 
2640
  *Returns:* `lhs.compare(rhs) < 0`.
2641
 
2642
+ #### `operator>` <a id="string.op>">[[string.op>]]</a>
2643
 
2644
  ``` cpp
2645
  template<class charT, class traits, class Allocator>
2646
  bool operator> (const basic_string<charT, traits, Allocator>& lhs,
2647
  const basic_string<charT, traits, Allocator>& rhs) noexcept;
 
2663
  const charT* rhs);
2664
  ```
2665
 
2666
  *Returns:* `lhs.compare(rhs) > 0`.
2667
 
2668
+ #### `operator<=` <a id="string.op<=">[[string.op<=]]</a>
2669
 
2670
  ``` cpp
2671
  template<class charT, class traits, class Allocator>
2672
  bool operator<=(const basic_string<charT, traits, Allocator>& lhs,
2673
  const basic_string<charT, traits, Allocator>& rhs) noexcept;
 
2689
  const charT* rhs);
2690
  ```
2691
 
2692
  *Returns:* `lhs.compare(rhs) <= 0`.
2693
 
2694
+ #### `operator>=` <a id="string.op>=">[[string.op>=]]</a>
2695
 
2696
  ``` cpp
2697
  template<class charT, class traits, class Allocator>
2698
  bool operator>=(const basic_string<charT, traits, Allocator>& lhs,
2699
  const basic_string<charT, traits, Allocator>& rhs) noexcept;
 
2720
  #### `swap` <a id="string.special">[[string.special]]</a>
2721
 
2722
  ``` cpp
2723
  template<class charT, class traits, class Allocator>
2724
  void swap(basic_string<charT, traits, Allocator>& lhs,
2725
+ basic_string<charT, traits, Allocator>& rhs)
2726
+ noexcept(noexcept(lhs.swap(rhs)));
2727
  ```
2728
 
2729
+ *Effects:* Equivalent to: `lhs.swap(rhs);`
2730
 
2731
  #### Inserters and extractors <a id="string.io">[[string.io]]</a>
2732
 
2733
  ``` cpp
2734
  template<class charT, class traits, class Allocator>
 
2737
  basic_string<charT, traits, Allocator>& str);
2738
  ```
2739
 
2740
  *Effects:* Behaves as a formatted input
2741
  function ([[istream.formatted.reqmts]]). After constructing a `sentry`
2742
+ object, if the sentry converts to `true`, calls `str.erase()` and then
2743
  extracts characters from `is` and appends them to `str` as if by calling
2744
  `str.append(1, c)`. If `is.width()` is greater than zero, the maximum
2745
  number `n` of characters appended is `is.width()`; otherwise `n` is
2746
  `str.max_size()`. Characters are extracted and appended until any of the
2747
  following occurs:
2748
 
2749
  - *n* characters are stored;
2750
  - end-of-file occurs on the input sequence;
2751
+ - `isspace(c, is.getloc())` is `true` for the next available input
2752
  character *c*.
2753
 
2754
  After the last character (if any) is extracted, `is.width(0)` is called
2755
+ and the `sentry` object is destroyed.
2756
 
2757
  If the function extracts no characters, it calls
2758
  `is.setstate(ios::failbit)`, which may throw
2759
  `ios_base::failure` ([[iostate.flags]]).
2760
 
2761
+ *Returns:* `is`.
2762
 
2763
  ``` cpp
2764
  template<class charT, class traits, class Allocator>
2765
  basic_ostream<charT, traits>&
2766
  operator<<(basic_ostream<charT, traits>& os,
2767
  const basic_string<charT, traits, Allocator>& str);
2768
  ```
2769
 
2770
+ *Effects:* Equivalent to:
2771
+ `return os << basic_string_view<charT, traits>(str);`
 
 
 
 
 
 
 
2772
 
2773
  ``` cpp
2774
  template<class charT, class traits, class Allocator>
2775
  basic_istream<charT, traits>&
2776
  getline(basic_istream<charT, traits>& is,
 
2784
  ```
2785
 
2786
  *Effects:* Behaves as an unformatted input
2787
  function ([[istream.unformatted]]), except that it does not affect the
2788
  value returned by subsequent calls to `basic_istream<>::gcount()`. After
2789
+ constructing a `sentry` object, if the sentry converts to `true`, calls
2790
  `str.erase()` and then extracts characters from `is` and appends them to
2791
  `str` as if by calling `str.append(1, c)` until any of the following
2792
  occurs:
2793
 
2794
  - end-of-file occurs on the input sequence (in which case, the `getline`
 
2797
  which case, *c* is extracted but not appended) ([[iostate.flags]])
2798
  - `str.max_size()` characters are stored (in which case, the function
2799
  calls `is.setstate(ios_base::failbit))` ([[iostate.flags]])
2800
 
2801
  The conditions are tested in the order shown. In any case, after the
2802
+ last character is extracted, the `sentry` object is destroyed.
2803
 
2804
  If the function extracts no characters, it calls
2805
  `is.setstate(ios_base::failbit)` which may throw
2806
  `ios_base::failure` ([[iostate.flags]]).
2807
 
 
2816
  basic_istream<charT, traits>&
2817
  getline(basic_istream<charT, traits>&& is,
2818
  basic_string<charT, traits, Allocator>& str);
2819
  ```
2820
 
2821
+ *Returns:* `getline(is, str, is.widen(’\n’))`.
2822
 
2823
+ ### Numeric conversions <a id="string.conversions">[[string.conversions]]</a>
2824
 
2825
  ``` cpp
2826
  int stoi(const string& str, size_t* idx = 0, int base = 10);
2827
  long stol(const string& str, size_t* idx = 0, int base = 10);
2828
  unsigned long stoul(const string& str, size_t* idx = 0, int base = 10);
 
2852
  float stof(const string& str, size_t* idx = 0);
2853
  double stod(const string& str, size_t* idx = 0);
2854
  long double stold(const string& str, size_t* idx = 0);
2855
  ```
2856
 
2857
+ *Effects:* These functions call `strtof(str.c_str(), ptr)`,
2858
+ `strtod(str.c_str(), ptr)`, and `strtold(str.c_str(), ptr)`,
2859
+ respectively. Each function returns the converted result, if any. The
2860
+ argument `ptr` designates a pointer to an object internal to the
2861
+ function that is used to determine what to store at `*idx`. If the
2862
+ function does not throw an exception and `idx != 0`, the function stores
2863
+ in `*idx` the index of the first unconverted element of `str`.
2864
 
2865
  *Returns:* The converted result.
2866
 
2867
+ *Throws:* `invalid_argument` if `strtof`, `strtod`, or `strtold` reports
2868
+ that no conversion could be performed. Throws `out_of_range` if
2869
+ `strtof`, `strtod`, or `strtold` sets `errno` to `ERANGE` or if the
2870
+ converted value is outside the range of representable values for the
2871
+ return type.
2872
 
2873
  ``` cpp
2874
  string to_string(int val);
2875
  string to_string(unsigned val);
2876
  string to_string(long val);
 
2918
  float stof(const wstring& str, size_t* idx = 0);
2919
  double stod(const wstring& str, size_t* idx = 0);
2920
  long double stold(const wstring& str, size_t* idx = 0);
2921
  ```
2922
 
2923
+ *Effects:* These functions call `wcstof(str.c_str(), ptr)`,
2924
+ `wcstod(str.c_str(), ptr)`, and `wcstold(str.c_str(), ptr)`,
2925
+ respectively. Each function returns the converted result, if any. The
2926
+ argument `ptr` designates a pointer to an object internal to the
2927
+ function that is used to determine what to store at `*idx`. If the
2928
+ function does not throw an exception and `idx != 0`, the function stores
2929
+ in `*idx` the index of the first unconverted element of `str`.
2930
 
2931
  *Returns:* The converted result.
2932
 
2933
+ *Throws:* `invalid_argument` if `wcstof`, `wcstod`, or `wcstold` reports
2934
+ that no conversion could be performed. Throws `out_of_range` if
2935
+ `wcstof`, `wcstod`, or `wcstold` sets `errno` to `ERANGE`.
2936
 
2937
  ``` cpp
2938
  wstring to_wstring(int val);
2939
  wstring to_wstring(unsigned val);
2940
  wstring to_wstring(long val);
 
2951
  generated by calling `swprintf(buf, buffsz, fmt, val)` with a format
2952
  specifier of `L"%d"`, `L"%u"`, `L"%ld"`, `L"%lu"`, `L"%lld"`, `L"%llu"`,
2953
  `L"%f"`, `L"%f"`, or `L"%Lf"`, respectively, where `buf` designates an
2954
  internal character buffer of sufficient size `buffsz`.
2955
 
2956
+ ### Hash support <a id="basic.string.hash">[[basic.string.hash]]</a>
2957
 
2958
  ``` cpp
2959
  template<> struct hash<string>;
2960
  template<> struct hash<u16string>;
2961
  template<> struct hash<u32string>;
2962
  template<> struct hash<wstring>;
2963
  ```
2964
 
2965
+ If `S` is one of these string types, `SV` is the corresponding string
2966
+ view type, and `s` is an object of type `S`, then
2967
+ `hash<S>()(s) == hash<SV>()(SV(s))`.
2968
 
2969
+ ### Suffix for `basic_string` literals <a id="basic.string.literals">[[basic.string.literals]]</a>
2970
 
2971
  ``` cpp
2972
  string operator""s(const char* str, size_t len);
2973
  ```
2974
 
2975
+ *Returns:* `string{str, len}`.
2976
 
2977
  ``` cpp
2978
  u16string operator""s(const char16_t* str, size_t len);
2979
  ```
2980
 
2981
+ *Returns:* `u16string{str, len}`.
2982
 
2983
  ``` cpp
2984
  u32string operator""s(const char32_t* str, size_t len);
2985
  ```
2986
 
2987
+ *Returns:* `u32string{str, len}`.
2988
 
2989
  ``` cpp
2990
  wstring operator""s(const wchar_t* str, size_t len);
2991
  ```
2992
 
2993
+ *Returns:* `wstring{str, len}`.
2994
 
2995
+ [*Note 1*: The same suffix `s` is used for `chrono::duration` literals
2996
+ denoting seconds but there is no conflict, since duration suffixes apply
2997
+ to numbers and string literal suffixes apply to character array
2998
+ literals. — *end note*]
2999
+
3000
+ ## String view classes <a id="string.view">[[string.view]]</a>
3001
+
3002
+ The class template `basic_string_view` describes an object that can
3003
+ refer to a constant contiguous sequence of char-like (
3004
+ [[strings.general]]) objects with the first element of the sequence at
3005
+ position zero. In the rest of this section, the type of the char-like
3006
+ objects held in a `basic_string_view` object is designated by `charT`.
3007
+
3008
+ [*Note 1*: The library provides implicit conversions from
3009
+ `const charT*` and `std::basic_string<charT, ...>` to
3010
+ `std::basic_string_view<charT, ...>` so that user code can accept just
3011
+ `std::basic_string_view<charT>` as a non-templated parameter wherever a
3012
+ sequence of characters is expected. User-defined types should define
3013
+ their own implicit conversions to `std::basic_string_view` in order to
3014
+ interoperate with these functions. — *end note*]
3015
+
3016
+ The complexity of `basic_string_view` member functions is 𝑂(1) unless
3017
+ otherwise specified.
3018
+
3019
+ ### Header `<string_view>` synopsis <a id="string.view.synop">[[string.view.synop]]</a>
3020
+
3021
+ ``` cpp
3022
+ namespace std {
3023
+ // [string.view.template], class template basic_string_view
3024
+ template<class charT, class traits = char_traits<charT>>
3025
+ class basic_string_view;
3026
+
3027
+ // [string.view.comparison], non-member comparison functions
3028
+ template<class charT, class traits>
3029
+ constexpr bool operator==(basic_string_view<charT, traits> x,
3030
+ basic_string_view<charT, traits> y) noexcept;
3031
+ template<class charT, class traits>
3032
+ constexpr bool operator!=(basic_string_view<charT, traits> x,
3033
+ basic_string_view<charT, traits> y) noexcept;
3034
+ template<class charT, class traits>
3035
+ constexpr bool operator< (basic_string_view<charT, traits> x,
3036
+ basic_string_view<charT, traits> y) noexcept;
3037
+ template<class charT, class traits>
3038
+ constexpr bool operator> (basic_string_view<charT, traits> x,
3039
+ basic_string_view<charT, traits> y) noexcept;
3040
+ template<class charT, class traits>
3041
+ constexpr bool operator<=(basic_string_view<charT, traits> x,
3042
+ basic_string_view<charT, traits> y) noexcept;
3043
+ template<class charT, class traits>
3044
+ constexpr bool operator>=(basic_string_view<charT, traits> x,
3045
+ basic_string_view<charT, traits> y) noexcept;
3046
+ // see [string.view.comparison], sufficient additional overloads of comparison functions
3047
+
3048
+ // [string.view.io], inserters and extractors
3049
+ template<class charT, class traits>
3050
+ basic_ostream<charT, traits>&
3051
+ operator<<(basic_ostream<charT, traits>& os,
3052
+ basic_string_view<charT, traits> str);
3053
+
3054
+ // basic_string_view typedef names
3055
+ using string_view = basic_string_view<char>;
3056
+ using u16string_view = basic_string_view<char16_t>;
3057
+ using u32string_view = basic_string_view<char32_t>;
3058
+ using wstring_view = basic_string_view<wchar_t>;
3059
+
3060
+ // [string.view.hash], hash support
3061
+ template<class T> struct hash;
3062
+ template<> struct hash<string_view>;
3063
+ template<> struct hash<u16string_view>;
3064
+ template<> struct hash<u32string_view>;
3065
+ template<> struct hash<wstring_view>;
3066
+
3067
+ inline namespace literals {
3068
+ inline namespace string_view_literals {
3069
+ // [string.view.literals], suffix for basic_string_view literals
3070
+ constexpr string_view operator""sv(const char* str, size_t len) noexcept;
3071
+ constexpr u16string_view operator""sv(const char16_t* str, size_t len) noexcept;
3072
+ constexpr u32string_view operator""sv(const char32_t* str, size_t len) noexcept;
3073
+ constexpr wstring_view operator""sv(const wchar_t* str, size_t len) noexcept;
3074
+ }
3075
+ }
3076
+ }
3077
+ ```
3078
+
3079
+ The function templates defined in [[utility.swap]] and
3080
+ [[iterator.range]] are available when `<string_view>` is included.
3081
+
3082
+ ### Class template `basic_string_view` <a id="string.view.template">[[string.view.template]]</a>
3083
+
3084
+ ``` cpp
3085
+ template<class charT, class traits = char_traits<charT>>
3086
+ class basic_string_view {
3087
+ public:
3088
+ // types
3089
+ using traits_type = traits;
3090
+ using value_type = charT;
3091
+ using pointer = value_type*;
3092
+ using const_pointer = const value_type*;
3093
+ using reference = value_type&;
3094
+ using const_reference = const value_type&;
3095
+ using const_iterator = implementation-defined // type of basic_string_view::const_iterator; // see [string.view.iterators]
3096
+ using iterator = const_iterator;\footnote{Because basic_string_view refers to a constant sequence, iterator and const_iterator are the same type.}
3097
+ using const_reverse_iterator = reverse_iterator<const_iterator>;
3098
+ using reverse_iterator = const_reverse_iterator;
3099
+ using size_type = size_t;
3100
+ using difference_type = ptrdiff_t;
3101
+ static constexpr size_type npos = size_type(-1);
3102
+
3103
+ // [string.view.cons], construction and assignment
3104
+ constexpr basic_string_view() noexcept;
3105
+ constexpr basic_string_view(const basic_string_view&) noexcept = default;
3106
+ constexpr basic_string_view& operator=(const basic_string_view&) noexcept = default;
3107
+ constexpr basic_string_view(const charT* str);
3108
+ constexpr basic_string_view(const charT* str, size_type len);
3109
+
3110
+ // [string.view.iterators], iterator support
3111
+ constexpr const_iterator begin() const noexcept;
3112
+ constexpr const_iterator end() const noexcept;
3113
+ constexpr const_iterator cbegin() const noexcept;
3114
+ constexpr const_iterator cend() const noexcept;
3115
+ constexpr const_reverse_iterator rbegin() const noexcept;
3116
+ constexpr const_reverse_iterator rend() const noexcept;
3117
+ constexpr const_reverse_iterator crbegin() const noexcept;
3118
+ constexpr const_reverse_iterator crend() const noexcept;
3119
+
3120
+ // [string.view.capacity], capacity
3121
+ constexpr size_type size() const noexcept;
3122
+ constexpr size_type length() const noexcept;
3123
+ constexpr size_type max_size() const noexcept;
3124
+ constexpr bool empty() const noexcept;
3125
+
3126
+ // [string.view.access], element access
3127
+ constexpr const_reference operator[](size_type pos) const;
3128
+ constexpr const_reference at(size_type pos) const;
3129
+ constexpr const_reference front() const;
3130
+ constexpr const_reference back() const;
3131
+ constexpr const_pointer data() const noexcept;
3132
+
3133
+ // [string.view.modifiers], modifiers
3134
+ constexpr void remove_prefix(size_type n);
3135
+ constexpr void remove_suffix(size_type n);
3136
+ constexpr void swap(basic_string_view& s) noexcept;
3137
+
3138
+ // [string.view.ops], string operations
3139
+ size_type copy(charT* s, size_type n, size_type pos = 0) const;
3140
+
3141
+ constexpr basic_string_view substr(size_type pos = 0, size_type n = npos) const;
3142
+ constexpr int compare(basic_string_view s) const noexcept;
3143
+ constexpr int compare(size_type pos1, size_type n1, basic_string_view s) const;
3144
+ constexpr int compare(size_type pos1, size_type n1, basic_string_view s,
3145
+ size_type pos2, size_type n2) const;
3146
+ constexpr int compare(const charT* s) const;
3147
+ constexpr int compare(size_type pos1, size_type n1, const charT* s) const;
3148
+ constexpr int compare(size_type pos1, size_type n1, const charT* s,
3149
+ size_type n2) const;
3150
+ constexpr size_type find(basic_string_view s, size_type pos = 0) const noexcept;
3151
+ constexpr size_type find(charT c, size_type pos = 0) const noexcept;
3152
+ constexpr size_type find(const charT* s, size_type pos, size_type n) const;
3153
+ constexpr size_type find(const charT* s, size_type pos = 0) const;
3154
+ constexpr size_type rfind(basic_string_view s, size_type pos = npos) const noexcept;
3155
+ constexpr size_type rfind(charT c, size_type pos = npos) const noexcept;
3156
+ constexpr size_type rfind(const charT* s, size_type pos, size_type n) const;
3157
+ constexpr size_type rfind(const charT* s, size_type pos = npos) const;
3158
+ constexpr size_type find_first_of(basic_string_view s, size_type pos = 0) const noexcept;
3159
+ constexpr size_type find_first_of(charT c, size_type pos = 0) const noexcept;
3160
+ constexpr size_type find_first_of(const charT* s, size_type pos, size_type n) const;
3161
+ constexpr size_type find_first_of(const charT* s, size_type pos = 0) const;
3162
+ constexpr size_type find_last_of(basic_string_view s, size_type pos = npos) const noexcept;
3163
+ constexpr size_type find_last_of(charT c, size_type pos = npos) const noexcept;
3164
+ constexpr size_type find_last_of(const charT* s, size_type pos, size_type n) const;
3165
+ constexpr size_type find_last_of(const charT* s, size_type pos = npos) const;
3166
+ constexpr size_type find_first_not_of(basic_string_view s, size_type pos = 0) const noexcept;
3167
+ constexpr size_type find_first_not_of(charT c, size_type pos = 0) const noexcept;
3168
+ constexpr size_type find_first_not_of(const charT* s, size_type pos,
3169
+ size_type n) const;
3170
+ constexpr size_type find_first_not_of(const charT* s, size_type pos = 0) const;
3171
+ constexpr size_type find_last_not_of(basic_string_view s,
3172
+ size_type pos = npos) const noexcept;
3173
+ constexpr size_type find_last_not_of(charT c, size_type pos = npos) const noexcept;
3174
+ constexpr size_type find_last_not_of(const charT* s, size_type pos,
3175
+ size_type n) const;
3176
+ constexpr size_type find_last_not_of(const charT* s, size_type pos = npos) const;
3177
+
3178
+ private:
3179
+ const_pointer data_; // exposition only
3180
+ size_type size_; // exposition only
3181
+ };
3182
+ ```
3183
+
3184
+ In every specialization `basic_string_view<charT, traits>`, the type
3185
+ `traits` shall satisfy the character traits requirements (
3186
+ [[char.traits]]), and the type `traits::char_type` shall name the same
3187
+ type as `charT`.
3188
+
3189
+ #### Construction and assignment <a id="string.view.cons">[[string.view.cons]]</a>
3190
+
3191
+ ``` cpp
3192
+ constexpr basic_string_view() noexcept;
3193
+ ```
3194
+
3195
+ *Effects:* Constructs an empty `basic_string_view`.
3196
+
3197
+ *Postconditions:* `size_ == 0` and `data_ == nullptr`.
3198
+
3199
+ ``` cpp
3200
+ constexpr basic_string_view(const charT* str);
3201
+ ```
3202
+
3203
+ *Requires:* \[`str`, `str + traits::length(str)`) is a valid range.
3204
+
3205
+ *Effects:* Constructs a `basic_string_view`, with the postconditions in
3206
+ Table  [[tab:string.view.ctr.2]].
3207
+
3208
+ *Complexity:* 𝑂(`traits::length(str)`).
3209
+
3210
+ ``` cpp
3211
+ constexpr basic_string_view(const charT* str, size_type len);
3212
+ ```
3213
+
3214
+ *Requires:* \[`str`, `str + len`) is a valid range.
3215
+
3216
+ *Effects:* Constructs a `basic_string_view`, with the postconditions in
3217
+ Table  [[tab:string.view.ctr.3]].
3218
+
3219
+ #### Iterator support <a id="string.view.iterators">[[string.view.iterators]]</a>
3220
+
3221
+ ``` cpp
3222
+ using const_iterator = implementation-defined // type of basic_string_view::const_iterator;
3223
+ ```
3224
+
3225
+ A type that meets the requirements of a constant random access
3226
+ iterator ([[random.access.iterators]]) and of a contiguous
3227
+ iterator ([[iterator.requirements.general]]) whose `value_type` is the
3228
+ template parameter `charT`.
3229
+
3230
+ For a `basic_string_view str`, any operation that invalidates a pointer
3231
+ in the range \[`str.data()`, `str.data() + str.size()`) invalidates
3232
+ pointers, iterators, and references returned from `str`’s methods.
3233
+
3234
+ All requirements on container iterators ([[container.requirements]])
3235
+ apply to `basic_string_view::const_iterator` as well.
3236
+
3237
+ ``` cpp
3238
+ constexpr const_iterator begin() const noexcept;
3239
+ constexpr const_iterator cbegin() const noexcept;
3240
+ ```
3241
+
3242
+ *Returns:* An iterator such that
3243
+
3244
+ - if `!empty()`, `&*begin() == data_`,
3245
+ - otherwise, an unspecified value such that \[`begin()`, `end()`) is a
3246
+ valid range.
3247
+
3248
+ ``` cpp
3249
+ constexpr const_iterator end() const noexcept;
3250
+ constexpr const_iterator cend() const noexcept;
3251
+ ```
3252
+
3253
+ *Returns:* `begin() + size()`.
3254
+
3255
+ ``` cpp
3256
+ constexpr const_reverse_iterator rbegin() const noexcept;
3257
+ constexpr const_reverse_iterator crbegin() const noexcept;
3258
+ ```
3259
+
3260
+ *Returns:* `const_reverse_iterator(end())`.
3261
+
3262
+ ``` cpp
3263
+ constexpr const_reverse_iterator rend() const noexcept;
3264
+ constexpr const_reverse_iterator crend() const noexcept;
3265
+ ```
3266
+
3267
+ *Returns:* `const_reverse_iterator(begin())`.
3268
+
3269
+ #### Capacity <a id="string.view.capacity">[[string.view.capacity]]</a>
3270
+
3271
+ ``` cpp
3272
+ constexpr size_type size() const noexcept;
3273
+ ```
3274
+
3275
+ *Returns:* `size_`.
3276
+
3277
+ ``` cpp
3278
+ constexpr size_type length() const noexcept;
3279
+ ```
3280
+
3281
+ *Returns:* `size_`.
3282
+
3283
+ ``` cpp
3284
+ constexpr size_type max_size() const noexcept;
3285
+ ```
3286
+
3287
+ *Returns:* The largest possible number of char-like objects that can be
3288
+ referred to by a `basic_string_view`.
3289
+
3290
+ ``` cpp
3291
+ constexpr bool empty() const noexcept;
3292
+ ```
3293
+
3294
+ *Returns:* `size_ == 0`.
3295
+
3296
+ #### Element access <a id="string.view.access">[[string.view.access]]</a>
3297
+
3298
+ ``` cpp
3299
+ constexpr const_reference operator[](size_type pos) const;
3300
+ ```
3301
+
3302
+ *Requires:* `pos < size()`.
3303
+
3304
+ *Returns:* `data_[pos]`.
3305
+
3306
+ *Throws:* Nothing.
3307
+
3308
+ [*Note 1*: Unlike `basic_string::operator[]`,
3309
+ `basic_string_view::operator[](size())` has undefined behavior instead
3310
+ of returning `charT()`. — *end note*]
3311
+
3312
+ ``` cpp
3313
+ constexpr const_reference at(size_type pos) const;
3314
+ ```
3315
+
3316
+ *Throws:* `out_of_range` if `pos >= size()`.
3317
+
3318
+ *Returns:* `data_[pos]`.
3319
+
3320
+ ``` cpp
3321
+ constexpr const_reference front() const;
3322
+ ```
3323
+
3324
+ *Requires:* `!empty()`.
3325
+
3326
+ *Returns:* `data_[0]`.
3327
+
3328
+ *Throws:* Nothing.
3329
+
3330
+ ``` cpp
3331
+ constexpr const_reference back() const;
3332
+ ```
3333
+
3334
+ *Requires:* `!empty()`.
3335
+
3336
+ *Returns:* `data_[size() - 1]`.
3337
+
3338
+ *Throws:* Nothing.
3339
+
3340
+ ``` cpp
3341
+ constexpr const_pointer data() const noexcept;
3342
+ ```
3343
+
3344
+ *Returns:* `data_`.
3345
+
3346
+ [*Note 2*: Unlike `basic_string::data()` and string literals, `data()`
3347
+ may return a pointer to a buffer that is not null-terminated. Therefore
3348
+ it is typically a mistake to pass `data()` to a function that takes just
3349
+ a `const charT*` and expects a null-terminated string. — *end note*]
3350
+
3351
+ #### Modifiers <a id="string.view.modifiers">[[string.view.modifiers]]</a>
3352
+
3353
+ ``` cpp
3354
+ constexpr void remove_prefix(size_type n);
3355
+ ```
3356
+
3357
+ *Requires:* `n <= size()`.
3358
+
3359
+ *Effects:* Equivalent to: `data_ += n; size_ -= n;`
3360
+
3361
+ ``` cpp
3362
+ constexpr void remove_suffix(size_type n);
3363
+ ```
3364
+
3365
+ *Requires:* `n <= size()`.
3366
+
3367
+ *Effects:* Equivalent to: `size_ -= n;`
3368
+
3369
+ ``` cpp
3370
+ constexpr void swap(basic_string_view& s) noexcept;
3371
+ ```
3372
+
3373
+ *Effects:* Exchanges the values of `*this` and `s`.
3374
+
3375
+ #### String operations <a id="string.view.ops">[[string.view.ops]]</a>
3376
+
3377
+ ``` cpp
3378
+ size_type copy(charT* s, size_type n, size_type pos = 0) const;
3379
+ ```
3380
+
3381
+ Let `rlen` be the smaller of `n` and `size() - pos`.
3382
+
3383
+ *Throws:* `out_of_range` if `pos > size()`.
3384
+
3385
+ *Requires:* \[`s`, `s + rlen`) is a valid range.
3386
+
3387
+ *Effects:* Equivalent to `traits::copy(s, data() + pos, rlen)`.
3388
+
3389
+ *Returns:* `rlen`.
3390
+
3391
+ *Complexity:* 𝑂(`rlen`).
3392
+
3393
+ ``` cpp
3394
+ constexpr basic_string_view substr(size_type pos = 0, size_type n = npos) const;
3395
+ ```
3396
+
3397
+ Let `rlen` be the smaller of `n` and `size() - pos`.
3398
+
3399
+ *Throws:* `out_of_range` if `pos > size()`.
3400
+
3401
+ *Effects:* Determines `rlen`, the effective length of the string to
3402
+ reference.
3403
+
3404
+ *Returns:* `basic_string_view(data() + pos, rlen)`.
3405
+
3406
+ ``` cpp
3407
+ constexpr int compare(basic_string_view str) const noexcept;
3408
+ ```
3409
+
3410
+ Let `rlen` be the smaller of `size()` and `str.size()`.
3411
+
3412
+ *Effects:* Determines `rlen`, the effective length of the strings to
3413
+ compare. The function then compares the two strings by calling
3414
+ `traits::compare(data(), str.data(), rlen)`.
3415
+
3416
+ *Complexity:* 𝑂(`rlen`).
3417
+
3418
+ *Returns:* The nonzero result if the result of the comparison is
3419
+ nonzero. Otherwise, returns a value as indicated in
3420
+ Table  [[tab:string.view.compare]].
3421
+
3422
+ **Table: `compare()` results** <a id="tab:string.view.compare">[tab:string.view.compare]</a>
3423
+
3424
+ | Condition | Return Value |
3425
+ | ---------------------- | ------------ |
3426
+ | `size() < str.size()` | `< 0` |
3427
+ | `size() == str.size()` | ` 0` |
3428
+ | `size() > str.size()` | `> 0` |
3429
+
3430
+ ``` cpp
3431
+ constexpr int compare(size_type pos1, size_type n1, basic_string_view str) const;
3432
+ ```
3433
+
3434
+ *Effects:* Equivalent to: `return substr(pos1, n1).compare(str);`
3435
+
3436
+ ``` cpp
3437
+ constexpr int compare(size_type pos1, size_type n1, basic_string_view str,
3438
+ size_type pos2, size_type n2) const;
3439
+ ```
3440
+
3441
+ *Effects:* Equivalent to:
3442
+ `return substr(pos1, n1).compare(str.substr(pos2, n2));`
3443
+
3444
+ ``` cpp
3445
+ constexpr int compare(const charT* s) const;
3446
+ ```
3447
+
3448
+ *Effects:* Equivalent to: `return compare(basic_string_view(s));`
3449
+
3450
+ ``` cpp
3451
+ constexpr int compare(size_type pos1, size_type n1, const charT* s) const;
3452
+ ```
3453
+
3454
+ *Effects:* Equivalent to:
3455
+ `return substr(pos1, n1).compare(basic_string_view(s));`
3456
+
3457
+ ``` cpp
3458
+ constexpr int compare(size_type pos1, size_type n1,
3459
+ const charT* s, size_type n2) const;
3460
+ ```
3461
+
3462
+ *Effects:* Equivalent to:
3463
+ `return substr(pos1, n1).compare(basic_string_view(s, n2));`
3464
+
3465
+ #### Searching <a id="string.view.find">[[string.view.find]]</a>
3466
+
3467
+ This section specifies the `basic_string_view` member functions named
3468
+ `find`, `rfind`, `find_first_of`, `find_last_of`, `find_first_not_of`,
3469
+ and `find_last_not_of`.
3470
+
3471
+ Member functions in this section have complexity
3472
+ 𝑂(`size() * str.size()`) at worst, although implementations are
3473
+ encouraged to do better.
3474
+
3475
+ Each member function of the form
3476
+
3477
+ ``` cpp
3478
+ constexpr return-type F(const charT* s, size_type pos);
3479
+ ```
3480
+
3481
+ is equivalent to `return F(basic_string_view(s), pos);`
3482
+
3483
+ Each member function of the form
3484
+
3485
+ ``` cpp
3486
+ constexpr return-type F(const charT* s, size_type pos, size_type n);
3487
+ ```
3488
+
3489
+ is equivalent to `return F(basic_string_view(s, n), pos);`
3490
+
3491
+ Each member function of the form
3492
+
3493
+ ``` cpp
3494
+ constexpr return-type F(charT c, size_type pos);
3495
+ ```
3496
+
3497
+ is equivalent to `return F(basic_string_view(&c, 1), pos);`
3498
+
3499
+ ``` cpp
3500
+ constexpr size_type find(basic_string_view str, size_type pos = 0) const noexcept;
3501
+ ```
3502
+
3503
+ Let `xpos` be the lowest position, if possible, such that the following
3504
+ conditions hold:
3505
+
3506
+ - `pos <= xpos`
3507
+ - `xpos + str.size() <= size()`
3508
+ - `traits::eq(at(xpos + I), str.at(I))` for all elements `I` of the
3509
+ string referenced by `str`.
3510
+
3511
+ *Effects:* Determines `xpos`.
3512
+
3513
+ *Returns:* `xpos` if the function can determine such a value for `xpos`.
3514
+ Otherwise, returns `npos`.
3515
+
3516
+ ``` cpp
3517
+ constexpr size_type rfind(basic_string_view str, size_type pos = npos) const noexcept;
3518
+ ```
3519
+
3520
+ Let `xpos` be the highest position, if possible, such that the following
3521
+ conditions hold:
3522
+
3523
+ - `xpos <= pos`
3524
+ - `xpos + str.size() <= size()`
3525
+ - `traits::eq(at(xpos + I), str.at(I))` for all elements `I` of the
3526
+ string referenced by `str`.
3527
+
3528
+ *Effects:* Determines `xpos`.
3529
+
3530
+ *Returns:* `xpos` if the function can determine such a value for `xpos`.
3531
+ Otherwise, returns `npos`.
3532
+
3533
+ ``` cpp
3534
+ constexpr size_type find_first_of(basic_string_view str, size_type pos = 0) const noexcept;
3535
+ ```
3536
+
3537
+ Let `xpos` be the lowest position, if possible, such that the following
3538
+ conditions hold:
3539
+
3540
+ - `pos <= xpos`
3541
+ - `xpos < size()`
3542
+ - `traits::eq(at(xpos), str.at(I))` for some element `I` of the string
3543
+ referenced by `str`.
3544
+
3545
+ *Effects:* Determines `xpos`.
3546
+
3547
+ *Returns:* `xpos` if the function can determine such a value for `xpos`.
3548
+ Otherwise, returns `npos`.
3549
+
3550
+ ``` cpp
3551
+ constexpr size_type find_last_of(basic_string_view str, size_type pos = npos) const noexcept;
3552
+ ```
3553
+
3554
+ Let `xpos` be the highest position, if possible, such that the following
3555
+ conditions hold:
3556
+
3557
+ - `xpos <= pos`
3558
+ - `xpos < size()`
3559
+ - `traits::eq(at(xpos), str.at(I))` for some element `I` of the string
3560
+ referenced by `str`.
3561
+
3562
+ *Effects:* Determines `xpos`.
3563
+
3564
+ *Returns:* `xpos` if the function can determine such a value for `xpos`.
3565
+ Otherwise, returns `npos`.
3566
+
3567
+ ``` cpp
3568
+ constexpr size_type find_first_not_of(basic_string_view str, size_type pos = 0) const noexcept;
3569
+ ```
3570
+
3571
+ Let `xpos` be the lowest position, if possible, such that the following
3572
+ conditions hold:
3573
+
3574
+ - `pos <= xpos`
3575
+ - `xpos < size()`
3576
+ - `traits::eq(at(xpos), str.at(I))` for no element `I` of the string
3577
+ referenced by `str`.
3578
+
3579
+ *Effects:* Determines `xpos`.
3580
+
3581
+ *Returns:* `xpos` if the function can determine such a value for `xpos`.
3582
+ Otherwise, returns `npos`.
3583
+
3584
+ ``` cpp
3585
+ constexpr size_type find_last_not_of(basic_string_view str, size_type pos = npos) const noexcept;
3586
+ ```
3587
+
3588
+ Let `xpos` be the highest position, if possible, such that the following
3589
+ conditions hold:
3590
+
3591
+ - `xpos <= pos`
3592
+ - `xpos < size()`
3593
+ - `traits::eq(at(xpos), str.at(I))` for no element `I` of the string
3594
+ referenced by `str`.
3595
+
3596
+ *Effects:* Determines `xpos`.
3597
+
3598
+ *Returns:* `xpos` if the function can determine such a value for `xpos`.
3599
+ Otherwise, returns `npos`.
3600
+
3601
+ ### Non-member comparison functions <a id="string.view.comparison">[[string.view.comparison]]</a>
3602
+
3603
+ Let `S` be `basic_string_view<charT, traits>`, and `sv` be an instance
3604
+ of `S`. Implementations shall provide sufficient additional overloads
3605
+ marked `constexpr` and `noexcept` so that an object `t` with an implicit
3606
+ conversion to `S` can be compared according to Table 
3607
+ [[tab:string.view.comparison.overloads]].
3608
+
3609
+ **Table: Additional `basic_string_view` comparison overloads** <a id="tab:string.view.comparison.overloads">[tab:string.view.comparison.overloads]</a>
3610
+
3611
+ | Expression | Equivalent to |
3612
+ | ---------- | ------------- |
3613
+ | `t == sv` | `S(t) == sv` |
3614
+ | `sv == t` | `sv == S(t)` |
3615
+ | `t != sv` | `S(t) != sv` |
3616
+ | `sv != t` | `sv != S(t)` |
3617
+ | `t < sv` | `S(t) < sv` |
3618
+ | `sv < t` | `sv < S(t)` |
3619
+ | `t > sv` | `S(t) > sv` |
3620
+ | `sv > t` | `sv > S(t)` |
3621
+ | `t <= sv` | `S(t) <= sv` |
3622
+ | `sv <= t` | `sv <= S(t)` |
3623
+ | `t >= sv` | `S(t) >= sv` |
3624
+ | `sv >= t` | `sv >= S(t)` |
3625
+
3626
+
3627
+ [*Example 1*:
3628
+
3629
+ A sample conforming implementation for `operator==` would be:
3630
+
3631
+ ``` cpp
3632
+ template<class T> using __identity = decay_t<T>;
3633
+ template<class charT, class traits>
3634
+ constexpr bool operator==(basic_string_view<charT, traits> lhs,
3635
+ basic_string_view<charT, traits> rhs) noexcept {
3636
+ return lhs.compare(rhs) == 0;
3637
+ }
3638
+ template<class charT, class traits>
3639
+ constexpr bool operator==(basic_string_view<charT, traits> lhs,
3640
+ __identity<basic_string_view<charT, traits>> rhs) noexcept {
3641
+ return lhs.compare(rhs) == 0;
3642
+ }
3643
+ template<class charT, class traits>
3644
+ constexpr bool operator==(__identity<basic_string_view<charT, traits>> lhs,
3645
+ basic_string_view<charT, traits> rhs) noexcept {
3646
+ return lhs.compare(rhs) == 0;
3647
+ }
3648
+ ```
3649
+
3650
+ — *end example*]
3651
+
3652
+ ``` cpp
3653
+ template<class charT, class traits>
3654
+ constexpr bool operator==(basic_string_view<charT, traits> lhs,
3655
+ basic_string_view<charT, traits> rhs) noexcept;
3656
+ ```
3657
+
3658
+ *Returns:* `lhs.compare(rhs) == 0`.
3659
+
3660
+ ``` cpp
3661
+ template<class charT, class traits>
3662
+ constexpr bool operator!=(basic_string_view<charT, traits> lhs,
3663
+ basic_string_view<charT, traits> rhs) noexcept;
3664
+ ```
3665
+
3666
+ *Returns:* `lhs.compare(rhs) != 0`.
3667
+
3668
+ ``` cpp
3669
+ template<class charT, class traits>
3670
+ constexpr bool operator< (basic_string_view<charT, traits> lhs,
3671
+ basic_string_view<charT, traits> rhs) noexcept;
3672
+ ```
3673
+
3674
+ *Returns:* `lhs.compare(rhs) < 0`.
3675
+
3676
+ ``` cpp
3677
+ template<class charT, class traits>
3678
+ constexpr bool operator> (basic_string_view<charT, traits> lhs,
3679
+ basic_string_view<charT, traits> rhs) noexcept;
3680
+ ```
3681
+
3682
+ *Returns:* `lhs.compare(rhs) > 0`.
3683
+
3684
+ ``` cpp
3685
+ template<class charT, class traits>
3686
+ constexpr bool operator<=(basic_string_view<charT, traits> lhs,
3687
+ basic_string_view<charT, traits> rhs) noexcept;
3688
+ ```
3689
+
3690
+ *Returns:* `lhs.compare(rhs) <= 0`.
3691
+
3692
+ ``` cpp
3693
+ template<class charT, class traits>
3694
+ constexpr bool operator>=(basic_string_view<charT, traits> lhs,
3695
+ basic_string_view<charT, traits> rhs) noexcept;
3696
+ ```
3697
+
3698
+ *Returns:* `lhs.compare(rhs) >= 0`.
3699
+
3700
+ ### Inserters and extractors <a id="string.view.io">[[string.view.io]]</a>
3701
+
3702
+ ``` cpp
3703
+ template<class charT, class traits>
3704
+ basic_ostream<charT, traits>&
3705
+ operator<<(basic_ostream<charT, traits>& os,
3706
+ basic_string_view<charT, traits> str);
3707
+ ```
3708
+
3709
+ *Effects:* Behaves as a formatted output
3710
+ function ([[ostream.formatted.reqmts]]) of `os`. Forms a character
3711
+ sequence `seq`, initially consisting of the elements defined by the
3712
+ range \[`str.begin()`, `str.end()`). Determines padding for `seq` as
3713
+ described in  [[ostream.formatted.reqmts]]. Then inserts `seq` as if by
3714
+ calling `os.rdbuf()->sputn(seq, n)`, where `n` is the larger of
3715
+ `os.width()` and `str.size()`; then calls `os.width(0)`.
3716
+
3717
+ *Returns:* `os`
3718
+
3719
+ ### Hash support <a id="string.view.hash">[[string.view.hash]]</a>
3720
+
3721
+ ``` cpp
3722
+ template<> struct hash<string_view>;
3723
+ template<> struct hash<u16string_view>;
3724
+ template<> struct hash<u32string_view>;
3725
+ template<> struct hash<wstring_view>;
3726
+ ```
3727
+
3728
+ The specialization is enabled ([[unord.hash]]).
3729
+
3730
+ [*Note 1*: The hash value of a string view object is equal to the hash
3731
+ value of the corresponding string object
3732
+ ([[basic.string.hash]]). — *end note*]
3733
+
3734
+ ### Suffix for `basic_string_view` literals <a id="string.view.literals">[[string.view.literals]]</a>
3735
+
3736
+ ``` cpp
3737
+ constexpr string_view operator""sv(const char* str, size_t len) noexcept;
3738
+ ```
3739
+
3740
+ *Returns:* `string_view{str, len}`.
3741
+
3742
+ ``` cpp
3743
+ constexpr u16string_view operator""sv(const char16_t* str, size_t len) noexcept;
3744
+ ```
3745
+
3746
+ *Returns:* `u16string_view{str, len}`.
3747
+
3748
+ ``` cpp
3749
+ constexpr u32string_view operator""sv(const char32_t* str, size_t len) noexcept;
3750
+ ```
3751
+
3752
+ *Returns:* `u32string_view{str, len}`.
3753
+
3754
+ ``` cpp
3755
+ constexpr wstring_view operator""sv(const wchar_t* str, size_t len) noexcept;
3756
+ ```
3757
+
3758
+ *Returns:* `wstring_view{str, len}`.
3759
 
3760
  ## Null-terminated sequence utilities <a id="c.strings">[[c.strings]]</a>
3761
 
3762
+ ### Header `<cctype>` synopsis <a id="cctype.syn">[[cctype.syn]]</a>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3763
 
3764
  ``` cpp
3765
+ namespace std {
3766
+ int isalnum(int c);
3767
+ int isalpha(int c);
3768
+ int isblank(int c);
3769
+ int iscntrl(int c);
3770
+ int isdigit(int c);
3771
+ int isgraph(int c);
3772
+ int islower(int c);
3773
+ int isprint(int c);
3774
+ int ispunct(int c);
3775
+ int isspace(int c);
3776
+ int isupper(int c);
3777
+ int isxdigit(int c);
3778
+ int tolower(int c);
3779
+ int toupper(int c);
3780
+ }
3781
  ```
3782
 
3783
+ The contents and meaning of the header `<cctype>` are the same as the C
3784
+ standard library header `<ctype.h>`.
3785
 
3786
+ ISO C 7.4
 
3787
 
3788
+ ### Header `<cwctype>` synopsis <a id="cwctype.syn">[[cwctype.syn]]</a>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3789
 
3790
  ``` cpp
3791
+ namespace std {
3792
+ using wint_t = see below;
3793
+ using wctrans_t = see below;
3794
+ using wctype_t = see below;
3795
+
3796
+ int iswalnum(wint_t wc);
3797
+ int iswalpha(wint_t wc);
3798
+ int iswblank(wint_t wc);
3799
+ int iswcntrl(wint_t wc);
3800
+ int iswdigit(wint_t wc);
3801
+ int iswgraph(wint_t wc);
3802
+ int iswlower(wint_t wc);
3803
+ int iswprint(wint_t wc);
3804
+ int iswpunct(wint_t wc);
3805
+ int iswspace(wint_t wc);
3806
+ int iswupper(wint_t wc);
3807
+ int iswxdigit(wint_t wc);
3808
+ int iswctype(wint_t wc, wctype_t desc);
3809
+ wctype_t wctype(const char* property);
3810
+ wint_t towlower(wint_t wc);
3811
+ wint_t towupper(wint_t wc);
3812
+ wint_t towctrans(wint_t wc, wctrans_t desc);
3813
+ wctrans_t wctrans(const char* property);
3814
+ }
3815
+
3816
+ #define WEOF see below
3817
  ```
3818
 
3819
+ The contents and meaning of the header `<cwctype>` are the same as the C
3820
+ standard library header `<wctype.h>`.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3821
 
3822
+ ISO C 7.30
3823
 
3824
+ ### Header `<cstring>` synopsis <a id="cstring.syn">[[cstring.syn]]</a>
 
3825
 
3826
  ``` cpp
3827
+ namespace std {
3828
+ using size_t = see [support.types.layout];
3829
+
3830
+ void* memcpy(void* s1, const void* s2, size_t n);
3831
+ void* memmove(void* s1, const void* s2, size_t n);
3832
+ char* strcpy(char* s1, const char* s2);
3833
+ char* strncpy(char* s1, const char* s2, size_t n);
3834
+ char* strcat(char* s1, const char* s2);
3835
+ char* strncat(char* s1, const char* s2, size_t n);
3836
+ int memcmp(const void* s1, const void* s2, size_t n);
3837
+ int strcmp(const char* s1, const char* s2);
3838
+ int strcoll(const char* s1, const char* s2);
3839
+ int strncmp(const char* s1, const char* s2, size_t n);
3840
+ size_t strxfrm(char* s1, const char* s2, size_t n);
3841
+ const void* memchr(const void* s, int c, size_t n); // see [library.c]
3842
+ void* memchr(void* s, int c, size_t n) // see [library.c]
3843
+ const char* strchr(const char* s, int c) // see [library.c]
3844
+ char* strchr(char* s, int c) // see [library.c]
3845
+ size_t strcspn(const char* s1, const char* s2);
3846
+ const char* strpbrk(const char* s1, const char* s2) // see [library.c]
3847
+ char* strpbrk(char* s1, const char* s2) // see [library.c]
3848
+ const char* strrchr(const char* s, int c) // see [library.c]
3849
+ char* strrchr(char* s, int c) // see [library.c]
3850
+ size_t strspn(const char* s1, const char* s2);
3851
+ const char* strstr(const char* s1, const char* s2) // see [library.c]
3852
+ char* strstr(char* s1, const char* s2) // see [library.c]
3853
+ char* strtok(char* s1, const char* s2);
3854
+ void* memset(void* s, int c, size_t n);
3855
+ char* strerror(int errnum);
3856
+ size_t strlen(const char* s);
3857
+ }
3858
+
3859
+ #define NULL see [support.types.nullptr]
3860
  ```
3861
 
3862
+ The contents and meaning of the header `<cstring>` are the same as the C
3863
+ standard library header `<string.h>`.
3864
 
3865
  The functions `strerror` and `strtok` are not required to avoid data
3866
  races ([[res.on.data.races]]).
3867
 
3868
+ The functions `memcpy` and `memmove` are signal-safe ([[csignal.syn]]).
 
 
 
3869
 
3870
+ [*Note 1*: The functions `strchr`, `strpbrk`, `strrchr`, `strstr`, and
3871
+ `memchr`, have different signatures in this International Standard, but
3872
+ they have the same behavior as in the C standard library (
3873
+ [[library.c]]). — *end note*]
3874
 
3875
+ ISO C 7.24.
 
 
 
3876
 
3877
+ ### Header `<cwchar>` synopsis <a id="cwchar.syn">[[cwchar.syn]]</a>
3878
 
3879
+ ``` cpp
3880
+ namespace std {
3881
+ using size_t = see [support.types.layout];
3882
+ using mbstate_t = see below;
3883
+ using wint_t = see below;
3884
+
3885
+ struct tm;
3886
+
3887
+ int fwprintf(FILE* stream, const wchar_t* format, ...);
3888
+ int fwscanf(FILE* stream, const wchar_t* format, ...);
3889
+ int swprintf(wchar_t* s, size_t n, const wchar_t* format, ...);
3890
+ int swscanf(const wchar_t* s, const wchar_t* format, ...);
3891
+ int vfwprintf(FILE* stream, const wchar_t* format, va_list arg);
3892
+ int vfwscanf(FILE* stream, const wchar_t* format, va_list arg);
3893
+ int vswprintf(wchar_t* s, size_t n, const wchar_t* format, va_list arg);
3894
+ int vswscanf(const wchar_t* s, const wchar_t* format, va_list arg);
3895
+ int vwprintf(const wchar_t* format, va_list arg);
3896
+ int vwscanf(const wchar_t* format, va_list arg);
3897
+ int wprintf(const wchar_t* format, ...);
3898
+ int wscanf(const wchar_t* format, ...);
3899
+ wint_t fgetwc(FILE* stream);
3900
+ wchar_t* fgetws(wchar_t* s, int n, FILE* stream);
3901
+ wint_t fputwc(wchar_t c, FILE* stream);
3902
+ int fputws(const wchar_t* s, FILE* stream);
3903
+ int fwide(FILE* stream, int mode);
3904
+ wint_t getwc(FILE* stream);
3905
+ wint_t getwchar();
3906
+ wint_t putwc(wchar_t c, FILE* stream);
3907
+ wint_t putwchar(wchar_t c);
3908
+ wint_t ungetwc(wint_t c, FILE* stream);
3909
+ double wcstod(const wchar_t* nptr, wchar_t** endptr);
3910
+ float wcstof(const wchar_t* nptr, wchar_t** endptr);
3911
+ long double wcstold(const wchar_t* nptr, wchar_t** endptr);
3912
+ long int wcstol(const wchar_t* nptr, wchar_t** endptr, int base);
3913
+ long long int wcstoll(const wchar_t* nptr, wchar_t** endptr, int base);
3914
+ unsigned long int wcstoul(const wchar_t* nptr, wchar_t** endptr, int base);
3915
+ unsigned long long int wcstoull(const wchar_t* nptr, wchar_t** endptr, int base);
3916
+ wchar_t* wcscpy(wchar_t* s1, const wchar_t* s2);
3917
+ wchar_t* wcsncpy(wchar_t* s1, const wchar_t* s2, size_t n);
3918
+ wchar_t* wmemcpy(wchar_t* s1, const wchar_t* s2, size_t n);
3919
+ wchar_t* wmemmove(wchar_t* s1, const wchar_t* s2, size_t n);
3920
+ wchar_t* wcscat(wchar_t* s1, const wchar_t* s2);
3921
+ wchar_t* wcsncat(wchar_t* s1, const wchar_t* s2, size_t n);
3922
+ int wcscmp(const wchar_t* s1, const wchar_t* s2);
3923
+ int wcscoll(const wchar_t* s1, const wchar_t* s2);
3924
+ int wcsncmp(const wchar_t* s1, const wchar_t* s2, size_t n);
3925
+ size_t wcsxfrm(wchar_t* s1, const wchar_t* s2, size_t n);
3926
+ int wmemcmp(const wchar_t* s1, const wchar_t* s2, size_t n);
3927
+ const wchar_t* wcschr(const wchar_t* s, wchar_t c) // see [library.c]
3928
+ wchar_t* wcschr(wchar_t* s, wchar_t c) // see [library.c]
3929
+ size_t wcscspn(const wchar_t* s1, const wchar_t* s2);
3930
+ const wchar_t* wcspbrk(const wchar_t* s1, const wchar_t* s2) // see [library.c]
3931
+ wchar_t* wcspbrk(wchar_t* s1, const wchar_t* s2) // see [library.c]
3932
+ const wchar_t* wcsrchr(const wchar_t* s, wchar_t c) // see [library.c]
3933
+ wchar_t* wcsrchr(wchar_t* s, wchar_t c) // see [library.c]
3934
+ size_t wcsspn(const wchar_t* s1, const wchar_t* s2);
3935
+ const wchar_t* wcsstr(const wchar_t* s1, const wchar_t* s2) // see [library.c]
3936
+ wchar_t* wcsstr(wchar_t* s1, const wchar_t* s2) // see [library.c]
3937
+ wchar_t* wcstok(wchar_t* s1, const wchar_t* s2, wchar_t** ptr);
3938
+ const wchar_t* wmemchr(const wchar_t* s, wchar_t c, size_t n) // see [library.c]
3939
+ wchar_t* wmemchr(wchar_t* s, wchar_t c, size_t n) // see [library.c]
3940
+ size_t wcslen(const wchar_t* s);
3941
+ wchar_t* wmemset(wchar_t* s, wchar_t c, size_t n);
3942
+ size_t wcsftime(wchar_t* s, size_t maxsize, const wchar_t* format, const struct tm* timeptr);
3943
+ wint_t btowc(int c);
3944
+ int wctob(wint_t c);
3945
+
3946
+ // [c.mb.wcs], multibyte / wide string and character conversion functions
3947
+ int mbsinit(const mbstate_t* ps);
3948
+ size_t mbrlen(const char* s, size_t n, mbstate_t* ps);
3949
+ size_t mbrtowc(wchar_t* pwc, const char* s, size_t n, mbstate_t* ps);
3950
+ size_t wcrtomb(char* s, wchar_t wc, mbstate_t* ps);
3951
+ size_t mbsrtowcs(wchar_t* dst, const char** src, size_t len, mbstate_t* ps);
3952
+ size_t wcsrtombs(char* dst, const wchar_t** src, size_t len, mbstate_t* ps);
3953
+ }
3954
+
3955
+ #define NULL see [support.types.nullptr]
3956
+ #define WCHAR_MAX see below
3957
+ #define WCHAR_MIN see below
3958
+ #define WEOF see below
3959
+ ```
3960
+
3961
+ The contents and meaning of the header `<cwchar>` are the same as the C
3962
+ standard library header `<wchar.h>`, except that it does not declare a
3963
+ type `wchar_t`.
3964
+
3965
+ [*Note 1*: The functions `wcschr`, `wcspbrk`, `wcsrchr`, `wcsstr`, and
3966
+ `wmemchr` have different signatures in this International Standard, but
3967
+ they have the same behavior as in the C standard library (
3968
+ [[library.c]]). — *end note*]
3969
+
3970
+ ISO C 7.29
3971
+
3972
+ ### Header `<cuchar>` synopsis <a id="cuchar.syn">[[cuchar.syn]]</a>
3973
+
3974
+ ``` cpp
3975
+ namespace std {
3976
+ using mbstate_t = see below;
3977
+ using size_t = see [support.types.layout];
3978
+
3979
+ size_t mbrtoc16(char16_t* pc16, const char* s, size_t n, mbstate_t* ps);
3980
+ size_t c16rtomb(char* s, char16_t c16, mbstate_t* ps);
3981
+ size_t mbrtoc32(char32_t* pc32, const char* s, size_t n, mbstate_t* ps);
3982
+ size_t c32rtomb(char* s, char32_t c32, mbstate_t* ps);
3983
+ }
3984
+ ```
3985
+
3986
+ The contents and meaning of the header `<cuchar>` are the same as the C
3987
+ standard library header `<uchar.h>`, except that it does not declare
3988
+ types `char16_t` nor `char32_t`.
3989
+
3990
+ ISO C 7.28
3991
+
3992
+ ### Multibyte / wide string and character conversion functions <a id="c.mb.wcs">[[c.mb.wcs]]</a>
3993
+
3994
+ [*Note 1*: The headers `<cstdlib>` ([[cstdlib.syn]]) and `<cwchar>` (
3995
+ [[cwchar.syn]]) declare the functions described in this
3996
+ subclause. — *end note*]
3997
+
3998
+ ``` cpp
3999
+ int mbsinit(const mbstate_t* ps);
4000
+ int mblen(const char* s, size_t n);
4001
+ size_t mbstowcs(wchar_t* pwcs, const char* s, size_t n);
4002
+ size_t wcstombs(char* s, const wchar_t* pwcs, size_t n);
4003
+ ```
4004
+
4005
+ *Effects:* These functions have the semantics specified in the C
4006
+ standard library.
4007
+
4008
+ ISO C 7.22.7.1, 7.22.8, 7.29.6.2.1
4009
+
4010
+ ``` cpp
4011
+ int mbtowc(wchar_t* pwc, const char* s, size_t n);
4012
+ int wctomb(char* s, wchar_t wchar);
4013
+ ```
4014
+
4015
+ *Effects:* These functions have the semantics specified in the C
4016
+ standard library.
4017
+
4018
+ *Remarks:* Calls to these functions may introduce a data
4019
+ race ([[res.on.data.races]]) with other calls to the same function.
4020
+
4021
+ ISO C 7.22.7
4022
+
4023
+ ``` cpp
4024
+ size_t mbrlen(const char* s, size_t n, mbstate_t* ps);
4025
+ size_t mbrtowc(wchar_t* pwc, const char* s, size_t n, mbstate_t* ps);
4026
+ size_t wcrtomb(char* s, wchar_t wc, mbstate_t* ps);
4027
+ size_t mbsrtowcs(wchar_t* dst, const char** src, size_t len, mbstate_t* ps);
4028
+ size_t wcsrtombs(char* dst, const wchar_t** src, size_t len, mbstate_t* ps);
4029
+ ```
4030
+
4031
+ *Effects:* These functions have the semantics specified in the C
4032
+ standard library.
4033
+
4034
+ *Remarks:* Calling these functions with an `mbstate_t*` argument that is
4035
+ a null pointer value may introduce a data race ([[res.on.data.races]])
4036
+ with other calls to the same function with an `mbstate_t*` argument that
4037
+ is a null pointer value.
4038
+
4039
+ ISO C 7.29.6.3
4040
 
4041
  <!-- Link reference definitions -->
4042
  [basic.string]: #basic.string
4043
  [basic.string.hash]: #basic.string.hash
4044
  [basic.string.literals]: #basic.string.literals
4045
  [basic.types]: basic.md#basic.types
4046
+ [c.mb.wcs]: #c.mb.wcs
4047
  [c.strings]: #c.strings
4048
+ [cctype.syn]: #cctype.syn
4049
  [char.traits]: #char.traits
4050
  [char.traits.require]: #char.traits.require
4051
  [char.traits.specializations]: #char.traits.specializations
4052
  [char.traits.specializations.char]: #char.traits.specializations.char
4053
  [char.traits.specializations.char16_t]: #char.traits.specializations.char16_t
4054
  [char.traits.specializations.char32_t]: #char.traits.specializations.char32_t
4055
  [char.traits.specializations.wchar.t]: #char.traits.specializations.wchar.t
4056
  [char.traits.typedefs]: #char.traits.typedefs
4057
+ [container.requirements]: containers.md#container.requirements
4058
  [container.requirements.general]: containers.md#container.requirements.general
4059
+ [csignal.syn]: language.md#csignal.syn
4060
+ [cstdlib.syn]: language.md#cstdlib.syn
4061
+ [cstring.syn]: #cstring.syn
4062
+ [cuchar.syn]: #cuchar.syn
4063
+ [cwchar.syn]: #cwchar.syn
4064
+ [cwctype.syn]: #cwctype.syn
4065
  [input.output]: input.md#input.output
4066
  [iostate.flags]: input.md#iostate.flags
4067
  [iostream.forward]: input.md#iostream.forward
4068
  [iostreams.limits.pos]: input.md#iostreams.limits.pos
4069
  [istream.formatted.reqmts]: input.md#istream.formatted.reqmts
4070
  [istream.unformatted]: input.md#istream.unformatted
4071
+ [iterator.range]: iterators.md#iterator.range
4072
+ [iterator.requirements.general]: iterators.md#iterator.requirements.general
4073
  [length.error]: diagnostics.md#length.error
4074
+ [library.c]: library.md#library.c
4075
  [ostream.formatted.reqmts]: input.md#ostream.formatted.reqmts
4076
  [out.of.range]: diagnostics.md#out.of.range
4077
  [random.access.iterators]: iterators.md#random.access.iterators
4078
  [res.on.data.races]: library.md#res.on.data.races
4079
  [sequence.reqmts]: containers.md#sequence.reqmts
4080
  [string.access]: #string.access
4081
  [string.accessors]: #string.accessors
4082
+ [string.append]: #string.append
4083
+ [string.assign]: #string.assign
4084
  [string.capacity]: #string.capacity
4085
  [string.classes]: #string.classes
4086
+ [string.compare]: #string.compare
4087
  [string.cons]: #string.cons
4088
  [string.conversions]: #string.conversions
4089
+ [string.copy]: #string.copy
4090
+ [string.erase]: #string.erase
4091
+ [string.find]: #string.find
4092
+ [string.find.first.not.of]: #string.find.first.not.of
4093
+ [string.find.first.of]: #string.find.first.of
4094
+ [string.find.last.not.of]: #string.find.last.not.of
4095
+ [string.find.last.of]: #string.find.last.of
4096
+ [string.insert]: #string.insert
4097
  [string.io]: #string.io
4098
  [string.iterators]: #string.iterators
4099
  [string.modifiers]: #string.modifiers
4100
  [string.nonmembers]: #string.nonmembers
4101
+ [string.op!=]: #string.op!=
4102
+ [string.op+]: #string.op+
4103
+ [string.op+=]: #string.op+=
4104
+ [string.op<]: #string.op<
4105
+ [string.op<=]: #string.op<=
4106
+ [string.op>]: #string.op>
4107
+ [string.op>=]: #string.op>=
4108
+ [string.operator==]: #string.operator==
4109
  [string.ops]: #string.ops
4110
+ [string.replace]: #string.replace
4111
  [string.require]: #string.require
4112
+ [string.rfind]: #string.rfind
4113
  [string.special]: #string.special
4114
+ [string.substr]: #string.substr
4115
+ [string.swap]: #string.swap
4116
+ [string.syn]: #string.syn
4117
+ [string.view]: #string.view
4118
+ [string.view.access]: #string.view.access
4119
+ [string.view.capacity]: #string.view.capacity
4120
+ [string.view.comparison]: #string.view.comparison
4121
+ [string.view.cons]: #string.view.cons
4122
+ [string.view.find]: #string.view.find
4123
+ [string.view.hash]: #string.view.hash
4124
+ [string.view.io]: #string.view.io
4125
+ [string.view.iterators]: #string.view.iterators
4126
+ [string.view.literals]: #string.view.literals
4127
+ [string.view.modifiers]: #string.view.modifiers
4128
+ [string.view.ops]: #string.view.ops
4129
+ [string.view.synop]: #string.view.synop
4130
+ [string.view.template]: #string.view.template
 
 
 
 
 
 
4131
  [strings]: #strings
4132
  [strings.general]: #strings.general
4133
  [tab:char.traits.require]: #tab:char.traits.require
4134
+ [tab:copyassignable]: #tab:copyassignable
4135
+ [tab:copyconstructible]: #tab:copyconstructible
4136
+ [tab:defaultconstructible]: #tab:defaultconstructible
4137
+ [tab:string.view.compare]: #tab:string.view.compare
4138
+ [tab:string.view.comparison.overloads]: #tab:string.view.comparison.overloads
4139
+ [tab:string.view.ctr.2]: #tab:string.view.ctr.2
4140
+ [tab:string.view.ctr.3]: #tab:string.view.ctr.3
4141
  [tab:strings.compare]: #tab:strings.compare
4142
  [tab:strings.ctr.1]: #tab:strings.ctr.1
4143
  [tab:strings.ctr.2]: #tab:strings.ctr.2
4144
  [tab:strings.ctr.3]: #tab:strings.ctr.3
4145
  [tab:strings.ctr.4]: #tab:strings.ctr.4
4146
  [tab:strings.ctr.5]: #tab:strings.ctr.5
4147
  [tab:strings.ctr.6]: #tab:strings.ctr.6
4148
  [tab:strings.ctr.cpy]: #tab:strings.ctr.cpy
 
 
 
 
 
 
4149
  [tab:strings.lib.summary]: #tab:strings.lib.summary
4150
  [tab:strings.op=]: #tab:strings.op=
 
4151
  [unord.hash]: utilities.md#unord.hash
4152
+ [utility.swap]: utilities.md#utility.swap
4153
 
4154
  [^1]: If `eof()` can be held in `char_type` then some iostreams
4155
  operations may give surprising results.
4156
 
4157
  [^2]: `Allocator::value_type` must name the same type as `charT` (
4158
  [[string.require]]).
4159
 
4160
  [^3]: For example, as an argument to non-member functions `swap()` (
4161
  [[string.special]]), `operator>{}>()` ([[string.io]]), and
4162
  `getline()` ([[string.io]]), or as an argument to
4163
+ `basic_string::swap()`.
4164
 
4165
  [^4]: `reserve()` uses `allocator_traits<Allocator>::allocate()` which
4166
  may throw an appropriate exception.