From Jason Turner

[string.view.template]

C++20 → C++23 9.3 KB 116 lines
Current Draft | LaTeX Source
Archived: C++20 | C++23
Markdown: C++20 | C++23
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpekfgbfyv/{from.md → to.md} +89 -14
tmp/tmpekfgbfyv/{from.md → to.md} RENAMED
@@ -1,8 +1,11 @@
1
  ### Class template `basic_string_view` <a id="string.view.template">[[string.view.template]]</a>
2
 
 
 
3
  ``` cpp
 
4
  template<class charT, class traits = char_traits<charT>>
5
  class basic_string_view {
6
  public:
7
  // types
8
  using traits_type = traits;
@@ -10,11 +13,11 @@ public:
10
  using pointer = value_type*;
11
  using const_pointer = const value_type*;
12
  using reference = value_type&;
13
  using const_reference = const value_type&;
14
  using const_iterator = implementation-defined // type of basic_string_view::const_iterator; // see [string.view.iterators]
15
- using iterator = const_iterator;\footnote{Because basic_string_view refers to a constant sequence, iterator and const_iterator are the same type.}
16
  using const_reverse_iterator = reverse_iterator<const_iterator>;
17
  using reverse_iterator = const_reverse_iterator;
18
  using size_type = size_t;
19
  using difference_type = ptrdiff_t;
20
  static constexpr size_type npos = size_type(-1);
@@ -22,13 +25,16 @@ public:
22
  // [string.view.cons], construction and assignment
23
  constexpr basic_string_view() noexcept;
24
  constexpr basic_string_view(const basic_string_view&) noexcept = default;
25
  constexpr basic_string_view& operator=(const basic_string_view&) noexcept = default;
26
  constexpr basic_string_view(const charT* str);
 
27
  constexpr basic_string_view(const charT* str, size_type len);
28
  template<class It, class End>
29
  constexpr basic_string_view(It begin, End end);
 
 
30
 
31
  // [string.view.iterators], iterator support
32
  constexpr const_iterator begin() const noexcept;
33
  constexpr const_iterator end() const noexcept;
34
  constexpr const_iterator cbegin() const noexcept;
@@ -74,10 +80,14 @@ public:
74
  constexpr bool starts_with(const charT* x) const;
75
  constexpr bool ends_with(basic_string_view x) const noexcept;
76
  constexpr bool ends_with(charT x) const noexcept;
77
  constexpr bool ends_with(const charT* x) const;
78
 
 
 
 
 
79
  // [string.view.find], searching
80
  constexpr size_type find(basic_string_view s, size_type pos = 0) const noexcept;
81
  constexpr size_type find(charT c, size_type pos = 0) const noexcept;
82
  constexpr size_type find(const charT* s, size_type pos, size_type n) const;
83
  constexpr size_type find(const charT* s, size_type pos = 0) const;
@@ -109,29 +119,42 @@ public:
109
  private:
110
  const_pointer data_; // exposition only
111
  size_type size_; // exposition only
112
  };
113
 
114
- // [string.view.deduct], deduction guide
115
  template<class It, class End>
116
  basic_string_view(It, End) -> basic_string_view<iter_value_t<It>>;
 
 
 
117
  ```
118
 
 
 
119
  In every specialization `basic_string_view<charT, traits>`, the type
120
  `traits` shall meet the character traits requirements [[char.traits]].
121
 
122
  [*Note 1*: The program is ill-formed if `traits::char_type` is not the
123
  same type as `charT`. — *end note*]
124
 
125
  For a `basic_string_view str`, any operation that invalidates a pointer
126
- in the range \[`str.data()`, `str.data() + str.size()`) invalidates
127
- pointers, iterators, and references returned from `str`’s member
128
- functions.
 
 
 
 
 
129
 
130
  The complexity of `basic_string_view` member functions is 𝑂(1) unless
131
  otherwise specified.
132
 
 
 
 
133
  #### Construction and assignment <a id="string.view.cons">[[string.view.cons]]</a>
134
 
135
  ``` cpp
136
  constexpr basic_string_view() noexcept;
137
  ```
@@ -177,10 +200,53 @@ template<class It, class End>
177
  - `End` models `sized_sentinel_for<It>`.
178
 
179
  *Effects:* Initializes `data_` with `to_address(begin)` and initializes
180
  `size_` with `end - begin`.
181
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
182
  #### Iterator support <a id="string.view.iterators">[[string.view.iterators]]</a>
183
 
184
  ``` cpp
185
  using const_iterator = implementation-defined // type of basic_string_view::const_iterator;
186
  ```
@@ -266,14 +332,14 @@ of returning `charT()`. — *end note*]
266
 
267
  ``` cpp
268
  constexpr const_reference at(size_type pos) const;
269
  ```
270
 
 
 
271
  *Throws:* `out_of_range` if `pos >= size()`.
272
 
273
- *Returns:* `data_[pos]`.
274
-
275
  ``` cpp
276
  constexpr const_reference front() const;
277
  ```
278
 
279
  *Preconditions:* `!empty()`.
@@ -297,11 +363,11 @@ constexpr const_pointer data() const noexcept;
297
  ```
298
 
299
  *Returns:* `data_`.
300
 
301
  [*Note 2*: Unlike `basic_string::data()` and *string-literal*s,
302
- `data()` may return a pointer to a buffer that is not null-terminated.
303
  Therefore it is typically a mistake to pass `data()` to a function that
304
  takes just a `const charT*` and expects a null-terminated
305
  string. — *end note*]
306
 
307
  #### Modifiers <a id="string.view.modifiers">[[string.view.modifiers]]</a>
@@ -334,45 +400,43 @@ constexpr void swap(basic_string_view& s) noexcept;
334
  constexpr size_type copy(charT* s, size_type n, size_type pos = 0) const;
335
  ```
336
 
337
  Let `rlen` be the smaller of `n` and `size() - pos`.
338
 
339
- *Throws:* `out_of_range` if `pos > size()`.
340
-
341
  *Preconditions:* \[`s`, `s + rlen`) is a valid range.
342
 
343
  *Effects:* Equivalent to `traits::copy(s, data() + pos, rlen)`.
344
 
345
  *Returns:* `rlen`.
346
 
 
 
347
  *Complexity:* 𝑂(`rlen`).
348
 
349
  ``` cpp
350
  constexpr basic_string_view substr(size_type pos = 0, size_type n = npos) const;
351
  ```
352
 
353
  Let `rlen` be the smaller of `n` and `size() - pos`.
354
 
355
- *Throws:* `out_of_range` if `pos > size()`.
356
-
357
  *Effects:* Determines `rlen`, the effective length of the string to
358
  reference.
359
 
360
  *Returns:* `basic_string_view(data() + pos, rlen)`.
361
 
 
 
362
  ``` cpp
363
  constexpr int compare(basic_string_view str) const noexcept;
364
  ```
365
 
366
  Let `rlen` be the smaller of `size()` and `str.size()`.
367
 
368
  *Effects:* Determines `rlen`, the effective length of the strings to
369
  compare. The function then compares the two strings by calling
370
  `traits::compare(data(), str.data(), rlen)`.
371
 
372
- *Complexity:* 𝑂(`rlen`).
373
-
374
  *Returns:* The nonzero result if the result of the comparison is
375
  nonzero. Otherwise, returns a value as indicated in
376
  [[string.view.compare]].
377
 
378
  **Table: `compare()` results** <a id="string.view.compare">[string.view.compare]</a>
@@ -381,10 +445,13 @@ nonzero. Otherwise, returns a value as indicated in
381
  | ---------------------- | ------------ |
382
  | `size() < str.size()` | `< 0` |
383
  | `size() == str.size()` | ` 0` |
384
  | `size() > str.size()` | `> 0` |
385
 
 
 
 
386
  ``` cpp
387
  constexpr int compare(size_type pos1, size_type n1, basic_string_view str) const;
388
  ```
389
 
390
  *Effects:* Equivalent to: `return substr(pos1, n1).compare(str);`
@@ -455,10 +522,18 @@ constexpr bool ends_with(charT x) const noexcept;
455
  constexpr bool ends_with(const charT* x) const;
456
  ```
457
 
458
  *Effects:* Equivalent to: `return ends_with(basic_string_view(x));`
459
 
 
 
 
 
 
 
 
 
460
  #### Searching <a id="string.view.find">[[string.view.find]]</a>
461
 
462
  Member functions in this subclause have complexity
463
  𝑂(`size() * str.size()`) at worst, although implementations should do
464
  better.
 
1
  ### Class template `basic_string_view` <a id="string.view.template">[[string.view.template]]</a>
2
 
3
+ #### General <a id="string.view.template.general">[[string.view.template.general]]</a>
4
+
5
  ``` cpp
6
+ namespace std {
7
  template<class charT, class traits = char_traits<charT>>
8
  class basic_string_view {
9
  public:
10
  // types
11
  using traits_type = traits;
 
13
  using pointer = value_type*;
14
  using const_pointer = const value_type*;
15
  using reference = value_type&;
16
  using const_reference = const value_type&;
17
  using const_iterator = implementation-defined // type of basic_string_view::const_iterator; // see [string.view.iterators]
18
+ using iterator = const_iterator;
19
  using const_reverse_iterator = reverse_iterator<const_iterator>;
20
  using reverse_iterator = const_reverse_iterator;
21
  using size_type = size_t;
22
  using difference_type = ptrdiff_t;
23
  static constexpr size_type npos = size_type(-1);
 
25
  // [string.view.cons], construction and assignment
26
  constexpr basic_string_view() noexcept;
27
  constexpr basic_string_view(const basic_string_view&) noexcept = default;
28
  constexpr basic_string_view& operator=(const basic_string_view&) noexcept = default;
29
  constexpr basic_string_view(const charT* str);
30
+ basic_string_view(nullptr_t) = delete;
31
  constexpr basic_string_view(const charT* str, size_type len);
32
  template<class It, class End>
33
  constexpr basic_string_view(It begin, End end);
34
+ template<class R>
35
+ constexpr explicit basic_string_view(R&& r);
36
 
37
  // [string.view.iterators], iterator support
38
  constexpr const_iterator begin() const noexcept;
39
  constexpr const_iterator end() const noexcept;
40
  constexpr const_iterator cbegin() const noexcept;
 
80
  constexpr bool starts_with(const charT* x) const;
81
  constexpr bool ends_with(basic_string_view x) const noexcept;
82
  constexpr bool ends_with(charT x) const noexcept;
83
  constexpr bool ends_with(const charT* x) const;
84
 
85
+ constexpr bool contains(basic_string_view x) const noexcept;
86
+ constexpr bool contains(charT x) const noexcept;
87
+ constexpr bool contains(const charT* x) const;
88
+
89
  // [string.view.find], searching
90
  constexpr size_type find(basic_string_view s, size_type pos = 0) const noexcept;
91
  constexpr size_type find(charT c, size_type pos = 0) const noexcept;
92
  constexpr size_type find(const charT* s, size_type pos, size_type n) const;
93
  constexpr size_type find(const charT* s, size_type pos = 0) const;
 
119
  private:
120
  const_pointer data_; // exposition only
121
  size_type size_; // exposition only
122
  };
123
 
124
+ // [string.view.deduct], deduction guides
125
  template<class It, class End>
126
  basic_string_view(It, End) -> basic_string_view<iter_value_t<It>>;
127
+ template<class R>
128
+ basic_string_view(R&&) -> basic_string_view<ranges::range_value_t<R>>;
129
+ }
130
  ```
131
 
132
+ [^2]
133
+
134
  In every specialization `basic_string_view<charT, traits>`, the type
135
  `traits` shall meet the character traits requirements [[char.traits]].
136
 
137
  [*Note 1*: The program is ill-formed if `traits::char_type` is not the
138
  same type as `charT`. — *end note*]
139
 
140
  For a `basic_string_view str`, any operation that invalidates a pointer
141
+ in the range
142
+
143
+ ``` cpp
144
+ {[}str.data(), {str.data() + str.size()}{)}
145
+ ```
146
+
147
+ invalidates pointers, iterators, and references returned from `str`’s
148
+ member functions.
149
 
150
  The complexity of `basic_string_view` member functions is 𝑂(1) unless
151
  otherwise specified.
152
 
153
+ `basic_string_view<charT, traits>` is a trivially copyable type
154
+ [[term.trivially.copyable.type]].
155
+
156
  #### Construction and assignment <a id="string.view.cons">[[string.view.cons]]</a>
157
 
158
  ``` cpp
159
  constexpr basic_string_view() noexcept;
160
  ```
 
200
  - `End` models `sized_sentinel_for<It>`.
201
 
202
  *Effects:* Initializes `data_` with `to_address(begin)` and initializes
203
  `size_` with `end - begin`.
204
 
205
+ *Throws:* When and what `end - begin` throws.
206
+
207
+ ``` cpp
208
+ template<class R>
209
+ constexpr explicit basic_string_view(R&& r);
210
+ ```
211
+
212
+ Let `d` be an lvalue of type `remove_cvref_t<R>`.
213
+
214
+ *Constraints:*
215
+
216
+ - `remove_cvref_t<R>` is not the same type as `basic_string_view`,
217
+ - `R` models `ranges::contiguous_range` and `ranges::sized_range`,
218
+ - `is_same_v<ranges::range_value_t<R>, charT>` is `true`,
219
+ - `is_convertible_v<R, const charT*>` is `false`, and
220
+ - `d.operator ::std::basic_string_view<charT, traits>()` is not a valid
221
+ expression.
222
+
223
+ *Effects:* Initializes `data_` with `ranges::data(r)` and `size_` with
224
+ `ranges::size(r)`.
225
+
226
+ *Throws:* Any exception thrown by `ranges::data(r)` and
227
+ `ranges::size(r)`.
228
+
229
+ #### Deduction guides <a id="string.view.deduct">[[string.view.deduct]]</a>
230
+
231
+ ``` cpp
232
+ template<class It, class End>
233
+ basic_string_view(It, End) -> basic_string_view<iter_value_t<It>>;
234
+ ```
235
+
236
+ *Constraints:*
237
+
238
+ - `It` satisfies `contiguous_iterator`.
239
+ - `End` satisfies `sized_sentinel_for<It>`.
240
+
241
+ ``` cpp
242
+ template<class R>
243
+ basic_string_view(R&&) -> basic_string_view<ranges::range_value_t<R>>;
244
+ ```
245
+
246
+ *Constraints:* `R` satisfies `ranges::contiguous_range`.
247
+
248
  #### Iterator support <a id="string.view.iterators">[[string.view.iterators]]</a>
249
 
250
  ``` cpp
251
  using const_iterator = implementation-defined // type of basic_string_view::const_iterator;
252
  ```
 
332
 
333
  ``` cpp
334
  constexpr const_reference at(size_type pos) const;
335
  ```
336
 
337
+ *Returns:* `data_[pos]`.
338
+
339
  *Throws:* `out_of_range` if `pos >= size()`.
340
 
 
 
341
  ``` cpp
342
  constexpr const_reference front() const;
343
  ```
344
 
345
  *Preconditions:* `!empty()`.
 
363
  ```
364
 
365
  *Returns:* `data_`.
366
 
367
  [*Note 2*: Unlike `basic_string::data()` and *string-literal*s,
368
+ `data()` can return a pointer to a buffer that is not null-terminated.
369
  Therefore it is typically a mistake to pass `data()` to a function that
370
  takes just a `const charT*` and expects a null-terminated
371
  string. — *end note*]
372
 
373
  #### Modifiers <a id="string.view.modifiers">[[string.view.modifiers]]</a>
 
400
  constexpr size_type copy(charT* s, size_type n, size_type pos = 0) const;
401
  ```
402
 
403
  Let `rlen` be the smaller of `n` and `size() - pos`.
404
 
 
 
405
  *Preconditions:* \[`s`, `s + rlen`) is a valid range.
406
 
407
  *Effects:* Equivalent to `traits::copy(s, data() + pos, rlen)`.
408
 
409
  *Returns:* `rlen`.
410
 
411
+ *Throws:* `out_of_range` if `pos > size()`.
412
+
413
  *Complexity:* 𝑂(`rlen`).
414
 
415
  ``` cpp
416
  constexpr basic_string_view substr(size_type pos = 0, size_type n = npos) const;
417
  ```
418
 
419
  Let `rlen` be the smaller of `n` and `size() - pos`.
420
 
 
 
421
  *Effects:* Determines `rlen`, the effective length of the string to
422
  reference.
423
 
424
  *Returns:* `basic_string_view(data() + pos, rlen)`.
425
 
426
+ *Throws:* `out_of_range` if `pos > size()`.
427
+
428
  ``` cpp
429
  constexpr int compare(basic_string_view str) const noexcept;
430
  ```
431
 
432
  Let `rlen` be the smaller of `size()` and `str.size()`.
433
 
434
  *Effects:* Determines `rlen`, the effective length of the strings to
435
  compare. The function then compares the two strings by calling
436
  `traits::compare(data(), str.data(), rlen)`.
437
 
 
 
438
  *Returns:* The nonzero result if the result of the comparison is
439
  nonzero. Otherwise, returns a value as indicated in
440
  [[string.view.compare]].
441
 
442
  **Table: `compare()` results** <a id="string.view.compare">[string.view.compare]</a>
 
445
  | ---------------------- | ------------ |
446
  | `size() < str.size()` | `< 0` |
447
  | `size() == str.size()` | ` 0` |
448
  | `size() > str.size()` | `> 0` |
449
 
450
+
451
+ *Complexity:* 𝑂(`rlen`).
452
+
453
  ``` cpp
454
  constexpr int compare(size_type pos1, size_type n1, basic_string_view str) const;
455
  ```
456
 
457
  *Effects:* Equivalent to: `return substr(pos1, n1).compare(str);`
 
522
  constexpr bool ends_with(const charT* x) const;
523
  ```
524
 
525
  *Effects:* Equivalent to: `return ends_with(basic_string_view(x));`
526
 
527
+ ``` cpp
528
+ constexpr bool contains(basic_string_view x) const noexcept;
529
+ constexpr bool contains(charT x) const noexcept;
530
+ constexpr bool contains(const charT* x) const;
531
+ ```
532
+
533
+ *Effects:* Equivalent to: `return find(x) != npos;`
534
+
535
  #### Searching <a id="string.view.find">[[string.view.find]]</a>
536
 
537
  Member functions in this subclause have complexity
538
  𝑂(`size() * str.size()`) at worst, although implementations should do
539
  better.