From Jason Turner

[stream.buffers]

C++14 → C++17 14.4 KB 168 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/tmp95jnx3ff/{from.md → to.md} +95 -61
tmp/tmp95jnx3ff/{from.md → to.md} RENAMED
@@ -1,15 +1,15 @@
1
  ## Stream buffers <a id="stream.buffers">[[stream.buffers]]</a>
2
 
3
- ### Overview <a id="stream.buffers.overview">[[stream.buffers.overview]]</a>
4
 
5
  ``` cpp
6
  namespace std {
7
  template <class charT, class traits = char_traits<charT>>
8
  class basic_streambuf;
9
- typedef basic_streambuf<char> streambuf;
10
- typedef basic_streambuf<wchar_t> wstreambuf;
11
  }
12
  ```
13
 
14
  The header `<streambuf>` defines types that control input from and
15
  output to *character* sequences.
@@ -63,123 +63,121 @@ above:
63
  - If `xnext` is not a null pointer and `xnext < xend` for an input
64
  sequence, then a *read position* is available. In this case, `*xnext`
65
  shall have a defined value and is the next element to read (to get, or
66
  to obtain a character value, from the sequence).
67
 
68
- ### Class template `basic_streambuf<charT,traits>` <a id="streambuf">[[streambuf]]</a>
69
 
70
  ``` cpp
71
  namespace std {
72
  template <class charT, class traits = char_traits<charT>>
73
  class basic_streambuf {
74
  public:
75
-
76
- // types:
77
- typedef charT char_type;
78
- typedef typename traits::int_type int_type;
79
- typedef typename traits::pos_type pos_type;
80
- typedef typename traits::off_type off_type;
81
- typedef traits traits_type;
82
 
83
  virtual ~basic_streambuf();
84
 
85
- // [streambuf.locales] locales:
86
  locale pubimbue(const locale& loc);
87
  locale getloc() const;
88
 
89
- // [streambuf.buffer] buffer and positioning:
90
- basic_streambuf<char_type,traits>*
91
- pubsetbuf(char_type* s, streamsize n);
92
  pos_type pubseekoff(off_type off, ios_base::seekdir way,
93
- ios_base::openmode which =
94
- ios_base::in | ios_base::out);
95
  pos_type pubseekpos(pos_type sp,
96
- ios_base::openmode which =
97
- ios_base::in | ios_base::out);
98
  int pubsync();
99
 
100
- // Get and put areas:
101
- // [streambuf.pub.get] Get area:
102
  streamsize in_avail();
103
  int_type snextc();
104
  int_type sbumpc();
105
  int_type sgetc();
106
  streamsize sgetn(char_type* s, streamsize n);
107
 
108
- // [streambuf.pub.pback] Putback:
109
  int_type sputbackc(char_type c);
110
  int_type sungetc();
111
 
112
- // [streambuf.pub.put] Put area:
113
  int_type sputc(char_type c);
114
  streamsize sputn(const char_type* s, streamsize n);
115
 
116
  protected:
117
  basic_streambuf();
118
  basic_streambuf(const basic_streambuf& rhs);
119
  basic_streambuf& operator=(const basic_streambuf& rhs);
120
 
121
  void swap(basic_streambuf& rhs);
122
 
123
- // [streambuf.get.area] Get area:
124
  char_type* eback() const;
125
  char_type* gptr() const;
126
  char_type* egptr() const;
127
  void gbump(int n);
128
  void setg(char_type* gbeg, char_type* gnext, char_type* gend);
129
 
130
- // [streambuf.put.area] Put area:
131
  char_type* pbase() const;
132
  char_type* pptr() const;
133
  char_type* epptr() const;
134
  void pbump(int n);
135
  void setp(char_type* pbeg, char_type* pend);
136
 
137
- // [streambuf.virtuals] virtual functions:
138
- // [streambuf.virt.locales] Locales:
139
  virtual void imbue(const locale& loc);
140
 
141
- // [streambuf.virt.buffer] Buffer management and positioning:
142
- virtual basic_streambuf<char_type,traits>*
143
- setbuf(char_type* s, streamsize n);
144
  virtual pos_type seekoff(off_type off, ios_base::seekdir way,
145
- ios_base::openmode which = ios_base::in | ios_base::out);
 
146
  virtual pos_type seekpos(pos_type sp,
147
- ios_base::openmode which = ios_base::in | ios_base::out);
 
148
  virtual int sync();
149
 
150
- // [streambuf.virt.get] Get area:
151
  virtual streamsize showmanyc();
152
  virtual streamsize xsgetn(char_type* s, streamsize n);
153
  virtual int_type underflow();
154
  virtual int_type uflow();
155
 
156
- // [streambuf.virt.pback] Putback:
157
  virtual int_type pbackfail(int_type c = traits::eof());
158
 
159
- // [streambuf.virt.put] Put area:
160
  virtual streamsize xsputn(const char_type* s, streamsize n);
161
  virtual int_type overflow(int_type c = traits::eof());
162
  };
163
  }
164
  ```
165
 
166
- The class template `basic_streambuf<charT,traits>` serves as an abstract
167
- base class for deriving various *stream buffers* whose objects each
168
- control two *character sequences*:
169
 
170
  - a character *input sequence*;
171
  - a character *output sequence*.
172
 
173
  #### `basic_streambuf` constructors <a id="streambuf.cons">[[streambuf.cons]]</a>
174
 
175
  ``` cpp
176
  basic_streambuf();
177
  ```
178
 
179
- *Effects:* Constructs an object of class `basic_streambuf<charT,traits>`
180
- and initializes:[^13]
181
 
182
  - all its pointer member objects to null pointers,
183
  - the `getloc()` member to a copy the global locale, `locale()`, at the
184
  time of construction.
185
 
@@ -215,11 +213,11 @@ basic_streambuf(const basic_streambuf& rhs);
215
 
216
  ``` cpp
217
  locale pubimbue(const locale& loc);
218
  ```
219
 
220
- `loc == getloc()`.
221
 
222
  *Effects:* Calls `imbue(loc)`.
223
 
224
  *Returns:* Previous value of `getloc()`.
225
 
@@ -234,25 +232,27 @@ been called but before `pubimbue` has returned (i.e., from within the
234
  call of `imbue()`) then it returns the previous value.
235
 
236
  ##### Buffer management and positioning <a id="streambuf.buffer">[[streambuf.buffer]]</a>
237
 
238
  ``` cpp
239
- basic_streambuf<char_type,traits>* pubsetbuf(char_type* s, streamsize n);
240
  ```
241
 
242
  *Returns:* `setbuf(s, n)`.
243
 
244
  ``` cpp
245
  pos_type pubseekoff(off_type off, ios_base::seekdir way,
246
- ios_base::openmode which = ios_base::in | ios_base::out);
 
247
  ```
248
 
249
  *Returns:* `seekoff(off, way, which)`.
250
 
251
  ``` cpp
252
  pos_type pubseekpos(pos_type sp,
253
- ios_base::openmode which = ios_base::in | ios_base::out);
 
254
  ```
255
 
256
  *Returns:* `seekpos(sp, which)`.
257
 
258
  ``` cpp
@@ -305,11 +305,11 @@ streamsize sgetn(char_type* s, streamsize n);
305
  ``` cpp
306
  int_type sputbackc(char_type c);
307
  ```
308
 
309
  *Returns:* If the input sequence putback position is not available, or
310
- if `traits::eq(c,gptr()[-1])` is false, returns
311
  `pbackfail(traits::to_int_type(c))`. Otherwise, decrements the next
312
  pointer for the input sequence and returns
313
  `traits::to_int_type(*gptr())`.
314
 
315
  ``` cpp
@@ -493,12 +493,12 @@ int sync();
493
  *Effects:* Synchronizes the controlled sequences with the arrays. That
494
  is, if `pbase()` is non-null the characters between `pbase()` and
495
  `pptr()` are written to the controlled sequence. The pointers may then
496
  be reset as appropriate.
497
 
498
- *Returns:* -1 on failure. What constitutes failure is determined by each
499
- derived class ([[filebuf.virtuals]]).
500
 
501
  *Default behavior:* Returns zero.
502
 
503
  ##### Get area <a id="streambuf.virt.get">[[streambuf.virt.get]]</a>
504
 
@@ -542,22 +542,38 @@ function only if `gptr()` is null or `gptr() >= egptr()`
542
  *Returns:* `traits::to_int_type(c)`, where `c` is the first *character*
543
  of the *pending sequence*, without moving the input sequence position
544
  past it. If the pending sequence is null then the function returns
545
  `traits::eof()` to indicate failure.
546
 
547
- The *pending sequence* of characters is defined as the concatenation of:
548
 
549
- The *result character* is
 
 
 
550
 
551
- The *backup sequence* is defined as the concatenation of:
 
 
552
 
553
- *Effects:* The function sets up the `gptr()` and `egptr()` satisfying
554
- one of:
 
 
 
 
 
555
 
556
  If `eback()` and `gptr()` are non-null then the function is not
557
  constrained as to their contents, but the “usual backup condition” is
558
- that either:
 
 
 
 
 
 
559
 
560
  *Default behavior:* Returns `traits::eof()`.
561
 
562
  ``` cpp
563
  int_type uflow();
@@ -590,16 +606,16 @@ The *pending sequence* is defined as for `underflow()`, with the
590
  modifications that
591
 
592
  - If `traits::eq_int_type(c, traits::eof())` returns `true`, then the
593
  input sequence is backed up one character before the pending sequence
594
  is determined.
595
- - If `traits::eq_int_type(c,traits::eof())` returns `false`, then `c` is
596
- prepended. Whether the input sequence is backed up or modified in any
597
- other way is unspecified.
598
 
599
- On return, the constraints of `gptr()`, `eback()`, and `pptr()` are the
600
- same as for `underflow()`.
601
 
602
  *Returns:* `traits::eof()` to indicate failure. Failure may occur
603
  because the input sequence could not be backed up, or if for some other
604
  reason the pointers could not be set consistent with the constraints.
605
  `pbackfail()` is called only when put back has really failed.
@@ -616,13 +632,13 @@ streamsize xsputn(const char_type* s, streamsize n);
616
 
617
  *Effects:* Writes up to `n` characters to the output sequence as if by
618
  repeated calls to `sputc(c)`. The characters written are obtained from
619
  successive elements of the array whose first element is designated by
620
  `s`. Writing stops when either `n` characters have been written or a
621
- call to `sputc(c)` would return `traits::eof()`. Is is unspecified
622
  whether the function calls `overflow()` when `pptr() == epptr()` becomes
623
- true or whether it achieves the same effects by other means.
624
 
625
  *Returns:* The number of characters written.
626
 
627
  ``` cpp
628
  int_type overflow(int_type c = traits::eof());
@@ -630,19 +646,37 @@ int_type overflow(int_type c = traits::eof());
630
 
631
  *Effects:* Consumes some initial subsequence of the characters of the
632
  *pending sequence*. The pending sequence is defined as the concatenation
633
  of
634
 
 
 
 
 
 
635
  *Remarks:* The member functions `sputc()` and `sputn()` call this
636
  function in case that no room can be found in the put buffer enough to
637
  accommodate the argument character sequence.
638
 
639
  *Requires:* Every overriding definition of this virtual function shall
640
  obey the following constraints:
641
 
 
 
 
 
 
 
 
 
 
 
 
 
 
642
  *Returns:* `traits::eof()` or throws an exception if the function fails.
643
 
644
  Otherwise, returns some value other than `traits::eof()` to indicate
645
- success.[^16]
646
 
647
  *Default behavior:* Returns `traits::eof()`.
648
 
 
1
  ## Stream buffers <a id="stream.buffers">[[stream.buffers]]</a>
2
 
3
+ ### Header `<streambuf>` synopsis <a id="streambuf.syn">[[streambuf.syn]]</a>
4
 
5
  ``` cpp
6
  namespace std {
7
  template <class charT, class traits = char_traits<charT>>
8
  class basic_streambuf;
9
+ using streambuf = basic_streambuf<char>;
10
+ using wstreambuf = basic_streambuf<wchar_t>;
11
  }
12
  ```
13
 
14
  The header `<streambuf>` defines types that control input from and
15
  output to *character* sequences.
 
63
  - If `xnext` is not a null pointer and `xnext < xend` for an input
64
  sequence, then a *read position* is available. In this case, `*xnext`
65
  shall have a defined value and is the next element to read (to get, or
66
  to obtain a character value, from the sequence).
67
 
68
+ ### Class template `basic_streambuf` <a id="streambuf">[[streambuf]]</a>
69
 
70
  ``` cpp
71
  namespace std {
72
  template <class charT, class traits = char_traits<charT>>
73
  class basic_streambuf {
74
  public:
75
+ using char_type = charT;
76
+ using int_type = typename traits::int_type;
77
+ using pos_type = typename traits::pos_type;
78
+ using off_type = typename traits::off_type;
79
+ using traits_type = traits;
 
 
80
 
81
  virtual ~basic_streambuf();
82
 
83
+ // [streambuf.locales], locales
84
  locale pubimbue(const locale& loc);
85
  locale getloc() const;
86
 
87
+ // [streambuf.buffer], buffer and positioning
88
+ basic_streambuf* pubsetbuf(char_type* s, streamsize n);
 
89
  pos_type pubseekoff(off_type off, ios_base::seekdir way,
90
+ ios_base::openmode which
91
+ = ios_base::in | ios_base::out);
92
  pos_type pubseekpos(pos_type sp,
93
+ ios_base::openmode which
94
+ = ios_base::in | ios_base::out);
95
  int pubsync();
96
 
97
+ // Get and put areas
98
+ // [streambuf.pub.get], get area
99
  streamsize in_avail();
100
  int_type snextc();
101
  int_type sbumpc();
102
  int_type sgetc();
103
  streamsize sgetn(char_type* s, streamsize n);
104
 
105
+ // [streambuf.pub.pback], putback
106
  int_type sputbackc(char_type c);
107
  int_type sungetc();
108
 
109
+ // [streambuf.pub.put], put area
110
  int_type sputc(char_type c);
111
  streamsize sputn(const char_type* s, streamsize n);
112
 
113
  protected:
114
  basic_streambuf();
115
  basic_streambuf(const basic_streambuf& rhs);
116
  basic_streambuf& operator=(const basic_streambuf& rhs);
117
 
118
  void swap(basic_streambuf& rhs);
119
 
120
+ // [streambuf.get.area], get area access
121
  char_type* eback() const;
122
  char_type* gptr() const;
123
  char_type* egptr() const;
124
  void gbump(int n);
125
  void setg(char_type* gbeg, char_type* gnext, char_type* gend);
126
 
127
+ // [streambuf.put.area], put area access
128
  char_type* pbase() const;
129
  char_type* pptr() const;
130
  char_type* epptr() const;
131
  void pbump(int n);
132
  void setp(char_type* pbeg, char_type* pend);
133
 
134
+ // [streambuf.virtuals], virtual functions
135
+ // [streambuf.virt.locales], locales
136
  virtual void imbue(const locale& loc);
137
 
138
+ // [streambuf.virt.buffer], buffer management and positioning
139
+ virtual basic_streambuf* setbuf(char_type* s, streamsize n);
 
140
  virtual pos_type seekoff(off_type off, ios_base::seekdir way,
141
+ ios_base::openmode which
142
+ = ios_base::in | ios_base::out);
143
  virtual pos_type seekpos(pos_type sp,
144
+ ios_base::openmode which
145
+ = ios_base::in | ios_base::out);
146
  virtual int sync();
147
 
148
+ // [streambuf.virt.get], get area
149
  virtual streamsize showmanyc();
150
  virtual streamsize xsgetn(char_type* s, streamsize n);
151
  virtual int_type underflow();
152
  virtual int_type uflow();
153
 
154
+ // [streambuf.virt.pback], putback
155
  virtual int_type pbackfail(int_type c = traits::eof());
156
 
157
+ // [streambuf.virt.put], put area
158
  virtual streamsize xsputn(const char_type* s, streamsize n);
159
  virtual int_type overflow(int_type c = traits::eof());
160
  };
161
  }
162
  ```
163
 
164
+ The class template `basic_streambuf` serves as an abstract base class
165
+ for deriving various *stream buffers* whose objects each control two
166
+ *character sequences*:
167
 
168
  - a character *input sequence*;
169
  - a character *output sequence*.
170
 
171
  #### `basic_streambuf` constructors <a id="streambuf.cons">[[streambuf.cons]]</a>
172
 
173
  ``` cpp
174
  basic_streambuf();
175
  ```
176
 
177
+ *Effects:* Constructs an object of class
178
+ `basic_streambuf<charT, traits>` and initializes:[^13]
179
 
180
  - all its pointer member objects to null pointers,
181
  - the `getloc()` member to a copy the global locale, `locale()`, at the
182
  time of construction.
183
 
 
213
 
214
  ``` cpp
215
  locale pubimbue(const locale& loc);
216
  ```
217
 
218
+ *Postconditions:* `loc == getloc()`.
219
 
220
  *Effects:* Calls `imbue(loc)`.
221
 
222
  *Returns:* Previous value of `getloc()`.
223
 
 
232
  call of `imbue()`) then it returns the previous value.
233
 
234
  ##### Buffer management and positioning <a id="streambuf.buffer">[[streambuf.buffer]]</a>
235
 
236
  ``` cpp
237
+ basic_streambuf* pubsetbuf(char_type* s, streamsize n);
238
  ```
239
 
240
  *Returns:* `setbuf(s, n)`.
241
 
242
  ``` cpp
243
  pos_type pubseekoff(off_type off, ios_base::seekdir way,
244
+ ios_base::openmode which
245
+ = ios_base::in | ios_base::out);
246
  ```
247
 
248
  *Returns:* `seekoff(off, way, which)`.
249
 
250
  ``` cpp
251
  pos_type pubseekpos(pos_type sp,
252
+ ios_base::openmode which
253
+ = ios_base::in | ios_base::out);
254
  ```
255
 
256
  *Returns:* `seekpos(sp, which)`.
257
 
258
  ``` cpp
 
305
  ``` cpp
306
  int_type sputbackc(char_type c);
307
  ```
308
 
309
  *Returns:* If the input sequence putback position is not available, or
310
+ if `traits::eq(c, gptr()[-1])` is `false`, returns
311
  `pbackfail(traits::to_int_type(c))`. Otherwise, decrements the next
312
  pointer for the input sequence and returns
313
  `traits::to_int_type(*gptr())`.
314
 
315
  ``` cpp
 
493
  *Effects:* Synchronizes the controlled sequences with the arrays. That
494
  is, if `pbase()` is non-null the characters between `pbase()` and
495
  `pptr()` are written to the controlled sequence. The pointers may then
496
  be reset as appropriate.
497
 
498
+ *Returns:* `-1` on failure. What constitutes failure is determined by
499
+ each derived class ([[filebuf.virtuals]]).
500
 
501
  *Default behavior:* Returns zero.
502
 
503
  ##### Get area <a id="streambuf.virt.get">[[streambuf.virt.get]]</a>
504
 
 
542
  *Returns:* `traits::to_int_type(c)`, where `c` is the first *character*
543
  of the *pending sequence*, without moving the input sequence position
544
  past it. If the pending sequence is null then the function returns
545
  `traits::eof()` to indicate failure.
546
 
547
+ The *pending sequence* of characters is defined as the concatenation of
548
 
549
+ - the empty sequence if `gptr()` is null, otherwise the characters in
550
+ \[`gptr()`, `egptr()`), followed by
551
+ - some (possibly empty) sequence of characters read from the input
552
+ sequence.
553
 
554
+ The *result character* is the first character of the pending sequence if
555
+ it is non-empty, otherwise the next character that would be read from
556
+ the input sequence.
557
 
558
+ The *backup sequence* is the empty sequence if `eback()` is null,
559
+ otherwise the characters in \[`eback()`, `gptr()`).
560
+
561
+ *Effects:* The function sets up the `gptr()` and `egptr()` such that if
562
+ the pending sequence is non-empty, then `egptr()` is non-null and the
563
+ characters in \[`gptr()`, `egptr()`) are the characters in the pending
564
+ sequence, otherwise either `gptr()` is null or `gptr() == egptr()`.
565
 
566
  If `eback()` and `gptr()` are non-null then the function is not
567
  constrained as to their contents, but the “usual backup condition” is
568
+ that either
569
+
570
+ - the backup sequence contains at least `gptr() - eback()` characters,
571
+ in which case the characters in \[`eback()`, `gptr()`) agree with the
572
+ last `gptr() - eback()` characters of the backup sequence, or
573
+ - the characters in \[`gptr() - n`, `gptr()`) agree with the backup
574
+ sequence (where `n` is the length of the backup sequence).
575
 
576
  *Default behavior:* Returns `traits::eof()`.
577
 
578
  ``` cpp
579
  int_type uflow();
 
606
  modifications that
607
 
608
  - If `traits::eq_int_type(c, traits::eof())` returns `true`, then the
609
  input sequence is backed up one character before the pending sequence
610
  is determined.
611
+ - If `traits::eq_int_type(c, traits::eof())` returns `false`, then `c`
612
+ is prepended. Whether the input sequence is backed up or modified in
613
+ any other way is unspecified.
614
 
615
+ *Postconditions:* On return, the constraints of `gptr()`, `eback()`, and
616
+ `pptr()` are the same as for `underflow()`.
617
 
618
  *Returns:* `traits::eof()` to indicate failure. Failure may occur
619
  because the input sequence could not be backed up, or if for some other
620
  reason the pointers could not be set consistent with the constraints.
621
  `pbackfail()` is called only when put back has really failed.
 
632
 
633
  *Effects:* Writes up to `n` characters to the output sequence as if by
634
  repeated calls to `sputc(c)`. The characters written are obtained from
635
  successive elements of the array whose first element is designated by
636
  `s`. Writing stops when either `n` characters have been written or a
637
+ call to `sputc(c)` would return `traits::eof()`. It is unspecified
638
  whether the function calls `overflow()` when `pptr() == epptr()` becomes
639
+ `true` or whether it achieves the same effects by other means.
640
 
641
  *Returns:* The number of characters written.
642
 
643
  ``` cpp
644
  int_type overflow(int_type c = traits::eof());
 
646
 
647
  *Effects:* Consumes some initial subsequence of the characters of the
648
  *pending sequence*. The pending sequence is defined as the concatenation
649
  of
650
 
651
+ - the empty sequence if `pbase()` is not null, otherwise the
652
+ `pptr() - pbase()` characters beginning at `pbase()`, followed by
653
+ - the empty sequence if `traits::eq_int_type(c, traits::eof())` returns
654
+ `true`, otherwise the sequence consisting of `c`.
655
+
656
  *Remarks:* The member functions `sputc()` and `sputn()` call this
657
  function in case that no room can be found in the put buffer enough to
658
  accommodate the argument character sequence.
659
 
660
  *Requires:* Every overriding definition of this virtual function shall
661
  obey the following constraints:
662
 
663
+ 1. The effect of consuming a character on the associated output
664
+ sequence is specified[^16]
665
+ 2. Let `r` be the number of characters in the pending sequence not
666
+ consumed. If `r` is nonzero then `pbase()` and `pptr()` shall be set
667
+ so that: `pptr() - pbase() == r` and the `r` characters starting at
668
+ `pbase()` are the associated output stream. In case `r` is zero (all
669
+ characters of the pending sequence have been consumed) then either
670
+ `pbase()` is set to `nullptr`, or `pbase()` and `pptr()` are both
671
+ set to the same non-null value.
672
+ 3. The function may fail if either appending some character to the
673
+ associated output stream fails or if it is unable to establish
674
+ `pbase()` and `pptr()` according to the above rules.
675
+
676
  *Returns:* `traits::eof()` or throws an exception if the function fails.
677
 
678
  Otherwise, returns some value other than `traits::eof()` to indicate
679
+ success.[^17]
680
 
681
  *Default behavior:* Returns `traits::eof()`.
682