From Jason Turner

[string.view]

C++17 → C++20 25.7 KB 348 lines
Current Draft | LaTeX Source
Archived: C++17 | C++20
Markdown: C++17 | C++20
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpa9707rmo/{from.md → to.md} +191 -139
tmp/tmpa9707rmo/{from.md → to.md} RENAMED
@@ -1,76 +1,72 @@
1
  ## String view classes <a id="string.view">[[string.view]]</a>
2
 
3
  The class template `basic_string_view` describes an object that can
4
- refer to a constant contiguous sequence of char-like (
5
- [[strings.general]]) objects with the first element of the sequence at
6
- position zero. In the rest of this section, the type of the char-like
7
- objects held in a `basic_string_view` object is designated by `charT`.
8
 
9
  [*Note 1*: The library provides implicit conversions from
10
  `const charT*` and `std::basic_string<charT, ...>` to
11
  `std::basic_string_view<charT, ...>` so that user code can accept just
12
  `std::basic_string_view<charT>` as a non-templated parameter wherever a
13
  sequence of characters is expected. User-defined types should define
14
  their own implicit conversions to `std::basic_string_view` in order to
15
  interoperate with these functions. — *end note*]
16
 
17
- The complexity of `basic_string_view` member functions is 𝑂(1) unless
18
- otherwise specified.
19
-
20
  ### Header `<string_view>` synopsis <a id="string.view.synop">[[string.view.synop]]</a>
21
 
22
  ``` cpp
 
 
23
  namespace std {
24
  // [string.view.template], class template basic_string_view
25
  template<class charT, class traits = char_traits<charT>>
26
  class basic_string_view;
27
 
 
 
 
 
 
28
  // [string.view.comparison], non-member comparison functions
29
  template<class charT, class traits>
30
  constexpr bool operator==(basic_string_view<charT, traits> x,
31
  basic_string_view<charT, traits> y) noexcept;
32
  template<class charT, class traits>
33
- constexpr bool operator!=(basic_string_view<charT, traits> x,
34
- basic_string_view<charT, traits> y) noexcept;
35
- template<class charT, class traits>
36
- constexpr bool operator< (basic_string_view<charT, traits> x,
37
- basic_string_view<charT, traits> y) noexcept;
38
- template<class charT, class traits>
39
- constexpr bool operator> (basic_string_view<charT, traits> x,
40
- basic_string_view<charT, traits> y) noexcept;
41
- template<class charT, class traits>
42
- constexpr bool operator<=(basic_string_view<charT, traits> x,
43
- basic_string_view<charT, traits> y) noexcept;
44
- template<class charT, class traits>
45
- constexpr bool operator>=(basic_string_view<charT, traits> x,
46
- basic_string_view<charT, traits> y) noexcept;
47
  // see [string.view.comparison], sufficient additional overloads of comparison functions
48
 
49
  // [string.view.io], inserters and extractors
50
  template<class charT, class traits>
51
  basic_ostream<charT, traits>&
52
  operator<<(basic_ostream<charT, traits>& os,
53
  basic_string_view<charT, traits> str);
54
 
55
  // basic_string_view typedef names
56
  using string_view = basic_string_view<char>;
 
57
  using u16string_view = basic_string_view<char16_t>;
58
  using u32string_view = basic_string_view<char32_t>;
59
  using wstring_view = basic_string_view<wchar_t>;
60
 
61
  // [string.view.hash], hash support
62
  template<class T> struct hash;
63
  template<> struct hash<string_view>;
 
64
  template<> struct hash<u16string_view>;
65
  template<> struct hash<u32string_view>;
66
  template<> struct hash<wstring_view>;
67
 
68
  inline namespace literals {
69
  inline namespace string_view_literals {
70
  // [string.view.literals], suffix for basic_string_view literals
71
  constexpr string_view operator""sv(const char* str, size_t len) noexcept;
 
72
  constexpr u16string_view operator""sv(const char16_t* str, size_t len) noexcept;
73
  constexpr u32string_view operator""sv(const char32_t* str, size_t len) noexcept;
74
  constexpr wstring_view operator""sv(const wchar_t* str, size_t len) noexcept;
75
  }
76
  }
@@ -105,10 +101,12 @@ public:
105
  constexpr basic_string_view() noexcept;
106
  constexpr basic_string_view(const basic_string_view&) noexcept = default;
107
  constexpr basic_string_view& operator=(const basic_string_view&) noexcept = default;
108
  constexpr basic_string_view(const charT* str);
109
  constexpr basic_string_view(const charT* str, size_type len);
 
 
110
 
111
  // [string.view.iterators], iterator support
112
  constexpr const_iterator begin() const noexcept;
113
  constexpr const_iterator end() const noexcept;
114
  constexpr const_iterator cbegin() const noexcept;
@@ -120,11 +118,11 @@ public:
120
 
121
  // [string.view.capacity], capacity
122
  constexpr size_type size() const noexcept;
123
  constexpr size_type length() const noexcept;
124
  constexpr size_type max_size() const noexcept;
125
- constexpr bool empty() const noexcept;
126
 
127
  // [string.view.access], element access
128
  constexpr const_reference operator[](size_type pos) const;
129
  constexpr const_reference at(size_type pos) const;
130
  constexpr const_reference front() const;
@@ -135,29 +133,39 @@ public:
135
  constexpr void remove_prefix(size_type n);
136
  constexpr void remove_suffix(size_type n);
137
  constexpr void swap(basic_string_view& s) noexcept;
138
 
139
  // [string.view.ops], string operations
140
- size_type copy(charT* s, size_type n, size_type pos = 0) const;
141
 
142
  constexpr basic_string_view substr(size_type pos = 0, size_type n = npos) const;
 
143
  constexpr int compare(basic_string_view s) const noexcept;
144
  constexpr int compare(size_type pos1, size_type n1, basic_string_view s) const;
145
  constexpr int compare(size_type pos1, size_type n1, basic_string_view s,
146
  size_type pos2, size_type n2) const;
147
  constexpr int compare(const charT* s) const;
148
  constexpr int compare(size_type pos1, size_type n1, const charT* s) const;
149
- constexpr int compare(size_type pos1, size_type n1, const charT* s,
150
- size_type n2) const;
 
 
 
 
 
 
 
 
151
  constexpr size_type find(basic_string_view s, size_type pos = 0) const noexcept;
152
  constexpr size_type find(charT c, size_type pos = 0) const noexcept;
153
  constexpr size_type find(const charT* s, size_type pos, size_type n) const;
154
  constexpr size_type find(const charT* s, size_type pos = 0) const;
155
  constexpr size_type rfind(basic_string_view s, size_type pos = npos) const noexcept;
156
  constexpr size_type rfind(charT c, size_type pos = npos) const noexcept;
157
  constexpr size_type rfind(const charT* s, size_type pos, size_type n) const;
158
  constexpr size_type rfind(const charT* s, size_type pos = npos) const;
 
159
  constexpr size_type find_first_of(basic_string_view s, size_type pos = 0) const noexcept;
160
  constexpr size_type find_first_of(charT c, size_type pos = 0) const noexcept;
161
  constexpr size_type find_first_of(const charT* s, size_type pos, size_type n) const;
162
  constexpr size_type find_first_of(const charT* s, size_type pos = 0) const;
163
  constexpr size_type find_last_of(basic_string_view s, size_type pos = npos) const noexcept;
@@ -178,73 +186,102 @@ public:
178
 
179
  private:
180
  const_pointer data_; // exposition only
181
  size_type size_; // exposition only
182
  };
 
 
 
 
183
  ```
184
 
185
  In every specialization `basic_string_view<charT, traits>`, the type
186
- `traits` shall satisfy the character traits requirements (
187
- [[char.traits]]), and the type `traits::char_type` shall name the same
188
- type as `charT`.
 
 
 
 
 
 
 
 
 
189
 
190
  #### Construction and assignment <a id="string.view.cons">[[string.view.cons]]</a>
191
 
192
  ``` cpp
193
  constexpr basic_string_view() noexcept;
194
  ```
195
 
196
- *Effects:* Constructs an empty `basic_string_view`.
197
-
198
- *Postconditions:* `size_ == 0` and `data_ == nullptr`.
199
 
200
  ``` cpp
201
  constexpr basic_string_view(const charT* str);
202
  ```
203
 
204
- *Requires:* \[`str`, `str + traits::length(str)`) is a valid range.
205
 
206
- *Effects:* Constructs a `basic_string_view`, with the postconditions in
207
- Table  [[tab:string.view.ctr.2]].
208
 
209
  *Complexity:* 𝑂(`traits::length(str)`).
210
 
211
  ``` cpp
212
  constexpr basic_string_view(const charT* str, size_type len);
213
  ```
214
 
215
- *Requires:* \[`str`, `str + len`) is a valid range.
216
 
217
- *Effects:* Constructs a `basic_string_view`, with the postconditions in
218
- Table  [[tab:string.view.ctr.3]].
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
219
 
220
  #### Iterator support <a id="string.view.iterators">[[string.view.iterators]]</a>
221
 
222
  ``` cpp
223
  using const_iterator = implementation-defined // type of basic_string_view::const_iterator;
224
  ```
225
 
226
- A type that meets the requirements of a constant random access
227
- iterator ([[random.access.iterators]]) and of a contiguous
228
- iterator ([[iterator.requirements.general]]) whose `value_type` is the
229
- template parameter `charT`.
 
230
 
231
- For a `basic_string_view str`, any operation that invalidates a pointer
232
- in the range \[`str.data()`, `str.data() + str.size()`) invalidates
233
- pointers, iterators, and references returned from `str`’s methods.
234
-
235
- All requirements on container iterators ([[container.requirements]])
236
- apply to `basic_string_view::const_iterator` as well.
237
 
238
  ``` cpp
239
  constexpr const_iterator begin() const noexcept;
240
  constexpr const_iterator cbegin() const noexcept;
241
  ```
242
 
243
  *Returns:* An iterator such that
244
 
245
- - if `!empty()`, `&*begin() == data_`,
246
  - otherwise, an unspecified value such that \[`begin()`, `end()`) is a
247
  valid range.
248
 
249
  ``` cpp
250
  constexpr const_iterator end() const noexcept;
@@ -269,15 +306,10 @@ constexpr const_reverse_iterator crend() const noexcept;
269
 
270
  #### Capacity <a id="string.view.capacity">[[string.view.capacity]]</a>
271
 
272
  ``` cpp
273
  constexpr size_type size() const noexcept;
274
- ```
275
-
276
- *Returns:* `size_`.
277
-
278
- ``` cpp
279
  constexpr size_type length() const noexcept;
280
  ```
281
 
282
  *Returns:* `size_`.
283
 
@@ -287,22 +319,22 @@ constexpr size_type max_size() const noexcept;
287
 
288
  *Returns:* The largest possible number of char-like objects that can be
289
  referred to by a `basic_string_view`.
290
 
291
  ``` cpp
292
- constexpr bool empty() const noexcept;
293
  ```
294
 
295
  *Returns:* `size_ == 0`.
296
 
297
  #### Element access <a id="string.view.access">[[string.view.access]]</a>
298
 
299
  ``` cpp
300
  constexpr const_reference operator[](size_type pos) const;
301
  ```
302
 
303
- *Requires:* `pos < size()`.
304
 
305
  *Returns:* `data_[pos]`.
306
 
307
  *Throws:* Nothing.
308
 
@@ -320,21 +352,21 @@ constexpr const_reference at(size_type pos) const;
320
 
321
  ``` cpp
322
  constexpr const_reference front() const;
323
  ```
324
 
325
- *Requires:* `!empty()`.
326
 
327
  *Returns:* `data_[0]`.
328
 
329
  *Throws:* Nothing.
330
 
331
  ``` cpp
332
  constexpr const_reference back() const;
333
  ```
334
 
335
- *Requires:* `!empty()`.
336
 
337
  *Returns:* `data_[size() - 1]`.
338
 
339
  *Throws:* Nothing.
340
 
@@ -342,30 +374,31 @@ constexpr const_reference back() const;
342
  constexpr const_pointer data() const noexcept;
343
  ```
344
 
345
  *Returns:* `data_`.
346
 
347
- [*Note 2*: Unlike `basic_string::data()` and string literals, `data()`
348
- may return a pointer to a buffer that is not null-terminated. Therefore
349
- it is typically a mistake to pass `data()` to a function that takes just
350
- a `const charT*` and expects a null-terminated string. — *end note*]
 
351
 
352
  #### Modifiers <a id="string.view.modifiers">[[string.view.modifiers]]</a>
353
 
354
  ``` cpp
355
  constexpr void remove_prefix(size_type n);
356
  ```
357
 
358
- *Requires:* `n <= size()`.
359
 
360
  *Effects:* Equivalent to: `data_ += n; size_ -= n;`
361
 
362
  ``` cpp
363
  constexpr void remove_suffix(size_type n);
364
  ```
365
 
366
- *Requires:* `n <= size()`.
367
 
368
  *Effects:* Equivalent to: `size_ -= n;`
369
 
370
  ``` cpp
371
  constexpr void swap(basic_string_view& s) noexcept;
@@ -374,18 +407,18 @@ constexpr void swap(basic_string_view& s) noexcept;
374
  *Effects:* Exchanges the values of `*this` and `s`.
375
 
376
  #### String operations <a id="string.view.ops">[[string.view.ops]]</a>
377
 
378
  ``` cpp
379
- size_type copy(charT* s, size_type n, size_type pos = 0) const;
380
  ```
381
 
382
  Let `rlen` be the smaller of `n` and `size() - pos`.
383
 
384
  *Throws:* `out_of_range` if `pos > size()`.
385
 
386
- *Requires:* \[`s`, `s + rlen`) is a valid range.
387
 
388
  *Effects:* Equivalent to `traits::copy(s, data() + pos, rlen)`.
389
 
390
  *Returns:* `rlen`.
391
 
@@ -416,13 +449,13 @@ compare. The function then compares the two strings by calling
416
 
417
  *Complexity:* 𝑂(`rlen`).
418
 
419
  *Returns:* The nonzero result if the result of the comparison is
420
  nonzero. Otherwise, returns a value as indicated in
421
- Table  [[tab:string.view.compare]].
422
 
423
- **Table: `compare()` results** <a id="tab:string.view.compare">[tab:string.view.compare]</a>
424
 
425
  | Condition | Return Value |
426
  | ---------------------- | ------------ |
427
  | `size() < str.size()` | `< 0` |
428
  | `size() == str.size()` | ` 0` |
@@ -454,50 +487,84 @@ constexpr int compare(size_type pos1, size_type n1, const charT* s) const;
454
 
455
  *Effects:* Equivalent to:
456
  `return substr(pos1, n1).compare(basic_string_view(s));`
457
 
458
  ``` cpp
459
- constexpr int compare(size_type pos1, size_type n1,
460
- const charT* s, size_type n2) const;
461
  ```
462
 
463
  *Effects:* Equivalent to:
464
  `return substr(pos1, n1).compare(basic_string_view(s, n2));`
465
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
466
  #### Searching <a id="string.view.find">[[string.view.find]]</a>
467
 
468
- This section specifies the `basic_string_view` member functions named
469
- `find`, `rfind`, `find_first_of`, `find_last_of`, `find_first_not_of`,
470
- and `find_last_not_of`.
471
 
472
- Member functions in this section have complexity
473
- 𝑂(`size() * str.size()`) at worst, although implementations are
474
- encouraged to do better.
475
-
476
- Each member function of the form
477
 
 
478
  ``` cpp
479
- constexpr return-type F(const charT* s, size_type pos);
480
  ```
481
 
482
- is equivalent to `return F(basic_string_view(s), pos);`
483
-
484
- Each member function of the form
485
-
486
  ``` cpp
487
- constexpr return-type F(const charT* s, size_type pos, size_type n);
488
  ```
489
 
490
- is equivalent to `return F(basic_string_view(s, n), pos);`
491
-
492
- Each member function of the form
493
-
494
  ``` cpp
495
- constexpr return-type F(charT c, size_type pos);
496
  ```
497
 
498
- is equivalent to `return F(basic_string_view(&c, 1), pos);`
 
499
 
500
  ``` cpp
501
  constexpr size_type find(basic_string_view str, size_type pos = 0) const noexcept;
502
  ```
503
 
@@ -597,19 +664,31 @@ conditions hold:
597
  *Effects:* Determines `xpos`.
598
 
599
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
600
  Otherwise, returns `npos`.
601
 
 
 
 
 
 
 
 
 
 
 
 
 
602
  ### Non-member comparison functions <a id="string.view.comparison">[[string.view.comparison]]</a>
603
 
604
  Let `S` be `basic_string_view<charT, traits>`, and `sv` be an instance
605
  of `S`. Implementations shall provide sufficient additional overloads
606
  marked `constexpr` and `noexcept` so that an object `t` with an implicit
607
- conversion to `S` can be compared according to Table 
608
- [[tab:string.view.comparison.overloads]].
609
 
610
- **Table: Additional `basic_string_view` comparison overloads** <a id="tab:string.view.comparison.overloads">[tab:string.view.comparison.overloads]</a>
611
 
612
  | Expression | Equivalent to |
613
  | ---------- | ------------- |
614
  | `t == sv` | `S(t) == sv` |
615
  | `sv == t` | `sv == S(t)` |
@@ -621,31 +700,27 @@ conversion to `S` can be compared according to Table 
621
  | `sv > t` | `sv > S(t)` |
622
  | `t <= sv` | `S(t) <= sv` |
623
  | `sv <= t` | `sv <= S(t)` |
624
  | `t >= sv` | `S(t) >= sv` |
625
  | `sv >= t` | `sv >= S(t)` |
 
 
626
 
627
 
628
  [*Example 1*:
629
 
630
  A sample conforming implementation for `operator==` would be:
631
 
632
  ``` cpp
633
- template<class T> using __identity = decay_t<T>;
634
  template<class charT, class traits>
635
  constexpr bool operator==(basic_string_view<charT, traits> lhs,
636
  basic_string_view<charT, traits> rhs) noexcept {
637
  return lhs.compare(rhs) == 0;
638
  }
639
  template<class charT, class traits>
640
  constexpr bool operator==(basic_string_view<charT, traits> lhs,
641
- __identity<basic_string_view<charT, traits>> rhs) noexcept {
642
- return lhs.compare(rhs) == 0;
643
- }
644
- template<class charT, class traits>
645
- constexpr bool operator==(__identity<basic_string_view<charT, traits>> lhs,
646
- basic_string_view<charT, traits> rhs) noexcept {
647
  return lhs.compare(rhs) == 0;
648
  }
649
  ```
650
 
651
  — *end example*]
@@ -658,59 +733,29 @@ template<class charT, class traits>
658
 
659
  *Returns:* `lhs.compare(rhs) == 0`.
660
 
661
  ``` cpp
662
  template<class charT, class traits>
663
- constexpr bool operator!=(basic_string_view<charT, traits> lhs,
664
- basic_string_view<charT, traits> rhs) noexcept;
665
  ```
666
 
667
- *Returns:* `lhs.compare(rhs) != 0`.
 
668
 
669
- ``` cpp
670
- template<class charT, class traits>
671
- constexpr bool operator< (basic_string_view<charT, traits> lhs,
672
- basic_string_view<charT, traits> rhs) noexcept;
673
- ```
674
-
675
- *Returns:* `lhs.compare(rhs) < 0`.
676
-
677
- ``` cpp
678
- template<class charT, class traits>
679
- constexpr bool operator> (basic_string_view<charT, traits> lhs,
680
- basic_string_view<charT, traits> rhs) noexcept;
681
- ```
682
-
683
- *Returns:* `lhs.compare(rhs) > 0`.
684
-
685
- ``` cpp
686
- template<class charT, class traits>
687
- constexpr bool operator<=(basic_string_view<charT, traits> lhs,
688
- basic_string_view<charT, traits> rhs) noexcept;
689
- ```
690
-
691
- *Returns:* `lhs.compare(rhs) <= 0`.
692
-
693
- ``` cpp
694
- template<class charT, class traits>
695
- constexpr bool operator>=(basic_string_view<charT, traits> lhs,
696
- basic_string_view<charT, traits> rhs) noexcept;
697
- ```
698
-
699
- *Returns:* `lhs.compare(rhs) >= 0`.
700
 
701
  ### Inserters and extractors <a id="string.view.io">[[string.view.io]]</a>
702
 
703
  ``` cpp
704
  template<class charT, class traits>
705
  basic_ostream<charT, traits>&
706
- operator<<(basic_ostream<charT, traits>& os,
707
- basic_string_view<charT, traits> str);
708
  ```
709
 
710
  *Effects:* Behaves as a formatted output
711
- function ([[ostream.formatted.reqmts]]) of `os`. Forms a character
712
  sequence `seq`, initially consisting of the elements defined by the
713
  range \[`str.begin()`, `str.end()`). Determines padding for `seq` as
714
  described in  [[ostream.formatted.reqmts]]. Then inserts `seq` as if by
715
  calling `os.rdbuf()->sputn(seq, n)`, where `n` is the larger of
716
  `os.width()` and `str.size()`; then calls `os.width(0)`.
@@ -719,29 +764,36 @@ calling `os.rdbuf()->sputn(seq, n)`, where `n` is the larger of
719
 
720
  ### Hash support <a id="string.view.hash">[[string.view.hash]]</a>
721
 
722
  ``` cpp
723
  template<> struct hash<string_view>;
 
724
  template<> struct hash<u16string_view>;
725
  template<> struct hash<u32string_view>;
726
  template<> struct hash<wstring_view>;
727
  ```
728
 
729
- The specialization is enabled ([[unord.hash]]).
730
 
731
  [*Note 1*: The hash value of a string view object is equal to the hash
732
- value of the corresponding string object
733
- ([[basic.string.hash]]). — *end note*]
734
 
735
  ### Suffix for `basic_string_view` literals <a id="string.view.literals">[[string.view.literals]]</a>
736
 
737
  ``` cpp
738
  constexpr string_view operator""sv(const char* str, size_t len) noexcept;
739
  ```
740
 
741
  *Returns:* `string_view{str, len}`.
742
 
 
 
 
 
 
 
743
  ``` cpp
744
  constexpr u16string_view operator""sv(const char16_t* str, size_t len) noexcept;
745
  ```
746
 
747
  *Returns:* `u16string_view{str, len}`.
 
1
  ## String view classes <a id="string.view">[[string.view]]</a>
2
 
3
  The class template `basic_string_view` describes an object that can
4
+ refer to a constant contiguous sequence of char-like [[strings.general]]
5
+ objects with the first element of the sequence at position zero. In the
6
+ rest of this subclause, the type of the char-like objects held in a
7
+ `basic_string_view` object is designated by `charT`.
8
 
9
  [*Note 1*: The library provides implicit conversions from
10
  `const charT*` and `std::basic_string<charT, ...>` to
11
  `std::basic_string_view<charT, ...>` so that user code can accept just
12
  `std::basic_string_view<charT>` as a non-templated parameter wherever a
13
  sequence of characters is expected. User-defined types should define
14
  their own implicit conversions to `std::basic_string_view` in order to
15
  interoperate with these functions. — *end note*]
16
 
 
 
 
17
  ### Header `<string_view>` synopsis <a id="string.view.synop">[[string.view.synop]]</a>
18
 
19
  ``` cpp
20
+ #include <compare> // see [compare.syn]
21
+
22
  namespace std {
23
  // [string.view.template], class template basic_string_view
24
  template<class charT, class traits = char_traits<charT>>
25
  class basic_string_view;
26
 
27
+ template<class charT, class traits>
28
+ inline constexpr bool ranges::enable_view<basic_string_view<charT, traits>> = true;
29
+ template<class charT, class traits>
30
+ inline constexpr bool ranges::enable_borrowed_range<basic_string_view<charT, traits>> = true;
31
+
32
  // [string.view.comparison], non-member comparison functions
33
  template<class charT, class traits>
34
  constexpr bool operator==(basic_string_view<charT, traits> x,
35
  basic_string_view<charT, traits> y) noexcept;
36
  template<class charT, class traits>
37
+ constexpr see below operator<=>(basic_string_view<charT, traits> x,
38
+ \itcorr basic_string_view<charT, traits> y) noexcept;
39
+
 
 
 
 
 
 
 
 
 
 
 
40
  // see [string.view.comparison], sufficient additional overloads of comparison functions
41
 
42
  // [string.view.io], inserters and extractors
43
  template<class charT, class traits>
44
  basic_ostream<charT, traits>&
45
  operator<<(basic_ostream<charT, traits>& os,
46
  basic_string_view<charT, traits> str);
47
 
48
  // basic_string_view typedef names
49
  using string_view = basic_string_view<char>;
50
+ using u8string_view = basic_string_view<char8_t>;
51
  using u16string_view = basic_string_view<char16_t>;
52
  using u32string_view = basic_string_view<char32_t>;
53
  using wstring_view = basic_string_view<wchar_t>;
54
 
55
  // [string.view.hash], hash support
56
  template<class T> struct hash;
57
  template<> struct hash<string_view>;
58
+ template<> struct hash<u8string_view>;
59
  template<> struct hash<u16string_view>;
60
  template<> struct hash<u32string_view>;
61
  template<> struct hash<wstring_view>;
62
 
63
  inline namespace literals {
64
  inline namespace string_view_literals {
65
  // [string.view.literals], suffix for basic_string_view literals
66
  constexpr string_view operator""sv(const char* str, size_t len) noexcept;
67
+ constexpr u8string_view operator""sv(const char8_t* str, size_t len) noexcept;
68
  constexpr u16string_view operator""sv(const char16_t* str, size_t len) noexcept;
69
  constexpr u32string_view operator""sv(const char32_t* str, size_t len) noexcept;
70
  constexpr wstring_view operator""sv(const wchar_t* str, size_t len) noexcept;
71
  }
72
  }
 
101
  constexpr basic_string_view() noexcept;
102
  constexpr basic_string_view(const basic_string_view&) noexcept = default;
103
  constexpr basic_string_view& operator=(const basic_string_view&) noexcept = default;
104
  constexpr basic_string_view(const charT* str);
105
  constexpr basic_string_view(const charT* str, size_type len);
106
+ template<class It, class End>
107
+ constexpr basic_string_view(It begin, End end);
108
 
109
  // [string.view.iterators], iterator support
110
  constexpr const_iterator begin() const noexcept;
111
  constexpr const_iterator end() const noexcept;
112
  constexpr const_iterator cbegin() const noexcept;
 
118
 
119
  // [string.view.capacity], capacity
120
  constexpr size_type size() const noexcept;
121
  constexpr size_type length() const noexcept;
122
  constexpr size_type max_size() const noexcept;
123
+ [[nodiscard]] constexpr bool empty() const noexcept;
124
 
125
  // [string.view.access], element access
126
  constexpr const_reference operator[](size_type pos) const;
127
  constexpr const_reference at(size_type pos) const;
128
  constexpr const_reference front() const;
 
133
  constexpr void remove_prefix(size_type n);
134
  constexpr void remove_suffix(size_type n);
135
  constexpr void swap(basic_string_view& s) noexcept;
136
 
137
  // [string.view.ops], string operations
138
+ constexpr size_type copy(charT* s, size_type n, size_type pos = 0) const;
139
 
140
  constexpr basic_string_view substr(size_type pos = 0, size_type n = npos) const;
141
+
142
  constexpr int compare(basic_string_view s) const noexcept;
143
  constexpr int compare(size_type pos1, size_type n1, basic_string_view s) const;
144
  constexpr int compare(size_type pos1, size_type n1, basic_string_view s,
145
  size_type pos2, size_type n2) const;
146
  constexpr int compare(const charT* s) const;
147
  constexpr int compare(size_type pos1, size_type n1, const charT* s) const;
148
+ constexpr int compare(size_type pos1, size_type n1, const charT* s, size_type n2) const;
149
+
150
+ constexpr bool starts_with(basic_string_view x) const noexcept;
151
+ constexpr bool starts_with(charT x) const noexcept;
152
+ constexpr bool starts_with(const charT* x) const;
153
+ constexpr bool ends_with(basic_string_view x) const noexcept;
154
+ constexpr bool ends_with(charT x) const noexcept;
155
+ constexpr bool ends_with(const charT* x) const;
156
+
157
+ // [string.view.find], searching
158
  constexpr size_type find(basic_string_view s, size_type pos = 0) const noexcept;
159
  constexpr size_type find(charT c, size_type pos = 0) const noexcept;
160
  constexpr size_type find(const charT* s, size_type pos, size_type n) const;
161
  constexpr size_type find(const charT* s, size_type pos = 0) const;
162
  constexpr size_type rfind(basic_string_view s, size_type pos = npos) const noexcept;
163
  constexpr size_type rfind(charT c, size_type pos = npos) const noexcept;
164
  constexpr size_type rfind(const charT* s, size_type pos, size_type n) const;
165
  constexpr size_type rfind(const charT* s, size_type pos = npos) const;
166
+
167
  constexpr size_type find_first_of(basic_string_view s, size_type pos = 0) const noexcept;
168
  constexpr size_type find_first_of(charT c, size_type pos = 0) const noexcept;
169
  constexpr size_type find_first_of(const charT* s, size_type pos, size_type n) const;
170
  constexpr size_type find_first_of(const charT* s, size_type pos = 0) const;
171
  constexpr size_type find_last_of(basic_string_view s, size_type pos = npos) const noexcept;
 
186
 
187
  private:
188
  const_pointer data_; // exposition only
189
  size_type size_; // exposition only
190
  };
191
+
192
+ // [string.view.deduct], deduction guide
193
+ template<class It, class End>
194
+ basic_string_view(It, End) -> basic_string_view<iter_value_t<It>>;
195
  ```
196
 
197
  In every specialization `basic_string_view<charT, traits>`, the type
198
+ `traits` shall meet the character traits requirements [[char.traits]].
199
+
200
+ [*Note 1*: The program is ill-formed if `traits::char_type` is not the
201
+ same type as `charT`. — *end note*]
202
+
203
+ For a `basic_string_view str`, any operation that invalidates a pointer
204
+ in the range \[`str.data()`, `str.data() + str.size()`) invalidates
205
+ pointers, iterators, and references returned from `str`’s member
206
+ functions.
207
+
208
+ The complexity of `basic_string_view` member functions is 𝑂(1) unless
209
+ otherwise specified.
210
 
211
  #### Construction and assignment <a id="string.view.cons">[[string.view.cons]]</a>
212
 
213
  ``` cpp
214
  constexpr basic_string_view() noexcept;
215
  ```
216
 
217
+ *Ensures:* `size_ == 0` and `data_ == nullptr`.
 
 
218
 
219
  ``` cpp
220
  constexpr basic_string_view(const charT* str);
221
  ```
222
 
223
+ *Preconditions:* \[`str`, `str + traits::length(str)`) is a valid range.
224
 
225
+ *Effects:* Constructs a `basic_string_view`, initializing `data_` with
226
+ `str` and initializing `size_` with `traits::length(str)`.
227
 
228
  *Complexity:* 𝑂(`traits::length(str)`).
229
 
230
  ``` cpp
231
  constexpr basic_string_view(const charT* str, size_type len);
232
  ```
233
 
234
+ *Preconditions:* \[`str`, `str + len`) is a valid range.
235
 
236
+ *Effects:* Constructs a `basic_string_view`, initializing `data_` with
237
+ `str` and initializing `size_` with `len`.
238
+
239
+ ``` cpp
240
+ template<class It, class End>
241
+ constexpr basic_string_view(It begin, End end);
242
+ ```
243
+
244
+ *Constraints:*
245
+
246
+ - `It` satisfies `contiguous_iterator`.
247
+ - `End` satisfies `sized_sentinel_for<It>`.
248
+ - `is_same_v<iter_value_t<It>, charT>` is `true`.
249
+ - `is_convertible_v<End, size_type>` is `false`.
250
+
251
+ *Preconditions:*
252
+
253
+ - \[`begin`, `end`) is a valid range.
254
+ - `It` models `contiguous_iterator`.
255
+ - `End` models `sized_sentinel_for<It>`.
256
+
257
+ *Effects:* Initializes `data_` with `to_address(begin)` and initializes
258
+ `size_` with `end - begin`.
259
 
260
  #### Iterator support <a id="string.view.iterators">[[string.view.iterators]]</a>
261
 
262
  ``` cpp
263
  using const_iterator = implementation-defined // type of basic_string_view::const_iterator;
264
  ```
265
 
266
+ A type that meets the requirements of a constant
267
+ *Cpp17RandomAccessIterator*[[random.access.iterators]], models
268
+ `contiguous_iterator` [[iterator.concept.contiguous]], and meets the
269
+ constexpr iterator requirements [[iterator.requirements.general]], whose
270
+ `value_type` is the template parameter `charT`.
271
 
272
+ All requirements on container iterators [[container.requirements]] apply
273
+ to `basic_string_view::const_iterator` as well.
 
 
 
 
274
 
275
  ``` cpp
276
  constexpr const_iterator begin() const noexcept;
277
  constexpr const_iterator cbegin() const noexcept;
278
  ```
279
 
280
  *Returns:* An iterator such that
281
 
282
+ - if `!empty()`, `addressof(*begin()) == data_`,
283
  - otherwise, an unspecified value such that \[`begin()`, `end()`) is a
284
  valid range.
285
 
286
  ``` cpp
287
  constexpr const_iterator end() const noexcept;
 
306
 
307
  #### Capacity <a id="string.view.capacity">[[string.view.capacity]]</a>
308
 
309
  ``` cpp
310
  constexpr size_type size() const noexcept;
 
 
 
 
 
311
  constexpr size_type length() const noexcept;
312
  ```
313
 
314
  *Returns:* `size_`.
315
 
 
319
 
320
  *Returns:* The largest possible number of char-like objects that can be
321
  referred to by a `basic_string_view`.
322
 
323
  ``` cpp
324
+ [[nodiscard]] constexpr bool empty() const noexcept;
325
  ```
326
 
327
  *Returns:* `size_ == 0`.
328
 
329
  #### Element access <a id="string.view.access">[[string.view.access]]</a>
330
 
331
  ``` cpp
332
  constexpr const_reference operator[](size_type pos) const;
333
  ```
334
 
335
+ *Preconditions:* `pos < size()`.
336
 
337
  *Returns:* `data_[pos]`.
338
 
339
  *Throws:* Nothing.
340
 
 
352
 
353
  ``` cpp
354
  constexpr const_reference front() const;
355
  ```
356
 
357
+ *Preconditions:* `!empty()`.
358
 
359
  *Returns:* `data_[0]`.
360
 
361
  *Throws:* Nothing.
362
 
363
  ``` cpp
364
  constexpr const_reference back() const;
365
  ```
366
 
367
+ *Preconditions:* `!empty()`.
368
 
369
  *Returns:* `data_[size() - 1]`.
370
 
371
  *Throws:* Nothing.
372
 
 
374
  constexpr const_pointer data() const noexcept;
375
  ```
376
 
377
  *Returns:* `data_`.
378
 
379
+ [*Note 2*: Unlike `basic_string::data()` and *string-literal*s,
380
+ `data()` may return a pointer to a buffer that is not null-terminated.
381
+ Therefore it is typically a mistake to pass `data()` to a function that
382
+ takes just a `const charT*` and expects a null-terminated
383
+ string. — *end note*]
384
 
385
  #### Modifiers <a id="string.view.modifiers">[[string.view.modifiers]]</a>
386
 
387
  ``` cpp
388
  constexpr void remove_prefix(size_type n);
389
  ```
390
 
391
+ *Preconditions:* `n <= size()`.
392
 
393
  *Effects:* Equivalent to: `data_ += n; size_ -= n;`
394
 
395
  ``` cpp
396
  constexpr void remove_suffix(size_type n);
397
  ```
398
 
399
+ *Preconditions:* `n <= size()`.
400
 
401
  *Effects:* Equivalent to: `size_ -= n;`
402
 
403
  ``` cpp
404
  constexpr void swap(basic_string_view& s) noexcept;
 
407
  *Effects:* Exchanges the values of `*this` and `s`.
408
 
409
  #### String operations <a id="string.view.ops">[[string.view.ops]]</a>
410
 
411
  ``` cpp
412
+ constexpr size_type copy(charT* s, size_type n, size_type pos = 0) const;
413
  ```
414
 
415
  Let `rlen` be the smaller of `n` and `size() - pos`.
416
 
417
  *Throws:* `out_of_range` if `pos > size()`.
418
 
419
+ *Preconditions:* \[`s`, `s + rlen`) is a valid range.
420
 
421
  *Effects:* Equivalent to `traits::copy(s, data() + pos, rlen)`.
422
 
423
  *Returns:* `rlen`.
424
 
 
449
 
450
  *Complexity:* 𝑂(`rlen`).
451
 
452
  *Returns:* The nonzero result if the result of the comparison is
453
  nonzero. Otherwise, returns a value as indicated in
454
+ [[string.view.compare]].
455
 
456
+ **Table: `compare()` results** <a id="string.view.compare">[string.view.compare]</a>
457
 
458
  | Condition | Return Value |
459
  | ---------------------- | ------------ |
460
  | `size() < str.size()` | `< 0` |
461
  | `size() == str.size()` | ` 0` |
 
487
 
488
  *Effects:* Equivalent to:
489
  `return substr(pos1, n1).compare(basic_string_view(s));`
490
 
491
  ``` cpp
492
+ constexpr int compare(size_type pos1, size_type n1, const charT* s, size_type n2) const;
 
493
  ```
494
 
495
  *Effects:* Equivalent to:
496
  `return substr(pos1, n1).compare(basic_string_view(s, n2));`
497
 
498
+ ``` cpp
499
+ constexpr bool starts_with(basic_string_view x) const noexcept;
500
+ ```
501
+
502
+ *Effects:* Equivalent to: `return substr(0, x.size()) == x;`
503
+
504
+ ``` cpp
505
+ constexpr bool starts_with(charT x) const noexcept;
506
+ ```
507
+
508
+ *Effects:* Equivalent to: `return !empty() && traits::eq(front(), x);`
509
+
510
+ ``` cpp
511
+ constexpr bool starts_with(const charT* x) const;
512
+ ```
513
+
514
+ *Effects:* Equivalent to: `return starts_with(basic_string_view(x));`
515
+
516
+ ``` cpp
517
+ constexpr bool ends_with(basic_string_view x) const noexcept;
518
+ ```
519
+
520
+ *Effects:* Equivalent to:
521
+
522
+ ``` cpp
523
+ return size() >= x.size() && compare(size() - x.size(), npos, x) == 0;
524
+ ```
525
+
526
+ ``` cpp
527
+ constexpr bool ends_with(charT x) const noexcept;
528
+ ```
529
+
530
+ *Effects:* Equivalent to: `return !empty() && traits::eq(back(), x);`
531
+
532
+ ``` cpp
533
+ constexpr bool ends_with(const charT* x) const;
534
+ ```
535
+
536
+ *Effects:* Equivalent to: `return ends_with(basic_string_view(x));`
537
+
538
  #### Searching <a id="string.view.find">[[string.view.find]]</a>
539
 
540
+ Member functions in this subclause have complexity
541
+ 𝑂(`size() * str.size()`) at worst, although implementations should do
542
+ better.
543
 
544
+ Let *F* be one of `find`, `rfind`, `find_first_of`, `find_last_of`,
545
+ `find_first_not_of`, and `find_last_not_of`.
 
 
 
546
 
547
+ - Each member function of the form
548
  ``` cpp
549
+ constexpr return-type F(const charT* s, size_type pos) const;
550
  ```
551
 
552
+ has effects equivalent to: `return F(basic_string_view(s), pos);`
553
+ - Each member function of the form
 
 
554
  ``` cpp
555
+ constexpr return-type F(const charT* s, size_type pos, size_type n) const;
556
  ```
557
 
558
+ has effects equivalent to: `return F(basic_string_view(s, n), pos);`
559
+ - Each member function of the form
 
 
560
  ``` cpp
561
+ constexpr return-type F(charT c, size_type pos) const noexcept;
562
  ```
563
 
564
+ has effects equivalent to:
565
+ `return F(basic_string_view(addressof(c), 1), pos);`
566
 
567
  ``` cpp
568
  constexpr size_type find(basic_string_view str, size_type pos = 0) const noexcept;
569
  ```
570
 
 
664
  *Effects:* Determines `xpos`.
665
 
666
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
667
  Otherwise, returns `npos`.
668
 
669
+ ### Deduction guide <a id="string.view.deduct">[[string.view.deduct]]</a>
670
+
671
+ ``` cpp
672
+ template<class It, class End>
673
+ basic_string_view(It, End) -> basic_string_view<iter_value_t<It>>;
674
+ ```
675
+
676
+ *Constraints:*
677
+
678
+ - `It` satisfies `contiguous_iterator`.
679
+ - `End` satisfies `sized_sentinel_for<It>`.
680
+
681
  ### Non-member comparison functions <a id="string.view.comparison">[[string.view.comparison]]</a>
682
 
683
  Let `S` be `basic_string_view<charT, traits>`, and `sv` be an instance
684
  of `S`. Implementations shall provide sufficient additional overloads
685
  marked `constexpr` and `noexcept` so that an object `t` with an implicit
686
+ conversion to `S` can be compared according to
687
+ [[string.view.comparison.overloads]].
688
 
689
+ **Table: Additional `basic_string_view` comparison overloads** <a id="string.view.comparison.overloads">[string.view.comparison.overloads]</a>
690
 
691
  | Expression | Equivalent to |
692
  | ---------- | ------------- |
693
  | `t == sv` | `S(t) == sv` |
694
  | `sv == t` | `sv == S(t)` |
 
700
  | `sv > t` | `sv > S(t)` |
701
  | `t <= sv` | `S(t) <= sv` |
702
  | `sv <= t` | `sv <= S(t)` |
703
  | `t >= sv` | `S(t) >= sv` |
704
  | `sv >= t` | `sv >= S(t)` |
705
+ | `t <=> sv` | `S(t) <=> sv` |
706
+ | `sv <=> t` | `sv <=> S(t)` |
707
 
708
 
709
  [*Example 1*:
710
 
711
  A sample conforming implementation for `operator==` would be:
712
 
713
  ``` cpp
 
714
  template<class charT, class traits>
715
  constexpr bool operator==(basic_string_view<charT, traits> lhs,
716
  basic_string_view<charT, traits> rhs) noexcept {
717
  return lhs.compare(rhs) == 0;
718
  }
719
  template<class charT, class traits>
720
  constexpr bool operator==(basic_string_view<charT, traits> lhs,
721
+ type_identity_t<basic_string_view<charT, traits>> rhs) noexcept {
 
 
 
 
 
722
  return lhs.compare(rhs) == 0;
723
  }
724
  ```
725
 
726
  — *end example*]
 
733
 
734
  *Returns:* `lhs.compare(rhs) == 0`.
735
 
736
  ``` cpp
737
  template<class charT, class traits>
738
+ constexpr see below operator<=>(basic_string_view<charT, traits> lhs,
739
+ \itcorr basic_string_view<charT, traits> rhs) noexcept;
740
  ```
741
 
742
+ Let `R` denote the type `traits::comparison_category` if it exists,
743
+ otherwise `R` is `weak_ordering`.
744
 
745
+ *Returns:* `static_cast<R>(lhs.compare(rhs) <=> 0)`.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
746
 
747
  ### Inserters and extractors <a id="string.view.io">[[string.view.io]]</a>
748
 
749
  ``` cpp
750
  template<class charT, class traits>
751
  basic_ostream<charT, traits>&
752
+ operator<<(basic_ostream<charT, traits>& os, basic_string_view<charT, traits> str);
 
753
  ```
754
 
755
  *Effects:* Behaves as a formatted output
756
+ function [[ostream.formatted.reqmts]] of `os`. Forms a character
757
  sequence `seq`, initially consisting of the elements defined by the
758
  range \[`str.begin()`, `str.end()`). Determines padding for `seq` as
759
  described in  [[ostream.formatted.reqmts]]. Then inserts `seq` as if by
760
  calling `os.rdbuf()->sputn(seq, n)`, where `n` is the larger of
761
  `os.width()` and `str.size()`; then calls `os.width(0)`.
 
764
 
765
  ### Hash support <a id="string.view.hash">[[string.view.hash]]</a>
766
 
767
  ``` cpp
768
  template<> struct hash<string_view>;
769
+ template<> struct hash<u8string_view>;
770
  template<> struct hash<u16string_view>;
771
  template<> struct hash<u32string_view>;
772
  template<> struct hash<wstring_view>;
773
  ```
774
 
775
+ The specialization is enabled [[unord.hash]].
776
 
777
  [*Note 1*: The hash value of a string view object is equal to the hash
778
+ value of the corresponding string
779
+ object [[basic.string.hash]]. — *end note*]
780
 
781
  ### Suffix for `basic_string_view` literals <a id="string.view.literals">[[string.view.literals]]</a>
782
 
783
  ``` cpp
784
  constexpr string_view operator""sv(const char* str, size_t len) noexcept;
785
  ```
786
 
787
  *Returns:* `string_view{str, len}`.
788
 
789
+ ``` cpp
790
+ constexpr u8string_view operator""sv(const char8_t* str, size_t len) noexcept;
791
+ ```
792
+
793
+ *Returns:* `u8string_view{str, len}`.
794
+
795
  ``` cpp
796
  constexpr u16string_view operator""sv(const char16_t* str, size_t len) noexcept;
797
  ```
798
 
799
  *Returns:* `u16string_view{str, len}`.