[stream.buffers] - C++17 → C++20

Files changed (1) hide show

tmp/tmpynz5g2a5/{from.md → to.md} +37 -42

tmp/tmpynz5g2a5/{from.md → to.md} RENAMED Viewed

@@ -92,11 +92,11 @@ namespace std {
     pos_type pubseekpos(pos_type sp,
                         ios_base::openmode which
                           = ios_base::in | ios_base::out);
     int      pubsync();
-    // Get and put areas
     // [streambuf.pub.get], get area
     streamsize in_avail();
     int_type snextc();
     int_type sbumpc();
     int_type sgetc();
@@ -166,20 +166,19 @@ for deriving various *stream buffers* whose objects each control two
 *character sequences*:
 - a character *input sequence*;
 - a character *output sequence*.
-#### `basic_streambuf` constructors <a id="streambuf.cons">[[streambuf.cons]]</a>
 ``` cpp
 basic_streambuf();
 ```
-*Effects:* Constructs an object of class
-`basic_streambuf<charT, traits>` and initializes:[^13]
-- all its pointer member objects to null pointers,
 - the `getloc()` member to a copy the global locale, `locale()`, at the
   time of construction.
 *Remarks:* Once the `getloc()` member is initialized, results of calling
 locale member functions, and of members of facets so obtained, can
@@ -187,13 +186,11 @@ safely be cached until the next time the member `imbue` is called.
 ``` cpp
 basic_streambuf(const basic_streambuf& rhs);
 ```
-*Effects:* Constructs a copy of `rhs`.
-*Postconditions:*
 - `eback() == rhs.eback()`
 - `gptr() == rhs.gptr()`
 - `egptr() == rhs.egptr()`
 - `pbase() == rhs.pbase()`
@@ -205,22 +202,22 @@ basic_streambuf(const basic_streambuf& rhs);
 ~basic_streambuf();
 ```
 *Effects:* None.
-#### `basic_streambuf` public member functions <a id="streambuf.members">[[streambuf.members]]</a>
 ##### Locales <a id="streambuf.locales">[[streambuf.locales]]</a>
 ``` cpp
 locale pubimbue(const locale& loc);
 ```
-*Postconditions:* `loc == getloc()`.
 *Effects:* Calls `imbue(loc)`.
 *Returns:* Previous value of `getloc()`.
 ``` cpp
 locale getloc() const;
 ```
@@ -266,11 +263,11 @@ int pubsync();
 ``` cpp
 streamsize in_avail();
 ```
 *Returns:* If a read position is available, returns `egptr() - gptr()`.
-Otherwise returns `showmanyc()` ([[streambuf.virt.get]]).
 ``` cpp
 int_type snextc();
 ```
@@ -281,11 +278,11 @@ int_type snextc();
 ``` cpp
 int_type sbumpc();
 ```
-*Returns:* If the input sequence read position is not available, returns
 `uflow()`. Otherwise, returns `traits::to_int_type(*gptr())` and
 increments the next pointer for the input sequence.
 ``` cpp
 int_type sgetc();
@@ -304,52 +301,50 @@ streamsize sgetn(char_type* s, streamsize n);
 ``` cpp
 int_type sputbackc(char_type c);
 ```
-*Returns:* If the input sequence putback position is not available, or
 if `traits::eq(c, gptr()[-1])` is `false`, returns
 `pbackfail(traits::to_int_type(c))`. Otherwise, decrements the next
 pointer for the input sequence and returns
 `traits::to_int_type(*gptr())`.
 ``` cpp
 int_type sungetc();
 ```
-*Returns:* If the input sequence putback position is not available,
 returns `pbackfail()`. Otherwise, decrements the next pointer for the
 input sequence and returns `traits::to_int_type(*gptr())`.
 ##### Put area <a id="streambuf.pub.put">[[streambuf.pub.put]]</a>
 ``` cpp
 int_type sputc(char_type c);
 ```
-*Returns:* If the output sequence write position is not available,
 returns `overflow(traits::to_int_type(c))`. Otherwise, stores `c` at the
 next pointer for the output sequence, increments the pointer, and
 returns `traits::to_int_type(c)`.
 ``` cpp
 streamsize sputn(const char_type* s, streamsize n);
 ```
 *Returns:* `xsputn(s, n)`.
-#### `basic_streambuf` protected member functions <a id="streambuf.protected">[[streambuf.protected]]</a>
 ##### Assignment <a id="streambuf.assign">[[streambuf.assign]]</a>
 ``` cpp
 basic_streambuf& operator=(const basic_streambuf& rhs);
 ```
-*Effects:* Assigns the data members of `rhs` to `*this`.
-*Postconditions:*
 - `eback() == rhs.eback()`
 - `gptr() == rhs.gptr()`
 - `egptr() == rhs.egptr()`
 - `pbase() == rhs.pbase()`
@@ -393,12 +388,12 @@ void gbump(int n);
 ``` cpp
 void setg(char_type* gbeg, char_type* gnext, char_type* gend);
 ```
-*Postconditions:* `gbeg == eback()`, `gnext == gptr()`, and
-`gend == egptr()`.
 ##### Put area access <a id="streambuf.put.area">[[streambuf.put.area]]</a>
 ``` cpp
 char_type* pbase() const;
@@ -426,14 +421,14 @@ void pbump(int n);
 ``` cpp
 void setp(char_type* pbeg, char_type* pend);
 ```
-*Postconditions:* `pbeg == pbase()`, `pbeg == pptr()`, and
-`pend == epptr()`.
-#### `basic_streambuf` virtual functions <a id="streambuf.virtuals">[[streambuf.virtuals]]</a>
 ##### Locales <a id="streambuf.virt.locales">[[streambuf.virt.locales]]</a>
 ``` cpp
 void imbue(const locale&);
@@ -494,11 +489,11 @@ int sync();
 is, if `pbase()` is non-null the characters between `pbase()` and
 `pptr()` are written to the controlled sequence. The pointers may then
 be reset as appropriate.
 *Returns:* `-1` on failure. What constitutes failure is determined by
-each derived class ([[filebuf.virtuals]]).
 *Default behavior:* Returns zero.
 ##### Get area <a id="streambuf.virt.get">[[streambuf.virt.get]]</a>
@@ -535,11 +530,11 @@ to `sbumpc()` would return `traits::eof()`.
 ``` cpp
 int_type underflow();
 ```
 *Remarks:* The public members of `basic_streambuf` call this virtual
-function only if `gptr()` is null or `gptr() >= egptr()`
 *Returns:* `traits::to_int_type(c)`, where `c` is the first *character*
 of the *pending sequence*, without moving the input sequence position
 past it. If the pending sequence is null then the function returns
 `traits::eof()` to indicate failure.
@@ -577,13 +572,13 @@ that either
 ``` cpp
 int_type uflow();
 ```
-*Requires:* The constraints are the same as for `underflow()`, except
-that the result character shall be transferred from the pending sequence
-to the backup sequence, and the pending sequence shall not be empty
 before the transfer.
 *Default behavior:* Calls `underflow()`. If `underflow()` returns
 `traits::eof()`, returns `traits::eof()`. Otherwise, returns the value
 of `traits::to_int_type(*gptr())` and increment the value of the next
@@ -610,11 +605,11 @@ modifications that
   is determined.
 - If `traits::eq_int_type(c, traits::eof())` returns `false`, then `c`
   is prepended. Whether the input sequence is backed up or modified in
   any other way is unspecified.
-*Postconditions:* On return, the constraints of `gptr()`, `eback()`, and
 `pptr()` are the same as for `underflow()`.
 *Returns:* `traits::eof()` to indicate failure. Failure may occur
 because the input sequence could not be backed up, or if for some other
 reason the pointers could not be set consistent with the constraints.
@@ -646,32 +641,32 @@ int_type overflow(int_type c = traits::eof());
 *Effects:* Consumes some initial subsequence of the characters of the
 *pending sequence*. The pending sequence is defined as the concatenation
 of
-- the empty sequence if `pbase()` is not null, otherwise the
   `pptr() - pbase()` characters beginning at `pbase()`, followed by
 - the empty sequence if `traits::eq_int_type(c, traits::eof())` returns
   `true`, otherwise the sequence consisting of `c`.
 *Remarks:* The member functions `sputc()` and `sputn()` call this
 function in case that no room can be found in the put buffer enough to
 accommodate the argument character sequence.
-*Requires:* Every overriding definition of this virtual function shall
-obey the following constraints:
-1.  The effect of consuming a character on the associated output
-    sequence is specified[^16]
-2.  Let `r` be the number of characters in the pending sequence not
- consumed. If `r` is nonzero then `pbase()` and `pptr()` shall be set
-    so that: `pptr() - pbase() == r` and the `r` characters starting at
   `pbase()` are the associated output stream. In case `r` is zero (all
   characters of the pending sequence have been consumed) then either
- `pbase()` is set to `nullptr`, or `pbase()` and `pptr()` are both
-    set to the same non-null value.
-3.  The function may fail if either appending some character to the
   associated output stream fails or if it is unable to establish
   `pbase()` and `pptr()` according to the above rules.
 *Returns:* `traits::eof()` or throws an exception if the function fails.

     pos_type pubseekpos(pos_type sp,
                         ios_base::openmode which
                           = ios_base::in | ios_base::out);
     int      pubsync();
+    // get and put areas
     // [streambuf.pub.get], get area
     streamsize in_avail();
     int_type snextc();
     int_type sbumpc();
     int_type sgetc();
 *character sequences*:
 - a character *input sequence*;
 - a character *output sequence*.
+#### Constructors <a id="streambuf.cons">[[streambuf.cons]]</a>
 ``` cpp
 basic_streambuf();
 ```
+*Effects:* Initializes:[^13]
+- all pointer member objects to null pointers,
 - the `getloc()` member to a copy the global locale, `locale()`, at the
   time of construction.
 *Remarks:* Once the `getloc()` member is initialized, results of calling
 locale member functions, and of members of facets so obtained, can
 ``` cpp
 basic_streambuf(const basic_streambuf& rhs);
 ```
+*Ensures:*
 - `eback() == rhs.eback()`
 - `gptr() == rhs.gptr()`
 - `egptr() == rhs.egptr()`
 - `pbase() == rhs.pbase()`
 ~basic_streambuf();
 ```
 *Effects:* None.
+#### Public member functions <a id="streambuf.members">[[streambuf.members]]</a>
 ##### Locales <a id="streambuf.locales">[[streambuf.locales]]</a>
 ``` cpp
 locale pubimbue(const locale& loc);
 ```
 *Effects:* Calls `imbue(loc)`.
+*Ensures:* `loc == getloc()`.
 *Returns:* Previous value of `getloc()`.
 ``` cpp
 locale getloc() const;
 ```
 ``` cpp
 streamsize in_avail();
 ```
 *Returns:* If a read position is available, returns `egptr() - gptr()`.
+Otherwise returns `showmanyc()` [[streambuf.virt.get]].
 ``` cpp
 int_type snextc();
 ```
 ``` cpp
 int_type sbumpc();
 ```
+*Effects:* If the input sequence read position is not available, returns
 `uflow()`. Otherwise, returns `traits::to_int_type(*gptr())` and
 increments the next pointer for the input sequence.
 ``` cpp
 int_type sgetc();
 ``` cpp
 int_type sputbackc(char_type c);
 ```
+*Effects:* If the input sequence putback position is not available, or
 if `traits::eq(c, gptr()[-1])` is `false`, returns
 `pbackfail(traits::to_int_type(c))`. Otherwise, decrements the next
 pointer for the input sequence and returns
 `traits::to_int_type(*gptr())`.
 ``` cpp
 int_type sungetc();
 ```
+*Effects:* If the input sequence putback position is not available,
 returns `pbackfail()`. Otherwise, decrements the next pointer for the
 input sequence and returns `traits::to_int_type(*gptr())`.
 ##### Put area <a id="streambuf.pub.put">[[streambuf.pub.put]]</a>
 ``` cpp
 int_type sputc(char_type c);
 ```
+*Effects:* If the output sequence write position is not available,
 returns `overflow(traits::to_int_type(c))`. Otherwise, stores `c` at the
 next pointer for the output sequence, increments the pointer, and
 returns `traits::to_int_type(c)`.
 ``` cpp
 streamsize sputn(const char_type* s, streamsize n);
 ```
 *Returns:* `xsputn(s, n)`.
+#### Protected member functions <a id="streambuf.protected">[[streambuf.protected]]</a>
 ##### Assignment <a id="streambuf.assign">[[streambuf.assign]]</a>
 ``` cpp
 basic_streambuf& operator=(const basic_streambuf& rhs);
 ```
+*Ensures:*
 - `eback() == rhs.eback()`
 - `gptr() == rhs.gptr()`
 - `egptr() == rhs.egptr()`
 - `pbase() == rhs.pbase()`
 ``` cpp
 void setg(char_type* gbeg, char_type* gnext, char_type* gend);
 ```
+*Ensures:* `gbeg == eback()`, `gnext == gptr()`, and `gend == egptr()`
+are all `true`.
 ##### Put area access <a id="streambuf.put.area">[[streambuf.put.area]]</a>
 ``` cpp
 char_type* pbase() const;
 ``` cpp
 void setp(char_type* pbeg, char_type* pend);
 ```
+*Ensures:* `pbeg == pbase()`, `pbeg == pptr()`, and `pend == epptr()`
+are all `true`.
+#### Virtual functions <a id="streambuf.virtuals">[[streambuf.virtuals]]</a>
 ##### Locales <a id="streambuf.virt.locales">[[streambuf.virt.locales]]</a>
 ``` cpp
 void imbue(const locale&);
 is, if `pbase()` is non-null the characters between `pbase()` and
 `pptr()` are written to the controlled sequence. The pointers may then
 be reset as appropriate.
 *Returns:* `-1` on failure. What constitutes failure is determined by
+each derived class [[filebuf.virtuals]].
 *Default behavior:* Returns zero.
 ##### Get area <a id="streambuf.virt.get">[[streambuf.virt.get]]</a>
 ``` cpp
 int_type underflow();
 ```
 *Remarks:* The public members of `basic_streambuf` call this virtual
+function only if `gptr()` is null or `gptr() >= egptr()`.
 *Returns:* `traits::to_int_type(c)`, where `c` is the first *character*
 of the *pending sequence*, without moving the input sequence position
 past it. If the pending sequence is null then the function returns
 `traits::eof()` to indicate failure.
 ``` cpp
 int_type uflow();
 ```
+*Preconditions:* The constraints are the same as for `underflow()`,
+except that the result character is transferred from the pending
+sequence to the backup sequence, and the pending sequence is not empty
 before the transfer.
 *Default behavior:* Calls `underflow()`. If `underflow()` returns
 `traits::eof()`, returns `traits::eof()`. Otherwise, returns the value
 of `traits::to_int_type(*gptr())` and increment the value of the next
   is determined.
 - If `traits::eq_int_type(c, traits::eof())` returns `false`, then `c`
   is prepended. Whether the input sequence is backed up or modified in
   any other way is unspecified.
+*Ensures:* On return, the constraints of `gptr()`, `eback()`, and
 `pptr()` are the same as for `underflow()`.
 *Returns:* `traits::eof()` to indicate failure. Failure may occur
 because the input sequence could not be backed up, or if for some other
 reason the pointers could not be set consistent with the constraints.
 *Effects:* Consumes some initial subsequence of the characters of the
 *pending sequence*. The pending sequence is defined as the concatenation
 of
+- the empty sequence if `pbase()` is null, otherwise the
   `pptr() - pbase()` characters beginning at `pbase()`, followed by
 - the empty sequence if `traits::eq_int_type(c, traits::eof())` returns
   `true`, otherwise the sequence consisting of `c`.
 *Remarks:* The member functions `sputc()` and `sputn()` call this
 function in case that no room can be found in the put buffer enough to
 accommodate the argument character sequence.
+*Preconditions:* Every overriding definition of this virtual function
+obeys the following constraints:
+- The effect of consuming a character on the associated output sequence
+ is specified.[^16]
+- Let `r` be the number of characters in the pending sequence not
+ consumed. If `r` is nonzero then `pbase()` and `pptr()` are set so
+ that: `pptr() - pbase() == r` and the `r` characters starting at
   `pbase()` are the associated output stream. In case `r` is zero (all
   characters of the pending sequence have been consumed) then either
+ `pbase()` is set to `nullptr`, or `pbase()` and `pptr()` are both set
+ to the same non-null value.
+- The function may fail if either appending some character to the
   associated output stream fails or if it is unable to establish
   `pbase()` and `pptr()` according to the above rules.
 *Returns:* `traits::eof()` or throws an exception if the function fails.

Diff to HTML by rtfpessoa