From Jason Turner

[stringbuf]

C++17 → C++20 21.7 KB 363 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/tmpxbh493sr/{from.md → to.md} +271 -84
tmp/tmpxbh493sr/{from.md → to.md} RENAMED
@@ -12,26 +12,55 @@ namespace std {
12
  using off_type = typename traits::off_type;
13
  using traits_type = traits;
14
  using allocator_type = Allocator;
15
 
16
  // [stringbuf.cons], constructors
 
 
17
  explicit basic_stringbuf(
 
18
  ios_base::openmode which = ios_base::in | ios_base::out);
 
 
 
19
  explicit basic_stringbuf(
20
- const basic_string<charT, traits, Allocator>& str,
21
  ios_base::openmode which = ios_base::in | ios_base::out);
22
- basic_stringbuf(const basic_stringbuf& rhs) = delete;
 
 
 
 
 
 
 
 
 
 
 
 
23
  basic_stringbuf(basic_stringbuf&& rhs);
 
24
 
25
  // [stringbuf.assign], assign and swap
26
- basic_stringbuf& operator=(const basic_stringbuf& rhs) = delete;
27
  basic_stringbuf& operator=(basic_stringbuf&& rhs);
28
- void swap(basic_stringbuf& rhs);
 
 
 
 
 
 
 
 
 
29
 
30
- // [stringbuf.members], get and set
31
- basic_string<charT, traits, Allocator> str() const;
32
  void str(const basic_string<charT, traits, Allocator>& s);
 
 
 
33
 
34
  protected:
35
  // [stringbuf.virtuals], overridden virtual functions
36
  int_type underflow() override;
37
  int_type pbackfail(int_type c = traits::eof()) override;
@@ -45,66 +74,120 @@ namespace std {
45
  ios_base::openmode which
46
  = ios_base::in | ios_base::out) override;
47
 
48
  private:
49
  ios_base::openmode mode; // exposition only
 
 
50
  };
51
 
52
  template<class charT, class traits, class Allocator>
53
  void swap(basic_stringbuf<charT, traits, Allocator>& x,
54
- basic_stringbuf<charT, traits, Allocator>& y);
55
  }
56
  ```
57
 
58
  The class `basic_stringbuf` is derived from `basic_streambuf` to
59
  associate possibly the input sequence and possibly the output sequence
60
  with a sequence of arbitrary *characters*. The sequence can be
61
  initialized from, or made available as, an object of class
62
  `basic_string`.
63
 
64
- For the sake of exposition, the maintained data is presented here as:
 
65
 
66
  - `ios_base::openmode mode`, has `in` set if the input sequence can be
67
  read, and `out` set if the output sequence can be written.
 
 
 
 
 
68
 
69
- #### `basic_stringbuf` constructors <a id="stringbuf.cons">[[stringbuf.cons]]</a>
70
 
71
  ``` cpp
72
- explicit basic_stringbuf(
73
- ios_base::openmode which = ios_base::in | ios_base::out);
74
  ```
75
 
76
- *Effects:* Constructs an object of class `basic_stringbuf`, initializing
77
- the base class with `basic_streambuf()` ([[streambuf.cons]]), and
78
- initializing `mode` with `which`.
 
 
79
 
80
- *Postconditions:* `str() == ""`.
81
 
82
  ``` cpp
83
  explicit basic_stringbuf(
84
  const basic_string<charT, traits, Allocator>& s,
85
  ios_base::openmode which = ios_base::in | ios_base::out);
86
  ```
87
 
88
- *Effects:* Constructs an object of class `basic_stringbuf`, initializing
89
- the base class with `basic_streambuf()` ([[streambuf.cons]]), and
90
- initializing `mode` with `which`. Then calls `str(s)`.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
91
 
92
  ``` cpp
93
  basic_stringbuf(basic_stringbuf&& rhs);
 
94
  ```
95
 
96
- *Effects:* Move constructs from the rvalue `rhs`. It is
97
- *implementation-defined* whether the sequence pointers in `*this`
98
- (`eback()`, `gptr()`, `egptr()`, `pbase()`, `pptr()`, `epptr()`) obtain
99
- the values which `rhs` had. Whether they do or not, `*this` and `rhs`
100
- reference separate buffers (if any at all) after the construction. The
101
- openmode, locale and any other state of `rhs` is also copied.
102
 
103
- *Postconditions:* Let `rhs_p` refer to the state of `rhs` just prior to
104
- this construction and let `rhs_a` refer to the state of `rhs` just after
105
- this construction.
106
 
107
  - `str() == rhs_p.str()`
108
  - `gptr() - eback() == rhs_p.gptr() - rhs_p.eback()`
109
  - `egptr() - eback() == rhs_p.egptr() - rhs_p.eback()`
110
  - `pptr() - pbase() == rhs_p.pptr() - rhs_p.pbase()`
@@ -113,12 +196,14 @@ this construction.
113
  - `if (gptr()) gptr() != rhs_a.gptr()`
114
  - `if (egptr()) egptr() != rhs_a.egptr()`
115
  - `if (pbase()) pbase() != rhs_a.pbase()`
116
  - `if (pptr()) pptr() != rhs_a.pptr()`
117
  - `if (epptr()) epptr() != rhs_a.epptr()`
 
 
118
 
119
- #### Assign and swap <a id="stringbuf.assign">[[stringbuf.assign]]</a>
120
 
121
  ``` cpp
122
  basic_stringbuf& operator=(basic_stringbuf&& rhs);
123
  ```
124
 
@@ -127,62 +212,165 @@ would have had if it had been move constructed from `rhs`
127
  (see  [[stringbuf.cons]]).
128
 
129
  *Returns:* `*this`.
130
 
131
  ``` cpp
132
- void swap(basic_stringbuf& rhs);
133
  ```
134
 
 
 
 
 
135
  *Effects:* Exchanges the state of `*this` and `rhs`.
136
 
 
 
 
 
137
  ``` cpp
138
  template<class charT, class traits, class Allocator>
139
  void swap(basic_stringbuf<charT, traits, Allocator>& x,
140
- basic_stringbuf<charT, traits, Allocator>& y);
141
  ```
142
 
143
- *Effects:* As if by `x.swap(y)`.
144
 
145
  #### Member functions <a id="stringbuf.members">[[stringbuf.members]]</a>
146
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
147
  ``` cpp
148
- basic_string<charT, traits, Allocator> str() const;
149
- ```
150
-
151
- *Returns:* A `basic_string` object whose content is equal to the
152
- `basic_stringbuf` underlying character sequence. If the
153
- `basic_stringbuf` was created only in input mode, the resultant
154
- `basic_string` contains the character sequence in the range \[`eback()`,
155
- `egptr()`). If the `basic_stringbuf` was created with
156
- `which & ios_base::out` being nonzero then the resultant `basic_string`
157
- contains the character sequence in the range \[`pbase()`, `high_mark`),
158
- where `high_mark` represents the position one past the highest
159
- initialized character in the buffer. Characters can be initialized by
160
- writing to the stream, by constructing the `basic_stringbuf` with a
161
- `basic_string`, or by calling the `str(basic_string)` member function.
162
- In the case of calling the `str(basic_string)` member function, all
163
- characters initialized prior to the call are now considered
164
- uninitialized (except for those characters re-initialized by the new
165
- `basic_string`). Otherwise the `basic_stringbuf` has been created in
166
- neither input nor output mode and a zero length `basic_string` is
167
- returned.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
168
 
169
  ``` cpp
170
  void str(const basic_string<charT, traits, Allocator>& s);
171
  ```
172
 
173
- *Effects:* Copies the content of `s` into the `basic_stringbuf`
174
- underlying character sequence and initializes the input and output
175
- sequences according to `mode`.
176
-
177
- *Postconditions:* If `mode & ios_base::out` is nonzero, `pbase()` points
178
- to the first underlying character and `epptr()` `>= pbase() + s.size()`
179
- holds; in addition, if `mode & ios_base::ate` is nonzero,
180
- `pptr() == pbase() + s.size()` holds, otherwise `pptr() == pbase()` is
181
- `true`. If `mode & ios_base::in` is nonzero, `eback()` points to the
182
- first underlying character, and both `gptr() == eback()` and
183
- `egptr() == eback() + s.size()` hold.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
184
 
185
  #### Overridden virtual functions <a id="stringbuf.virtuals">[[stringbuf.virtuals]]</a>
186
 
187
  ``` cpp
188
  int_type underflow() override;
@@ -209,11 +397,11 @@ sequence, if possible, in one of three ways:
209
  `ios_base::out` is nonzero, assigns `c` to `*``gptr()`. Returns: `c`.
210
  - If `traits::eq_int_type(c, traits::eof())` returns `true` and if the
211
  input sequence has a putback position available, assigns `gptr() - 1`
212
  to `gptr()`. Returns: `traits::not_eof(c)`.
213
 
214
- *Returns:* `traits::eof()` to indicate failure.
215
 
216
  *Remarks:* If the function can succeed in more than one of these ways,
217
  it is unspecified which way is chosen.
218
 
219
  ``` cpp
@@ -232,56 +420,55 @@ sequence, if possible, in one of two ways:
232
  `traits::eof()`.
233
 
234
  *Remarks:* The function can alter the number of write positions
235
  available as a result of any call.
236
 
237
- *Returns:* `traits::eof()` to indicate failure.
238
 
239
- The function can make a write position available only if
240
- `(mode & ios_base::out) != 0`. To make a write position available, the
241
- function reallocates (or initially allocates) an array object with a
242
- sufficient number of elements to hold the current array object (if any),
243
- plus at least one additional write position. If
244
- `(mode & ios_base::in) != 0`, the function alters the read end pointer
245
- `egptr()` to point just past the new write position.
246
 
247
  ``` cpp
248
  pos_type seekoff(off_type off, ios_base::seekdir way,
249
  ios_base::openmode which
250
  = ios_base::in | ios_base::out) override;
251
  ```
252
 
253
  *Effects:* Alters the stream position within one of the controlled
254
- sequences, if possible, as indicated in
255
- Table  [[tab:iostreams.seekoff.positioning]].
256
 
257
- **Table: `seekoff` positioning** <a id="tab:iostreams.seekoff.positioning">[tab:iostreams.seekoff.positioning]</a>
258
 
259
  | Conditions | Result |
260
- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
261
- | `(which & ios_base::in)`` == ios_base::in` | positions the input sequence |
262
- | `(which & ios_base::out)`` == ios_base::out` | positions the output sequence |
263
- | `(which & (ios_base::in |`<br> `ios_base::out)) ==`<br> `(ios_base::in) |`<br> `ios_base::out))`<br> and `way ==` either<br> `ios_base::beg` or<br> `ios_base::end` | positions both the input and the output sequences |
264
  | Otherwise | the positioning operation fails. |
265
 
266
 
267
- For a sequence to be positioned, if its next pointer (either `gptr()` or
268
- `pptr()`) is a null pointer and the new offset `newoff` is nonzero, the
269
- positioning operation fails. Otherwise, the function determines `newoff`
270
- as indicated in Table  [[tab:iostreams.newoff.values]].
271
 
272
- **Table: `newoff` values** <a id="tab:iostreams.newoff.values">[tab:iostreams.newoff.values]</a>
273
 
274
  | Condition | `newoff` Value |
275
  | ---------------------- | ----------------------------------------------------------------------- |
276
  | `way == ios_base::beg` | 0 |
277
  | `way == ios_base::cur` | the next pointer minus the beginning pointer (`xnext - xbeg`). |
278
  | `way == ios_base::end` | the high mark pointer minus the beginning pointer (`high_mark - xbeg`). |
279
 
280
 
281
  If `(newoff + off) < 0`, or if `newoff + off` refers to an uninitialized
282
- character ([[stringbuf.members]]), the positioning operation fails.
283
  Otherwise, the function assigns `xbeg + newoff + off` to the next
284
  pointer `xnext`.
285
 
286
  *Returns:* `pos_type(newoff)`, constructed from the resultant offset
287
  `newoff` (of type `off_type`), that stores the resultant stream
 
12
  using off_type = typename traits::off_type;
13
  using traits_type = traits;
14
  using allocator_type = Allocator;
15
 
16
  // [stringbuf.cons], constructors
17
+ basic_stringbuf() : basic_stringbuf(ios_base::in | ios_base::out) {}
18
+ explicit basic_stringbuf(ios_base::openmode which);
19
  explicit basic_stringbuf(
20
+ const basic_string<charT, traits, Allocator>& s,
21
  ios_base::openmode which = ios_base::in | ios_base::out);
22
+ explicit basic_stringbuf(const Allocator& a)
23
+ : basic_stringbuf(ios_base::in | ios_base::out, a) {}
24
+ basic_stringbuf(ios_base::openmode which, const Allocator& a);
25
  explicit basic_stringbuf(
26
+ basic_string<charT, traits, Allocator>&& s,
27
  ios_base::openmode which = ios_base::in | ios_base::out);
28
+ template<class SAlloc>
29
+ basic_stringbuf(
30
+ const basic_string<charT, traits, SAlloc>& s, const Allocator& a)
31
+ : basic_stringbuf(s, ios_base::in | ios_base::out, a) {}
32
+ template<class SAlloc>
33
+ basic_stringbuf(
34
+ const basic_string<charT, traits, SAlloc>& s,
35
+ ios_base::openmode which, const Allocator& a);
36
+ template<class SAlloc>
37
+ explicit basic_stringbuf(
38
+ const basic_string<charT, traits, SAlloc>& s,
39
+ ios_base::openmode which = ios_base::in | ios_base::out);
40
+ basic_stringbuf(const basic_stringbuf&) = delete;
41
  basic_stringbuf(basic_stringbuf&& rhs);
42
+ basic_stringbuf(basic_stringbuf&& rhs, const Allocator& a);
43
 
44
  // [stringbuf.assign], assign and swap
45
+ basic_stringbuf& operator=(const basic_stringbuf&) = delete;
46
  basic_stringbuf& operator=(basic_stringbuf&& rhs);
47
+ void swap(basic_stringbuf& rhs) noexcept(see below);
48
+
49
+ // [stringbuf.members], getters and setters
50
+ allocator_type get_allocator() const noexcept;
51
+
52
+ basic_string<charT, traits, Allocator> str() const &;
53
+ template<class SAlloc>
54
+ basic_string<charT,traits,SAlloc> str(const SAlloc& sa) const;
55
+ basic_string<charT, traits, Allocator> str() &&;
56
+ basic_string_view<charT, traits> view() const noexcept;
57
 
 
 
58
  void str(const basic_string<charT, traits, Allocator>& s);
59
+ template<class SAlloc>
60
+ void str(const basic_string<charT, traits, SAlloc>& s);
61
+ void str(basic_string<charT, traits, Allocator>&& s);
62
 
63
  protected:
64
  // [stringbuf.virtuals], overridden virtual functions
65
  int_type underflow() override;
66
  int_type pbackfail(int_type c = traits::eof()) override;
 
74
  ios_base::openmode which
75
  = ios_base::in | ios_base::out) override;
76
 
77
  private:
78
  ios_base::openmode mode; // exposition only
79
+ basic_string<charT, traits, Allocator> buf; // exposition only
80
+ void init_buf_ptrs(); // exposition only
81
  };
82
 
83
  template<class charT, class traits, class Allocator>
84
  void swap(basic_stringbuf<charT, traits, Allocator>& x,
85
+ basic_stringbuf<charT, traits, Allocator>& y) noexcept(noexcept(x.swap(y)));
86
  }
87
  ```
88
 
89
  The class `basic_stringbuf` is derived from `basic_streambuf` to
90
  associate possibly the input sequence and possibly the output sequence
91
  with a sequence of arbitrary *characters*. The sequence can be
92
  initialized from, or made available as, an object of class
93
  `basic_string`.
94
 
95
+ For the sake of exposition, the maintained data and internal pointer
96
+ initialization is presented here as:
97
 
98
  - `ios_base::openmode mode`, has `in` set if the input sequence can be
99
  read, and `out` set if the output sequence can be written.
100
+ - `basic_string<charT, traits, Allocator> buf` contains the underlying
101
+ character sequence.
102
+ - `init_buf_ptrs()` sets the base class’ get area [[streambuf.get.area]]
103
+ and put area [[streambuf.put.area]] pointers after initializing,
104
+ moving from, or assigning to `buf` accordingly.
105
 
106
+ #### Constructors <a id="stringbuf.cons">[[stringbuf.cons]]</a>
107
 
108
  ``` cpp
109
+ explicit basic_stringbuf(ios_base::openmode which);
 
110
  ```
111
 
112
+ *Effects:* Initializes the base class with `basic_streambuf()`
113
+ [[streambuf.cons]], and `mode` with `which`. It is
114
+ *implementation-defined* whether the sequence pointers (`eback()`,
115
+ `gptr()`, `egptr()`, `pbase()`, `pptr()`, `epptr()`) are initialized to
116
+ null pointers.
117
 
118
+ *Ensures:* `str().empty()` is `true`.
119
 
120
  ``` cpp
121
  explicit basic_stringbuf(
122
  const basic_string<charT, traits, Allocator>& s,
123
  ios_base::openmode which = ios_base::in | ios_base::out);
124
  ```
125
 
126
+ *Effects:* Initializes the base class with `basic_streambuf()`
127
+ [[streambuf.cons]], `mode` with `which`, and `buf` with `s`, then calls
128
+ `init_buf_ptrs()`.
129
+
130
+ ``` cpp
131
+ basic_stringbuf(ios_base::openmode which, const Allocator &a);
132
+ ```
133
+
134
+ *Effects:* Initializes the base class with `basic_streambuf()`
135
+ [[streambuf.cons]], `mode` with `which`, and `buf` with `a`, then calls
136
+ `init_buf_ptrs()`.
137
+
138
+ *Ensures:* `str().empty()` is `true`.
139
+
140
+ ``` cpp
141
+ explicit basic_stringbuf(
142
+ basic_string<charT, traits, Allocator>&& s,
143
+ ios_base::openmode which = ios_base::in | ios_base::out);
144
+ ```
145
+
146
+ *Effects:* Initializes the base class with `basic_streambuf()`
147
+ [[streambuf.cons]], `mode` with `which`, and `buf` with `std::move(s)`,
148
+ then calls `init_buf_ptrs()`.
149
+
150
+ ``` cpp
151
+ template<class SAlloc>
152
+ basic_stringbuf(
153
+ const basic_string<charT, traits, SAlloc>& s,
154
+ ios_base::openmode which, const Allocator &a);
155
+ ```
156
+
157
+ *Effects:* Initializes the base class with `basic_streambuf()`
158
+ [[streambuf.cons]], `mode` with `which`, and `buf` with `{s,a}`, then
159
+ calls `init_buf_ptrs()`.
160
+
161
+ ``` cpp
162
+ template<class SAlloc>
163
+ explicit basic_stringbuf(
164
+ const basic_string<charT, traits, SAlloc>& s,
165
+ ios_base::openmode which = ios_base::in | ios_base::out);
166
+ ```
167
+
168
+ *Constraints:* `is_same_v<SAlloc,Allocator>` is `false`.
169
+
170
+ *Effects:* Initializes the base class with `basic_streambuf()`
171
+ [[streambuf.cons]], `mode` with `which`, and `buf` with `s`, then calls
172
+ `init_buf_ptrs()`.
173
 
174
  ``` cpp
175
  basic_stringbuf(basic_stringbuf&& rhs);
176
+ basic_stringbuf(basic_stringbuf&& rhs, const Allocator& a);
177
  ```
178
 
179
+ *Effects:* Copy constructs the base class from `rhs` and initializes
180
+ `mode` with `rhs.mode`. In the first form `buf` is initialized from
181
+ `std::move(rhs).str()`. In the second form `buf` is initialized from
182
+ `{std::move(rhs).str(), a}`. It is *implementation-defined* whether the
183
+ sequence pointers in `*this` (`eback()`, `gptr()`, `egptr()`, `pbase()`,
184
+ `pptr()`, `epptr()`) obtain the values which `rhs` had.
185
 
186
+ *Ensures:* Let `rhs_p` refer to the state of `rhs` just prior to this
187
+ construction and let `rhs_a` refer to the state of `rhs` just after this
188
+ construction.
189
 
190
  - `str() == rhs_p.str()`
191
  - `gptr() - eback() == rhs_p.gptr() - rhs_p.eback()`
192
  - `egptr() - eback() == rhs_p.egptr() - rhs_p.eback()`
193
  - `pptr() - pbase() == rhs_p.pptr() - rhs_p.pbase()`
 
196
  - `if (gptr()) gptr() != rhs_a.gptr()`
197
  - `if (egptr()) egptr() != rhs_a.egptr()`
198
  - `if (pbase()) pbase() != rhs_a.pbase()`
199
  - `if (pptr()) pptr() != rhs_a.pptr()`
200
  - `if (epptr()) epptr() != rhs_a.epptr()`
201
+ - `getloc() == rhs_p.getloc()`
202
+ - `rhs` is empty but usable, as if `std::move(rhs).str()` was called.
203
 
204
+ #### Assignment and swap <a id="stringbuf.assign">[[stringbuf.assign]]</a>
205
 
206
  ``` cpp
207
  basic_stringbuf& operator=(basic_stringbuf&& rhs);
208
  ```
209
 
 
212
  (see  [[stringbuf.cons]]).
213
 
214
  *Returns:* `*this`.
215
 
216
  ``` cpp
217
+ void swap(basic_stringbuf& rhs) noexcept(see below);
218
  ```
219
 
220
+ *Preconditions:*
221
+ `allocator_traits<Allocator>::propagate_on_container_swap::value` is
222
+ `true` or `get_allocator() == s.get_allocator()` is `true`.
223
+
224
  *Effects:* Exchanges the state of `*this` and `rhs`.
225
 
226
+ *Remarks:* The expression inside `noexcept` is equivalent to:
227
+ `allocator_traits<Allocator>::propagate_on_container_swap::value ||`
228
+ `allocator_traits<Allocator>::is_always_equal::value`.
229
+
230
  ``` cpp
231
  template<class charT, class traits, class Allocator>
232
  void swap(basic_stringbuf<charT, traits, Allocator>& x,
233
+ basic_stringbuf<charT, traits, Allocator>& y) noexcept(noexcept(x.swap(y)));
234
  ```
235
 
236
+ *Effects:* Equivalent to: `x.swap(y)`.
237
 
238
  #### Member functions <a id="stringbuf.members">[[stringbuf.members]]</a>
239
 
240
+ The member functions getting the underlying character sequence all refer
241
+ to a `high_mark` value, where `high_mark` represents the position one
242
+ past the highest initialized character in the buffer. Characters can be
243
+ initialized by writing to the stream, by constructing the
244
+ `basic_stringbuf` passing a `basic_string` argument, or by calling one
245
+ of the `str` member functions passing a `basic_string` as an argument.
246
+ In the latter case, all characters initialized prior to the call are now
247
+ considered uninitialized (except for those characters re-initialized by
248
+ the new `basic_string`).
249
+
250
+ ``` cpp
251
+ void init_buf_ptrs(); // exposition only
252
+ ```
253
+
254
+ *Effects:* Initializes the input and output sequences from `buf`
255
+ according to `mode`.
256
+
257
+ *Ensures:*
258
+
259
+ - If `ios_base::out` is set in `mode`, `pbase()` points to `buf.front()`
260
+ and `epptr() >= pbase() + buf.size()` is `true`;
261
+ - in addition, if `ios_base::ate` is set in `mode`,
262
+ `pptr() == pbase() + buf.size()` is `true`,
263
+ - otherwise `pptr() == pbase()` is `true`.
264
+ - If `ios_base::in` is set in `mode`, `eback()` points to `buf.front()`,
265
+ and `(gptr() == eback() && egptr() == eback() + buf.size())` is
266
+ `true`.
267
+
268
+ [*Note 1*: For efficiency reasons, stream buffer operations might
269
+ violate invariants of `buf` while it is held encapsulated in the
270
+ `basic_stringbuf`, e.g., by writing to characters in the range
271
+ \[`buf.data() + buf.size()`, `buf.data() + buf.capacity()`). All
272
+ operations retrieving a `basic_string` from `buf` ensure that the
273
+ `basic_string` invariants hold on the returned value. — *end note*]
274
+
275
+ ``` cpp
276
+ allocator_type get_allocator() const noexcept;
277
+ ```
278
+
279
+ *Returns:* `buf.get_allocator()`.
280
+
281
+ ``` cpp
282
+ basic_string<charT, traits, Allocator> str() const &;
283
+ ```
284
+
285
+ *Effects:* Equivalent to:
286
+
287
+ ``` cpp
288
+ return basic_string<charT, traits, Allocator>(view(), get_allocator());
289
+ ```
290
+
291
  ``` cpp
292
+ template<class SAlloc>
293
+ basic_string<charT, traits, SAlloc> str(const SAlloc& sa) const;
294
+ ```
295
+
296
+ *Constraints:* `SAlloc` is a type that qualifies as an
297
+ allocator [[container.requirements.general]].
298
+
299
+ *Effects:* Equivalent to:
300
+
301
+ ``` cpp
302
+ return basic_string<charT, traits, SAlloc>(view(), sa);
303
+ ```
304
+
305
+ ``` cpp
306
+ basic_string<charT, traits, Allocator> str() &&;
307
+ ```
308
+
309
+ *Returns:* A `basic_string<charT, traits, Allocator>` object move
310
+ constructed from the `basic_stringbuf`’s underlying character sequence
311
+ in `buf`. This can be achieved by first adjusting `buf` to have the same
312
+ content as `view()`.
313
+
314
+ *Ensures:* The underlying character sequence `buf` is empty and
315
+ `pbase()`, `pptr()`, `epptr()`, `eback()`, `gptr()`, and `egptr()` are
316
+ initialized as if by calling `init_buf_ptrs()` with an empty `buf`.
317
+
318
+ ``` cpp
319
+ basic_string_view<charT, traits> view() const noexcept;
320
+ ```
321
+
322
+ Let `sv` be `basic_string_view<charT, traits>`.
323
+
324
+ *Returns:* A `sv` object referring to the `basic_stringbuf`’s underlying
325
+ character sequence in `buf`:
326
+
327
+ - If `ios_base::out` is set in `mode`, then
328
+ `sv(pbase(), high_mark-pbase())` is returned.
329
+ - Otherwise, if `ios_base::in` is set in `mode`, then
330
+ `sv(eback(), egptr()-eback())` is returned.
331
+ - Otherwise, `sv()` is returned.
332
+
333
+ [*Note 2*: Using the returned `sv` object after destruction or
334
+ invalidation of the character sequence underlying `*this` is undefined
335
+ behavior, unless `sv.empty()` is `true`. — *end note*]
336
 
337
  ``` cpp
338
  void str(const basic_string<charT, traits, Allocator>& s);
339
  ```
340
 
341
+ *Effects:* Equivalent to:
342
+
343
+ ``` cpp
344
+ buf = s;
345
+ init_buf_ptrs();
346
+ ```
347
+
348
+ ``` cpp
349
+ template<class SAlloc>
350
+ void str(const basic_string<charT, traits, SAlloc>& s);
351
+ ```
352
+
353
+ *Constraints:* `is_same_v<SAlloc,Allocator>` is `false`.
354
+
355
+ *Effects:* Equivalent to:
356
+
357
+ ``` cpp
358
+ buf = s;
359
+ init_buf_ptrs();
360
+ ```
361
+
362
+ ``` cpp
363
+ void str(basic_string<charT, traits, Allocator>&& s);
364
+ ```
365
+
366
+ *Effects:* Equivalent to:
367
+
368
+ ``` cpp
369
+ buf = std::move(s);
370
+ init_buf_ptrs();
371
+ ```
372
 
373
  #### Overridden virtual functions <a id="stringbuf.virtuals">[[stringbuf.virtuals]]</a>
374
 
375
  ``` cpp
376
  int_type underflow() override;
 
397
  `ios_base::out` is nonzero, assigns `c` to `*``gptr()`. Returns: `c`.
398
  - If `traits::eq_int_type(c, traits::eof())` returns `true` and if the
399
  input sequence has a putback position available, assigns `gptr() - 1`
400
  to `gptr()`. Returns: `traits::not_eof(c)`.
401
 
402
+ *Returns:* As specified above, or `traits::eof()` to indicate failure.
403
 
404
  *Remarks:* If the function can succeed in more than one of these ways,
405
  it is unspecified which way is chosen.
406
 
407
  ``` cpp
 
420
  `traits::eof()`.
421
 
422
  *Remarks:* The function can alter the number of write positions
423
  available as a result of any call.
424
 
425
+ *Returns:* As specified above, or `traits::eof()` to indicate failure.
426
 
427
+ The function can make a write position available only if `ios_base::out`
428
+ is set in `mode`. To make a write position available, the function
429
+ reallocates (or initially allocates) an array object with a sufficient
430
+ number of elements to hold the current array object (if any), plus at
431
+ least one additional write position. If `ios_base::in` is set in `mode`,
432
+ the function alters the read end pointer `egptr()` to point just past
433
+ the new write position.
434
 
435
  ``` cpp
436
  pos_type seekoff(off_type off, ios_base::seekdir way,
437
  ios_base::openmode which
438
  = ios_base::in | ios_base::out) override;
439
  ```
440
 
441
  *Effects:* Alters the stream position within one of the controlled
442
+ sequences, if possible, as indicated in [[stringbuf.seekoff.pos]].
 
443
 
444
+ **Table: `seekoff` positioning** <a id="stringbuf.seekoff.pos">[stringbuf.seekoff.pos]</a>
445
 
446
  | Conditions | Result |
447
+ | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
448
+ | `ios_base::in` is set in `which` | positions the input sequence |
449
+ | `ios_base::out` is set in `which` | positions the output sequence |
450
+ | both `ios_base::in` and `ios_base::out` are set in `which` and either<br> `way == ios_base::beg` or<br> `way == ios_base::end` | positions both the input and the output sequences |
451
  | Otherwise | the positioning operation fails. |
452
 
453
 
454
+ For a sequence to be positioned, the function determines `newoff` as
455
+ indicated in [[stringbuf.seekoff.newoff]]. If the sequence’s next
456
+ pointer (either `gptr()` or `pptr()`) is a null pointer and `newoff` is
457
+ nonzero, the positioning operation fails.
458
 
459
+ **Table: `newoff` values** <a id="stringbuf.seekoff.newoff">[stringbuf.seekoff.newoff]</a>
460
 
461
  | Condition | `newoff` Value |
462
  | ---------------------- | ----------------------------------------------------------------------- |
463
  | `way == ios_base::beg` | 0 |
464
  | `way == ios_base::cur` | the next pointer minus the beginning pointer (`xnext - xbeg`). |
465
  | `way == ios_base::end` | the high mark pointer minus the beginning pointer (`high_mark - xbeg`). |
466
 
467
 
468
  If `(newoff + off) < 0`, or if `newoff + off` refers to an uninitialized
469
+ character [[stringbuf.members]], the positioning operation fails.
470
  Otherwise, the function assigns `xbeg + newoff + off` to the next
471
  pointer `xnext`.
472
 
473
  *Returns:* `pos_type(newoff)`, constructed from the resultant offset
474
  `newoff` (of type `off_type`), that stores the resultant stream