From Jason Turner

[streambuf]

C++14 → C++17 13.5 KB 161 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/tmpo2d5p4kl/{from.md → to.md} +92 -58
tmp/tmpo2d5p4kl/{from.md → to.md} RENAMED
@@ -1,118 +1,116 @@
1
- ### Class template `basic_streambuf<charT,traits>` <a id="streambuf">[[streambuf]]</a>
2
 
3
  ``` cpp
4
  namespace std {
5
  template <class charT, class traits = char_traits<charT>>
6
  class basic_streambuf {
7
  public:
8
-
9
- // types:
10
- typedef charT char_type;
11
- typedef typename traits::int_type int_type;
12
- typedef typename traits::pos_type pos_type;
13
- typedef typename traits::off_type off_type;
14
- typedef traits traits_type;
15
 
16
  virtual ~basic_streambuf();
17
 
18
- // [streambuf.locales] locales:
19
  locale pubimbue(const locale& loc);
20
  locale getloc() const;
21
 
22
- // [streambuf.buffer] buffer and positioning:
23
- basic_streambuf<char_type,traits>*
24
- pubsetbuf(char_type* s, streamsize n);
25
  pos_type pubseekoff(off_type off, ios_base::seekdir way,
26
- ios_base::openmode which =
27
- ios_base::in | ios_base::out);
28
  pos_type pubseekpos(pos_type sp,
29
- ios_base::openmode which =
30
- ios_base::in | ios_base::out);
31
  int pubsync();
32
 
33
- // Get and put areas:
34
- // [streambuf.pub.get] Get area:
35
  streamsize in_avail();
36
  int_type snextc();
37
  int_type sbumpc();
38
  int_type sgetc();
39
  streamsize sgetn(char_type* s, streamsize n);
40
 
41
- // [streambuf.pub.pback] Putback:
42
  int_type sputbackc(char_type c);
43
  int_type sungetc();
44
 
45
- // [streambuf.pub.put] Put area:
46
  int_type sputc(char_type c);
47
  streamsize sputn(const char_type* s, streamsize n);
48
 
49
  protected:
50
  basic_streambuf();
51
  basic_streambuf(const basic_streambuf& rhs);
52
  basic_streambuf& operator=(const basic_streambuf& rhs);
53
 
54
  void swap(basic_streambuf& rhs);
55
 
56
- // [streambuf.get.area] Get area:
57
  char_type* eback() const;
58
  char_type* gptr() const;
59
  char_type* egptr() const;
60
  void gbump(int n);
61
  void setg(char_type* gbeg, char_type* gnext, char_type* gend);
62
 
63
- // [streambuf.put.area] Put area:
64
  char_type* pbase() const;
65
  char_type* pptr() const;
66
  char_type* epptr() const;
67
  void pbump(int n);
68
  void setp(char_type* pbeg, char_type* pend);
69
 
70
- // [streambuf.virtuals] virtual functions:
71
- // [streambuf.virt.locales] Locales:
72
  virtual void imbue(const locale& loc);
73
 
74
- // [streambuf.virt.buffer] Buffer management and positioning:
75
- virtual basic_streambuf<char_type,traits>*
76
- setbuf(char_type* s, streamsize n);
77
  virtual pos_type seekoff(off_type off, ios_base::seekdir way,
78
- ios_base::openmode which = ios_base::in | ios_base::out);
 
79
  virtual pos_type seekpos(pos_type sp,
80
- ios_base::openmode which = ios_base::in | ios_base::out);
 
81
  virtual int sync();
82
 
83
- // [streambuf.virt.get] Get area:
84
  virtual streamsize showmanyc();
85
  virtual streamsize xsgetn(char_type* s, streamsize n);
86
  virtual int_type underflow();
87
  virtual int_type uflow();
88
 
89
- // [streambuf.virt.pback] Putback:
90
  virtual int_type pbackfail(int_type c = traits::eof());
91
 
92
- // [streambuf.virt.put] Put area:
93
  virtual streamsize xsputn(const char_type* s, streamsize n);
94
  virtual int_type overflow(int_type c = traits::eof());
95
  };
96
  }
97
  ```
98
 
99
- The class template `basic_streambuf<charT,traits>` serves as an abstract
100
- base class for deriving various *stream buffers* whose objects each
101
- control two *character sequences*:
102
 
103
  - a character *input sequence*;
104
  - a character *output sequence*.
105
 
106
  #### `basic_streambuf` constructors <a id="streambuf.cons">[[streambuf.cons]]</a>
107
 
108
  ``` cpp
109
  basic_streambuf();
110
  ```
111
 
112
- *Effects:* Constructs an object of class `basic_streambuf<charT,traits>`
113
- and initializes:[^13]
114
 
115
  - all its pointer member objects to null pointers,
116
  - the `getloc()` member to a copy the global locale, `locale()`, at the
117
  time of construction.
118
 
@@ -148,11 +146,11 @@ basic_streambuf(const basic_streambuf& rhs);
148
 
149
  ``` cpp
150
  locale pubimbue(const locale& loc);
151
  ```
152
 
153
- `loc == getloc()`.
154
 
155
  *Effects:* Calls `imbue(loc)`.
156
 
157
  *Returns:* Previous value of `getloc()`.
158
 
@@ -167,25 +165,27 @@ been called but before `pubimbue` has returned (i.e., from within the
167
  call of `imbue()`) then it returns the previous value.
168
 
169
  ##### Buffer management and positioning <a id="streambuf.buffer">[[streambuf.buffer]]</a>
170
 
171
  ``` cpp
172
- basic_streambuf<char_type,traits>* pubsetbuf(char_type* s, streamsize n);
173
  ```
174
 
175
  *Returns:* `setbuf(s, n)`.
176
 
177
  ``` cpp
178
  pos_type pubseekoff(off_type off, ios_base::seekdir way,
179
- ios_base::openmode which = ios_base::in | ios_base::out);
 
180
  ```
181
 
182
  *Returns:* `seekoff(off, way, which)`.
183
 
184
  ``` cpp
185
  pos_type pubseekpos(pos_type sp,
186
- ios_base::openmode which = ios_base::in | ios_base::out);
 
187
  ```
188
 
189
  *Returns:* `seekpos(sp, which)`.
190
 
191
  ``` cpp
@@ -238,11 +238,11 @@ streamsize sgetn(char_type* s, streamsize n);
238
  ``` cpp
239
  int_type sputbackc(char_type c);
240
  ```
241
 
242
  *Returns:* If the input sequence putback position is not available, or
243
- if `traits::eq(c,gptr()[-1])` is false, returns
244
  `pbackfail(traits::to_int_type(c))`. Otherwise, decrements the next
245
  pointer for the input sequence and returns
246
  `traits::to_int_type(*gptr())`.
247
 
248
  ``` cpp
@@ -426,12 +426,12 @@ int sync();
426
  *Effects:* Synchronizes the controlled sequences with the arrays. That
427
  is, if `pbase()` is non-null the characters between `pbase()` and
428
  `pptr()` are written to the controlled sequence. The pointers may then
429
  be reset as appropriate.
430
 
431
- *Returns:* -1 on failure. What constitutes failure is determined by each
432
- derived class ([[filebuf.virtuals]]).
433
 
434
  *Default behavior:* Returns zero.
435
 
436
  ##### Get area <a id="streambuf.virt.get">[[streambuf.virt.get]]</a>
437
 
@@ -475,22 +475,38 @@ function only if `gptr()` is null or `gptr() >= egptr()`
475
  *Returns:* `traits::to_int_type(c)`, where `c` is the first *character*
476
  of the *pending sequence*, without moving the input sequence position
477
  past it. If the pending sequence is null then the function returns
478
  `traits::eof()` to indicate failure.
479
 
480
- The *pending sequence* of characters is defined as the concatenation of:
481
 
482
- The *result character* is
 
 
 
483
 
484
- The *backup sequence* is defined as the concatenation of:
 
 
485
 
486
- *Effects:* The function sets up the `gptr()` and `egptr()` satisfying
487
- one of:
 
 
 
 
 
488
 
489
  If `eback()` and `gptr()` are non-null then the function is not
490
  constrained as to their contents, but the “usual backup condition” is
491
- that either:
 
 
 
 
 
 
492
 
493
  *Default behavior:* Returns `traits::eof()`.
494
 
495
  ``` cpp
496
  int_type uflow();
@@ -523,16 +539,16 @@ The *pending sequence* is defined as for `underflow()`, with the
523
  modifications that
524
 
525
  - If `traits::eq_int_type(c, traits::eof())` returns `true`, then the
526
  input sequence is backed up one character before the pending sequence
527
  is determined.
528
- - If `traits::eq_int_type(c,traits::eof())` returns `false`, then `c` is
529
- prepended. Whether the input sequence is backed up or modified in any
530
- other way is unspecified.
531
 
532
- On return, the constraints of `gptr()`, `eback()`, and `pptr()` are the
533
- same as for `underflow()`.
534
 
535
  *Returns:* `traits::eof()` to indicate failure. Failure may occur
536
  because the input sequence could not be backed up, or if for some other
537
  reason the pointers could not be set consistent with the constraints.
538
  `pbackfail()` is called only when put back has really failed.
@@ -549,13 +565,13 @@ streamsize xsputn(const char_type* s, streamsize n);
549
 
550
  *Effects:* Writes up to `n` characters to the output sequence as if by
551
  repeated calls to `sputc(c)`. The characters written are obtained from
552
  successive elements of the array whose first element is designated by
553
  `s`. Writing stops when either `n` characters have been written or a
554
- call to `sputc(c)` would return `traits::eof()`. Is is unspecified
555
  whether the function calls `overflow()` when `pptr() == epptr()` becomes
556
- true or whether it achieves the same effects by other means.
557
 
558
  *Returns:* The number of characters written.
559
 
560
  ``` cpp
561
  int_type overflow(int_type c = traits::eof());
@@ -563,19 +579,37 @@ int_type overflow(int_type c = traits::eof());
563
 
564
  *Effects:* Consumes some initial subsequence of the characters of the
565
  *pending sequence*. The pending sequence is defined as the concatenation
566
  of
567
 
 
 
 
 
 
568
  *Remarks:* The member functions `sputc()` and `sputn()` call this
569
  function in case that no room can be found in the put buffer enough to
570
  accommodate the argument character sequence.
571
 
572
  *Requires:* Every overriding definition of this virtual function shall
573
  obey the following constraints:
574
 
 
 
 
 
 
 
 
 
 
 
 
 
 
575
  *Returns:* `traits::eof()` or throws an exception if the function fails.
576
 
577
  Otherwise, returns some value other than `traits::eof()` to indicate
578
- success.[^16]
579
 
580
  *Default behavior:* Returns `traits::eof()`.
581
 
 
1
+ ### Class template `basic_streambuf` <a id="streambuf">[[streambuf]]</a>
2
 
3
  ``` cpp
4
  namespace std {
5
  template <class charT, class traits = char_traits<charT>>
6
  class basic_streambuf {
7
  public:
8
+ using char_type = charT;
9
+ using int_type = typename traits::int_type;
10
+ using pos_type = typename traits::pos_type;
11
+ using off_type = typename traits::off_type;
12
+ using traits_type = traits;
 
 
13
 
14
  virtual ~basic_streambuf();
15
 
16
+ // [streambuf.locales], locales
17
  locale pubimbue(const locale& loc);
18
  locale getloc() const;
19
 
20
+ // [streambuf.buffer], buffer and positioning
21
+ basic_streambuf* pubsetbuf(char_type* s, streamsize n);
 
22
  pos_type pubseekoff(off_type off, ios_base::seekdir way,
23
+ ios_base::openmode which
24
+ = ios_base::in | ios_base::out);
25
  pos_type pubseekpos(pos_type sp,
26
+ ios_base::openmode which
27
+ = ios_base::in | ios_base::out);
28
  int pubsync();
29
 
30
+ // Get and put areas
31
+ // [streambuf.pub.get], get area
32
  streamsize in_avail();
33
  int_type snextc();
34
  int_type sbumpc();
35
  int_type sgetc();
36
  streamsize sgetn(char_type* s, streamsize n);
37
 
38
+ // [streambuf.pub.pback], putback
39
  int_type sputbackc(char_type c);
40
  int_type sungetc();
41
 
42
+ // [streambuf.pub.put], put area
43
  int_type sputc(char_type c);
44
  streamsize sputn(const char_type* s, streamsize n);
45
 
46
  protected:
47
  basic_streambuf();
48
  basic_streambuf(const basic_streambuf& rhs);
49
  basic_streambuf& operator=(const basic_streambuf& rhs);
50
 
51
  void swap(basic_streambuf& rhs);
52
 
53
+ // [streambuf.get.area], get area access
54
  char_type* eback() const;
55
  char_type* gptr() const;
56
  char_type* egptr() const;
57
  void gbump(int n);
58
  void setg(char_type* gbeg, char_type* gnext, char_type* gend);
59
 
60
+ // [streambuf.put.area], put area access
61
  char_type* pbase() const;
62
  char_type* pptr() const;
63
  char_type* epptr() const;
64
  void pbump(int n);
65
  void setp(char_type* pbeg, char_type* pend);
66
 
67
+ // [streambuf.virtuals], virtual functions
68
+ // [streambuf.virt.locales], locales
69
  virtual void imbue(const locale& loc);
70
 
71
+ // [streambuf.virt.buffer], buffer management and positioning
72
+ virtual basic_streambuf* setbuf(char_type* s, streamsize n);
 
73
  virtual pos_type seekoff(off_type off, ios_base::seekdir way,
74
+ ios_base::openmode which
75
+ = ios_base::in | ios_base::out);
76
  virtual pos_type seekpos(pos_type sp,
77
+ ios_base::openmode which
78
+ = ios_base::in | ios_base::out);
79
  virtual int sync();
80
 
81
+ // [streambuf.virt.get], get area
82
  virtual streamsize showmanyc();
83
  virtual streamsize xsgetn(char_type* s, streamsize n);
84
  virtual int_type underflow();
85
  virtual int_type uflow();
86
 
87
+ // [streambuf.virt.pback], putback
88
  virtual int_type pbackfail(int_type c = traits::eof());
89
 
90
+ // [streambuf.virt.put], put area
91
  virtual streamsize xsputn(const char_type* s, streamsize n);
92
  virtual int_type overflow(int_type c = traits::eof());
93
  };
94
  }
95
  ```
96
 
97
+ The class template `basic_streambuf` serves as an abstract base class
98
+ for deriving various *stream buffers* whose objects each control two
99
+ *character sequences*:
100
 
101
  - a character *input sequence*;
102
  - a character *output sequence*.
103
 
104
  #### `basic_streambuf` constructors <a id="streambuf.cons">[[streambuf.cons]]</a>
105
 
106
  ``` cpp
107
  basic_streambuf();
108
  ```
109
 
110
+ *Effects:* Constructs an object of class
111
+ `basic_streambuf<charT, traits>` and initializes:[^13]
112
 
113
  - all its pointer member objects to null pointers,
114
  - the `getloc()` member to a copy the global locale, `locale()`, at the
115
  time of construction.
116
 
 
146
 
147
  ``` cpp
148
  locale pubimbue(const locale& loc);
149
  ```
150
 
151
+ *Postconditions:* `loc == getloc()`.
152
 
153
  *Effects:* Calls `imbue(loc)`.
154
 
155
  *Returns:* Previous value of `getloc()`.
156
 
 
165
  call of `imbue()`) then it returns the previous value.
166
 
167
  ##### Buffer management and positioning <a id="streambuf.buffer">[[streambuf.buffer]]</a>
168
 
169
  ``` cpp
170
+ basic_streambuf* pubsetbuf(char_type* s, streamsize n);
171
  ```
172
 
173
  *Returns:* `setbuf(s, n)`.
174
 
175
  ``` cpp
176
  pos_type pubseekoff(off_type off, ios_base::seekdir way,
177
+ ios_base::openmode which
178
+ = ios_base::in | ios_base::out);
179
  ```
180
 
181
  *Returns:* `seekoff(off, way, which)`.
182
 
183
  ``` cpp
184
  pos_type pubseekpos(pos_type sp,
185
+ ios_base::openmode which
186
+ = ios_base::in | ios_base::out);
187
  ```
188
 
189
  *Returns:* `seekpos(sp, which)`.
190
 
191
  ``` cpp
 
238
  ``` cpp
239
  int_type sputbackc(char_type c);
240
  ```
241
 
242
  *Returns:* If the input sequence putback position is not available, or
243
+ if `traits::eq(c, gptr()[-1])` is `false`, returns
244
  `pbackfail(traits::to_int_type(c))`. Otherwise, decrements the next
245
  pointer for the input sequence and returns
246
  `traits::to_int_type(*gptr())`.
247
 
248
  ``` cpp
 
426
  *Effects:* Synchronizes the controlled sequences with the arrays. That
427
  is, if `pbase()` is non-null the characters between `pbase()` and
428
  `pptr()` are written to the controlled sequence. The pointers may then
429
  be reset as appropriate.
430
 
431
+ *Returns:* `-1` on failure. What constitutes failure is determined by
432
+ each derived class ([[filebuf.virtuals]]).
433
 
434
  *Default behavior:* Returns zero.
435
 
436
  ##### Get area <a id="streambuf.virt.get">[[streambuf.virt.get]]</a>
437
 
 
475
  *Returns:* `traits::to_int_type(c)`, where `c` is the first *character*
476
  of the *pending sequence*, without moving the input sequence position
477
  past it. If the pending sequence is null then the function returns
478
  `traits::eof()` to indicate failure.
479
 
480
+ The *pending sequence* of characters is defined as the concatenation of
481
 
482
+ - the empty sequence if `gptr()` is null, otherwise the characters in
483
+ \[`gptr()`, `egptr()`), followed by
484
+ - some (possibly empty) sequence of characters read from the input
485
+ sequence.
486
 
487
+ The *result character* is the first character of the pending sequence if
488
+ it is non-empty, otherwise the next character that would be read from
489
+ the input sequence.
490
 
491
+ The *backup sequence* is the empty sequence if `eback()` is null,
492
+ otherwise the characters in \[`eback()`, `gptr()`).
493
+
494
+ *Effects:* The function sets up the `gptr()` and `egptr()` such that if
495
+ the pending sequence is non-empty, then `egptr()` is non-null and the
496
+ characters in \[`gptr()`, `egptr()`) are the characters in the pending
497
+ sequence, otherwise either `gptr()` is null or `gptr() == egptr()`.
498
 
499
  If `eback()` and `gptr()` are non-null then the function is not
500
  constrained as to their contents, but the “usual backup condition” is
501
+ that either
502
+
503
+ - the backup sequence contains at least `gptr() - eback()` characters,
504
+ in which case the characters in \[`eback()`, `gptr()`) agree with the
505
+ last `gptr() - eback()` characters of the backup sequence, or
506
+ - the characters in \[`gptr() - n`, `gptr()`) agree with the backup
507
+ sequence (where `n` is the length of the backup sequence).
508
 
509
  *Default behavior:* Returns `traits::eof()`.
510
 
511
  ``` cpp
512
  int_type uflow();
 
539
  modifications that
540
 
541
  - If `traits::eq_int_type(c, traits::eof())` returns `true`, then the
542
  input sequence is backed up one character before the pending sequence
543
  is determined.
544
+ - If `traits::eq_int_type(c, traits::eof())` returns `false`, then `c`
545
+ is prepended. Whether the input sequence is backed up or modified in
546
+ any other way is unspecified.
547
 
548
+ *Postconditions:* On return, the constraints of `gptr()`, `eback()`, and
549
+ `pptr()` are the same as for `underflow()`.
550
 
551
  *Returns:* `traits::eof()` to indicate failure. Failure may occur
552
  because the input sequence could not be backed up, or if for some other
553
  reason the pointers could not be set consistent with the constraints.
554
  `pbackfail()` is called only when put back has really failed.
 
565
 
566
  *Effects:* Writes up to `n` characters to the output sequence as if by
567
  repeated calls to `sputc(c)`. The characters written are obtained from
568
  successive elements of the array whose first element is designated by
569
  `s`. Writing stops when either `n` characters have been written or a
570
+ call to `sputc(c)` would return `traits::eof()`. It is unspecified
571
  whether the function calls `overflow()` when `pptr() == epptr()` becomes
572
+ `true` or whether it achieves the same effects by other means.
573
 
574
  *Returns:* The number of characters written.
575
 
576
  ``` cpp
577
  int_type overflow(int_type c = traits::eof());
 
579
 
580
  *Effects:* Consumes some initial subsequence of the characters of the
581
  *pending sequence*. The pending sequence is defined as the concatenation
582
  of
583
 
584
+ - the empty sequence if `pbase()` is not null, otherwise the
585
+ `pptr() - pbase()` characters beginning at `pbase()`, followed by
586
+ - the empty sequence if `traits::eq_int_type(c, traits::eof())` returns
587
+ `true`, otherwise the sequence consisting of `c`.
588
+
589
  *Remarks:* The member functions `sputc()` and `sputn()` call this
590
  function in case that no room can be found in the put buffer enough to
591
  accommodate the argument character sequence.
592
 
593
  *Requires:* Every overriding definition of this virtual function shall
594
  obey the following constraints:
595
 
596
+ 1. The effect of consuming a character on the associated output
597
+ sequence is specified[^16]
598
+ 2. Let `r` be the number of characters in the pending sequence not
599
+ consumed. If `r` is nonzero then `pbase()` and `pptr()` shall be set
600
+ so that: `pptr() - pbase() == r` and the `r` characters starting at
601
+ `pbase()` are the associated output stream. In case `r` is zero (all
602
+ characters of the pending sequence have been consumed) then either
603
+ `pbase()` is set to `nullptr`, or `pbase()` and `pptr()` are both
604
+ set to the same non-null value.
605
+ 3. The function may fail if either appending some character to the
606
+ associated output stream fails or if it is unable to establish
607
+ `pbase()` and `pptr()` according to the above rules.
608
+
609
  *Returns:* `traits::eof()` or throws an exception if the function fails.
610
 
611
  Otherwise, returns some value other than `traits::eof()` to indicate
612
+ success.[^17]
613
 
614
  *Default behavior:* Returns `traits::eof()`.
615