From Jason Turner

[depr.strstreambuf]

C++14 → C++17 11.5 KB 117 lines
Current Draft | LaTeX Source
Archived: C++14 | C++17
Markdown: C++14 | C++17
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpte9zf0dh/{from.md → to.md} +76 -28
tmp/tmpte9zf0dh/{from.md → to.md} RENAMED
@@ -21,22 +21,23 @@ namespace std {
21
  void freeze(bool freezefl = true);
22
  char* str();
23
  int pcount();
24
 
25
  protected:
26
- virtual int_type overflow (int_type c = EOF);
27
- virtual int_type pbackfail(int_type c = EOF);
28
- virtual int_type underflow();
29
- virtual pos_type seekoff(off_type off, ios_base::seekdir way,
30
  ios_base::openmode which
31
- = ios_base::in | ios_base::out);
32
- virtual pos_type seekpos(pos_type sp, ios_base::openmode which
33
- = ios_base::in | ios_base::out);
34
- virtual streambuf* setbuf(char* s, streamsize n);
 
35
 
36
  private:
37
- typedef T1 strstate; // exposition only
38
  static const strstate allocated; // exposition only
39
  static const strstate constant; // exposition only
40
  static const strstate dynamic; // exposition only
41
  static const strstate frozen; // exposition only
42
  strstate strmode; // exposition only
@@ -50,10 +51,12 @@ namespace std {
50
  The class `strstreambuf` associates the input sequence, and possibly the
51
  output sequence, with an object of some *character* array type, whose
52
  elements store arbitrary values. The array object has several
53
  attributes.
54
 
 
 
55
  For the sake of exposition, these are represented as elements of a
56
  bitmask type (indicated here as `T1`) called `strstate`. The elements
57
  are:
58
 
59
  - `allocated`, set when a dynamic array object has been allocated, and
@@ -63,20 +66,26 @@ are:
63
  - `dynamic`, set when the array object is allocated (or reallocated) as
64
  necessary to hold a character sequence that can change in length;
65
  - `frozen`, set when the program has requested that the array object not
66
  be altered, reallocated, or freed.
67
 
 
 
 
 
68
  For the sake of exposition, the maintained data is presented here as:
69
 
70
  - `strstate strmode`, the attributes of the array object associated with
71
  the `strstreambuf` object;
72
  - `int alsize`, the suggested minimum size for a dynamic array object;
73
  - `void* (*palloc)(size_t)`, points to the function to call to allocate
74
  a dynamic array object;
75
  - `void (*pfree)(void*)`, points to the function to call to free a
76
  dynamic array object.
77
 
 
 
78
  Each object of class `strstreambuf` has a *seekable area*, delimited by
79
  the pointers `seeklow` and `seekhigh`. If `gnext` is a null pointer, the
80
  seekable area is undefined. Otherwise, `seeklow` equals `gbeg` and
81
  `seekhigh` is either `pend`, if `pend` is not a null pointer, or `gend`.
82
 
@@ -122,32 +131,71 @@ strstreambuf(signed char* gnext_arg, streamsize n,
122
  signed char* pbeg_arg = 0);
123
  strstreambuf(unsigned char* gnext_arg, streamsize n,
124
  unsigned char* pbeg_arg = 0);
125
  ```
126
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
127
  ``` cpp
128
  setg(gnext_arg, gnext_arg, gnext_arg + N);
129
  ```
130
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
131
  ``` cpp
132
  virtual ~strstreambuf();
133
  ```
134
 
135
  *Effects:* Destroys an object of class `strstreambuf`. The function
136
  frees the dynamically allocated array object only if
137
- `strmode & allocated != 0` and
138
- `strmode & frozen == 0`. ([[depr.strstreambuf.virtuals]] describes how
139
- a dynamically allocated array object is freed.)
140
 
141
  #### Member functions <a id="depr.strstreambuf.members">[[depr.strstreambuf.members]]</a>
142
 
143
  ``` cpp
144
  void freeze(bool freezefl = true);
145
  ```
146
 
147
- *Effects:* If `strmode` & `dynamic` is non-zero, alters the freeze
148
- status of the dynamic array object as follows:
149
 
150
  - If `freezefl` is `true`, the function sets `frozen` in `strmode`.
151
  - Otherwise, it clears `frozen` in `strmode`.
152
 
153
  ``` cpp
@@ -164,16 +212,16 @@ int pcount() const;
164
  ```
165
 
166
  *Effects:* If the next pointer for the output sequence, `pnext`, is a
167
  null pointer, returns zero. Otherwise, returns the current effective
168
  length of the array object as the next pointer minus the beginning
169
- pointer for the output sequence, `pnext` - `pbeg`.
170
 
171
  #### `strstreambuf` overridden virtual functions <a id="depr.strstreambuf.virtuals">[[depr.strstreambuf.virtuals]]</a>
172
 
173
  ``` cpp
174
- int_type overflow(int_type c = EOF);
175
  ```
176
 
177
  *Effects:* Appends the character designated by `c` to the output
178
  sequence, if possible, in one of two ways:
179
 
@@ -191,36 +239,36 @@ available as a result of any call.
191
 
192
  To make a write position available, the function reallocates (or
193
  initially allocates) an array object with a sufficient number of
194
  elements `n` to hold the current array object (if any), plus at least
195
  one additional write position. How many additional write positions are
196
- made available is otherwise unspecified. [^1] If `palloc` is not a null
197
  pointer, the function calls `(*palloc)(n)` to allocate the new dynamic
198
  array object. Otherwise, it evaluates the expression `new charT[n]`. In
199
  either case, if the allocation fails, the function returns `EOF`.
200
  Otherwise, it sets `allocated` in `strmode`.
201
 
202
  To free a previously existing dynamic array object whose first element
203
  address is `p`: If `pfree` is not a null pointer, the function calls
204
  `(*pfree)(p)`. Otherwise, it evaluates the expression `delete[]p`.
205
 
206
- If `strmode & dynamic == 0`, or if `strmode & frozen != 0`, the function
207
- cannot extend the array (reallocate it with greater length) to make a
208
- write position available.
209
 
210
  ``` cpp
211
- int_type pbackfail(int_type c = EOF);
212
  ```
213
 
214
  Puts back the character designated by `c` to the input sequence, if
215
  possible, in one of three ways:
216
 
217
  - If `c != EOF`, if the input sequence has a putback position available,
218
  and if `(char)c == gnext[-1]`, assigns `gnext - 1` to `gnext`. Returns
219
  `c`.
220
  - If `c != EOF`, if the input sequence has a putback position available,
221
- and if `strmode` & `constant` is zero, assigns `c` to `*`\dcr`gnext`.
222
  Returns `c`.
223
  - If `c == EOF` and if the input sequence has a putback position
224
  available, assigns `gnext - 1` to `gnext`. Returns a value other than
225
  `EOF`.
226
 
@@ -229,11 +277,11 @@ Returns `EOF` to indicate failure.
229
  *Remarks:* If the function can succeed in more than one of these ways,
230
  it is unspecified which way is chosen. The function can alter the number
231
  of putback positions available as a result of any call.
232
 
233
  ``` cpp
234
- int_type underflow();
235
  ```
236
 
237
  *Effects:* Reads a character from the *input sequence*, if possible,
238
  without moving the stream position past it, as follows:
239
 
@@ -241,19 +289,19 @@ without moving the stream position past it, as follows:
241
  signals success by returning `(unsigned char)*gnext`.
242
  - Otherwise, if the current write next pointer `pnext` is not a null
243
  pointer and is greater than the current read end pointer `gend`, makes
244
  a *read position* available by assigning to `gend` a value greater
245
  than `gnext` and no greater than `pnext`. Returns
246
- `(unsigned char*)gnext`.
247
 
248
  Returns `EOF` to indicate failure.
249
 
250
  *Remarks:* The function can alter the number of read positions available
251
  as a result of any call.
252
 
253
  ``` cpp
254
- pos_type seekoff(off_type off, seekdir way, openmode which = in | out);
255
  ```
256
 
257
  *Effects:* Alters the stream position within one of the controlled
258
  sequences, if possible, as indicated in
259
  Table  [[tab:future.seekoff.positioning]].
@@ -292,11 +340,11 @@ position, if possible. If the positioning operation fails, or if the
292
  constructed object cannot represent the resultant stream position, the
293
  return value is `pos_type(off_type(-1))`.
294
 
295
  ``` cpp
296
  pos_type seekpos(pos_type sp, ios_base::openmode which
297
- = ios_base::in | ios_base::out);
298
  ```
299
 
300
  *Effects:* Alters the stream position within one of the controlled
301
  sequences, if possible, to correspond to the stream position stored in
302
  `sp` (as described below).
@@ -309,11 +357,11 @@ sequences, if possible, to correspond to the stream position stored in
309
  For a sequence to be positioned, if its next pointer is a null pointer,
310
  the positioning operation fails. Otherwise, the function determines
311
  `newoff` from `sp.offset()`:
312
 
313
  - If `newoff` is an invalid stream position, has a negative value, or
314
- has a value greater than (`seekhigh` - `seeklow`), the positioning
315
  operation fails
316
  - Otherwise, the function adds `newoff` to the beginning pointer `xbeg`
317
  and stores the result in the next pointer `xnext`.
318
 
319
  *Returns:* `pos_type(newoff)`, constructed from the resultant offset
@@ -321,11 +369,11 @@ the positioning operation fails. Otherwise, the function determines
321
  position, if possible. If the positioning operation fails, or if the
322
  constructed object cannot represent the resultant stream position, the
323
  return value is `pos_type(off_type(-1))`.
324
 
325
  ``` cpp
326
- streambuf<char>* setbuf(char* s, streamsize n);
327
  ```
328
 
329
  *Effects:* Implementation defined, except that `setbuf(0, 0)` has no
330
  effect.
331
 
 
21
  void freeze(bool freezefl = true);
22
  char* str();
23
  int pcount();
24
 
25
  protected:
26
+ int_type overflow (int_type c = EOF) override;
27
+ int_type pbackfail(int_type c = EOF) override;
28
+ int_type underflow() override;
29
+ pos_type seekoff(off_type off, ios_base::seekdir way,
30
  ios_base::openmode which
31
+ = ios_base::in | ios_base::out) override;
32
+ pos_type seekpos(pos_type sp,
33
+ ios_base::openmode which
34
+ = ios_base::in | ios_base::out) override;
35
+ streambuf* setbuf(char* s, streamsize n) override;
36
 
37
  private:
38
+ using strstate = T1; // exposition only
39
  static const strstate allocated; // exposition only
40
  static const strstate constant; // exposition only
41
  static const strstate dynamic; // exposition only
42
  static const strstate frozen; // exposition only
43
  strstate strmode; // exposition only
 
51
  The class `strstreambuf` associates the input sequence, and possibly the
52
  output sequence, with an object of some *character* array type, whose
53
  elements store arbitrary values. The array object has several
54
  attributes.
55
 
56
+ [*Note 1*:
57
+
58
  For the sake of exposition, these are represented as elements of a
59
  bitmask type (indicated here as `T1`) called `strstate`. The elements
60
  are:
61
 
62
  - `allocated`, set when a dynamic array object has been allocated, and
 
66
  - `dynamic`, set when the array object is allocated (or reallocated) as
67
  necessary to hold a character sequence that can change in length;
68
  - `frozen`, set when the program has requested that the array object not
69
  be altered, reallocated, or freed.
70
 
71
+ — *end note*]
72
+
73
+ [*Note 2*:
74
+
75
  For the sake of exposition, the maintained data is presented here as:
76
 
77
  - `strstate strmode`, the attributes of the array object associated with
78
  the `strstreambuf` object;
79
  - `int alsize`, the suggested minimum size for a dynamic array object;
80
  - `void* (*palloc)(size_t)`, points to the function to call to allocate
81
  a dynamic array object;
82
  - `void (*pfree)(void*)`, points to the function to call to free a
83
  dynamic array object.
84
 
85
+ — *end note*]
86
+
87
  Each object of class `strstreambuf` has a *seekable area*, delimited by
88
  the pointers `seeklow` and `seekhigh`. If `gnext` is a null pointer, the
89
  seekable area is undefined. Otherwise, `seeklow` equals `gbeg` and
90
  `seekhigh` is either `pend`, if `pend` is not a null pointer, or `gend`.
91
 
 
131
  signed char* pbeg_arg = 0);
132
  strstreambuf(unsigned char* gnext_arg, streamsize n,
133
  unsigned char* pbeg_arg = 0);
134
  ```
135
 
136
+ *Effects:* Constructs an object of class `strstreambuf`, initializing
137
+ the base class with `streambuf()`. The postconditions of this function
138
+ are indicated in Table  [[tab:future.strstreambuf2.effects]].
139
+
140
+ **Table: `strstreambuf(charT*, streamsize, charT*)` effects** <a id="tab:future.strstreambuf2.effects">[tab:future.strstreambuf2.effects]</a>
141
+
142
+ | Element | Value |
143
+ | --------- | -------------------- |
144
+ | `strmode` | 0 |
145
+ | `alsize` | an unspecified value |
146
+ | `palloc` | a null pointer |
147
+ | `pfree` | a null pointer |
148
+
149
+
150
+ `gnext_arg` shall point to the first element of an array object whose
151
+ number of elements `N` is determined as follows:
152
+
153
+ - If `n > 0`, `N` is `n`.
154
+ - If `n == 0`, `N` is `std::strlen(gnext_arg)`.
155
+ - If `n < 0`, `N` is `INT_MAX`.[^1]
156
+
157
+ If `pbeg_arg` is a null pointer, the function executes:
158
+
159
  ``` cpp
160
  setg(gnext_arg, gnext_arg, gnext_arg + N);
161
  ```
162
 
163
+ Otherwise, the function executes:
164
+
165
+ ``` cpp
166
+ setg(gnext_arg, gnext_arg, pbeg_arg);
167
+ setp(pbeg_arg, pbeg_arg + N);
168
+ ```
169
+
170
+ ``` cpp
171
+ strstreambuf(const char* gnext_arg, streamsize n);
172
+ strstreambuf(const signed char* gnext_arg, streamsize n);
173
+ strstreambuf(const unsigned char* gnext_arg, streamsize n);
174
+ ```
175
+
176
+ *Effects:* Behaves the same as `strstreambuf((char*)gnext_arg,n)`,
177
+ except that the constructor also sets `constant` in `strmode`.
178
+
179
  ``` cpp
180
  virtual ~strstreambuf();
181
  ```
182
 
183
  *Effects:* Destroys an object of class `strstreambuf`. The function
184
  frees the dynamically allocated array object only if
185
+ `(strmode & allocated) != 0` and
186
+ `(strmode & frozen) == 0`. ([[depr.strstreambuf.virtuals]] describes
187
+ how a dynamically allocated array object is freed.)
188
 
189
  #### Member functions <a id="depr.strstreambuf.members">[[depr.strstreambuf.members]]</a>
190
 
191
  ``` cpp
192
  void freeze(bool freezefl = true);
193
  ```
194
 
195
+ *Effects:* If `strmode & dynamic` is nonzero, alters the freeze status
196
+ of the dynamic array object as follows:
197
 
198
  - If `freezefl` is `true`, the function sets `frozen` in `strmode`.
199
  - Otherwise, it clears `frozen` in `strmode`.
200
 
201
  ``` cpp
 
212
  ```
213
 
214
  *Effects:* If the next pointer for the output sequence, `pnext`, is a
215
  null pointer, returns zero. Otherwise, returns the current effective
216
  length of the array object as the next pointer minus the beginning
217
+ pointer for the output sequence, `pnext - pbeg`.
218
 
219
  #### `strstreambuf` overridden virtual functions <a id="depr.strstreambuf.virtuals">[[depr.strstreambuf.virtuals]]</a>
220
 
221
  ``` cpp
222
+ int_type overflow(int_type c = EOF) override;
223
  ```
224
 
225
  *Effects:* Appends the character designated by `c` to the output
226
  sequence, if possible, in one of two ways:
227
 
 
239
 
240
  To make a write position available, the function reallocates (or
241
  initially allocates) an array object with a sufficient number of
242
  elements `n` to hold the current array object (if any), plus at least
243
  one additional write position. How many additional write positions are
244
+ made available is otherwise unspecified. [^2] If `palloc` is not a null
245
  pointer, the function calls `(*palloc)(n)` to allocate the new dynamic
246
  array object. Otherwise, it evaluates the expression `new charT[n]`. In
247
  either case, if the allocation fails, the function returns `EOF`.
248
  Otherwise, it sets `allocated` in `strmode`.
249
 
250
  To free a previously existing dynamic array object whose first element
251
  address is `p`: If `pfree` is not a null pointer, the function calls
252
  `(*pfree)(p)`. Otherwise, it evaluates the expression `delete[]p`.
253
 
254
+ If `(strmode & dynamic) == 0`, or if `(strmode & frozen) != 0`, the
255
+ function cannot extend the array (reallocate it with greater length) to
256
+ make a write position available.
257
 
258
  ``` cpp
259
+ int_type pbackfail(int_type c = EOF) override;
260
  ```
261
 
262
  Puts back the character designated by `c` to the input sequence, if
263
  possible, in one of three ways:
264
 
265
  - If `c != EOF`, if the input sequence has a putback position available,
266
  and if `(char)c == gnext[-1]`, assigns `gnext - 1` to `gnext`. Returns
267
  `c`.
268
  - If `c != EOF`, if the input sequence has a putback position available,
269
+ and if `strmode & constant` is zero, assigns `c` to `*`\dcr`gnext`.
270
  Returns `c`.
271
  - If `c == EOF` and if the input sequence has a putback position
272
  available, assigns `gnext - 1` to `gnext`. Returns a value other than
273
  `EOF`.
274
 
 
277
  *Remarks:* If the function can succeed in more than one of these ways,
278
  it is unspecified which way is chosen. The function can alter the number
279
  of putback positions available as a result of any call.
280
 
281
  ``` cpp
282
+ int_type underflow() override;
283
  ```
284
 
285
  *Effects:* Reads a character from the *input sequence*, if possible,
286
  without moving the stream position past it, as follows:
287
 
 
289
  signals success by returning `(unsigned char)*gnext`.
290
  - Otherwise, if the current write next pointer `pnext` is not a null
291
  pointer and is greater than the current read end pointer `gend`, makes
292
  a *read position* available by assigning to `gend` a value greater
293
  than `gnext` and no greater than `pnext`. Returns
294
+ `(unsigned char)*gnext`.
295
 
296
  Returns `EOF` to indicate failure.
297
 
298
  *Remarks:* The function can alter the number of read positions available
299
  as a result of any call.
300
 
301
  ``` cpp
302
+ pos_type seekoff(off_type off, seekdir way, openmode which = in | out) override;
303
  ```
304
 
305
  *Effects:* Alters the stream position within one of the controlled
306
  sequences, if possible, as indicated in
307
  Table  [[tab:future.seekoff.positioning]].
 
340
  constructed object cannot represent the resultant stream position, the
341
  return value is `pos_type(off_type(-1))`.
342
 
343
  ``` cpp
344
  pos_type seekpos(pos_type sp, ios_base::openmode which
345
+ = ios_base::in | ios_base::out) override;
346
  ```
347
 
348
  *Effects:* Alters the stream position within one of the controlled
349
  sequences, if possible, to correspond to the stream position stored in
350
  `sp` (as described below).
 
357
  For a sequence to be positioned, if its next pointer is a null pointer,
358
  the positioning operation fails. Otherwise, the function determines
359
  `newoff` from `sp.offset()`:
360
 
361
  - If `newoff` is an invalid stream position, has a negative value, or
362
+ has a value greater than (`seekhigh - seeklow`), the positioning
363
  operation fails
364
  - Otherwise, the function adds `newoff` to the beginning pointer `xbeg`
365
  and stores the result in the next pointer `xnext`.
366
 
367
  *Returns:* `pos_type(newoff)`, constructed from the resultant offset
 
369
  position, if possible. If the positioning operation fails, or if the
370
  constructed object cannot represent the resultant stream position, the
371
  return value is `pos_type(off_type(-1))`.
372
 
373
  ``` cpp
374
+ streambuf<char>* setbuf(char* s, streamsize n) override;
375
  ```
376
 
377
  *Effects:* Implementation defined, except that `setbuf(0, 0)` has no
378
  effect.
379