[istream.unformatted] - C++14 → C++17

Files changed (1) hide show

tmp/tmp5mmbg_hc/{from.md → to.md} +91 -94

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

@@ -3,18 +3,18 @@
 Each unformatted input function begins execution by constructing an
 object of class `sentry` with the default argument `noskipws` (second)
 argument `true`. If the `sentry` object returns `true`, when converted
 to a value of type `bool`, the function endeavors to obtain the
 requested input. Otherwise, if the sentry constructor exits by throwing
-an exception or if the sentry object returns false, when converted to a
-value of type `bool`, the function returns without attempting to obtain
-any input. In either case the number of extracted characters is set to
-0; unformatted input functions taking a character array of non-zero size
-as an argument shall also store a null character (using `charT()`) in
-the first location of the array. If an exception is thrown during input
-then `ios::badbit` is turned on[^22] in `*this`’s error state.
-(Exceptions thrown from `basic_ios<>::clear()` are not caught or
 rethrown.) If `(exceptions()&badbit) != 0` then the exception is
 rethrown. It also counts the number of characters extracted. If no
 exception has been thrown it ends by storing the count in a member
 object and returning the value specified. In any event the `sentry`
 object is destroyed before leaving the unformatted input function.
@@ -22,49 +22,47 @@ object is destroyed before leaving the unformatted input function.
 ``` cpp
 streamsize gcount() const;
 ```
 *Effects:* None. This member function does not behave as an unformatted
-input function (as described in  [[istream.unformatted]], paragraph 1).
 *Returns:* The number of characters extracted by the last unformatted
 input member function called for the object.
 ``` cpp
 int_type get();
 ```
 *Effects:* Behaves as an unformatted input function (as described
-in  [[istream.unformatted]], paragraph 1). After constructing a sentry
-object, extracts a character `c`, if one is available. Otherwise, the
-function calls `setstate(failbit)`, which may throw
-`ios_base::failure` ([[iostate.flags]]),
 *Returns:* `c` if available, otherwise `traits::eof()`.
 ``` cpp
 basic_istream<charT, traits>& get(char_type& c);
 ```
 *Effects:* Behaves as an unformatted input function (as described
-in  [[istream.unformatted]], paragraph 1). After constructing a sentry
-object, extracts a character, if one is available, and assigns it to
-`c`.[^23] Otherwise, the function calls `setstate(failbit)` (which may
-throw `ios_base::failure` ([[iostate.flags]])).
 *Returns:* `*this`.
 ``` cpp
-basic_istream<charT,traits>& get(char_type* s, streamsize n,
-                  char_type delim );
 ```
 *Effects:* Behaves as an unformatted input function (as described
-in  [[istream.unformatted]], paragraph 1). After constructing a sentry
-object, extracts characters and stores them into successive locations of
-an array whose first element is designated by `s`.[^24] Characters are
-extracted and stored until any of the following occurs:
 - `n` is less than one or `n - 1` characters are stored;
 - end-of-file occurs on the input sequence (in which case the function
   calls `setstate(eofbit)`);
 - `traits::eq(c, delim)` for the next available input character `c` (in
@@ -79,24 +77,22 @@ next successive location of the array.
 ``` cpp
 basic_istream<charT, traits>& get(char_type* s, streamsize n);
 ```
-*Effects:* Calls `get(s,n,widen(’\n’))`
 *Returns:* Value returned by the call.
 ``` cpp
-basic_istream<charT,traits>& get(basic_streambuf<char_type,traits>& sb,
-                  char_type delim );
 ```
 *Effects:* Behaves as an unformatted input function (as described
-in  [[istream.unformatted]], paragraph 1). After constructing a sentry
-object, extracts characters and inserts them in the output sequence
-controlled by `sb`. Characters are extracted and inserted until any of
-the following occurs:
 - end-of-file occurs on the input sequence;
 - inserting in the output sequence fails (in which case the character to
   be inserted is not extracted);
 - `traits::eq(c, delim)` for the next available input character `c` (in
@@ -111,44 +107,45 @@ which may throw `ios_base::failure` ([[iostate.flags]]).
 ``` cpp
 basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb);
 ```
-*Effects:* Calls `get(sb, widen(’\n’))`
 *Returns:* Value returned by the call.
 ``` cpp
-basic_istream<charT,traits>& getline(char_type* s, streamsize n,
-                      char_type delim);
 ```
 *Effects:* Behaves as an unformatted input function (as described
-in  [[istream.unformatted]], paragraph 1). After constructing a sentry
-object, extracts characters and stores them into successive locations of
-an array whose first element is designated by `s`.[^25] Characters are
-extracted and stored until one of the following occurs:
 1.  end-of-file occurs on the input sequence (in which case the function
     calls `setstate(eofbit)`);
 2.  `traits::eq(c, delim)` for the next available input character `c`
     (in which case the input character is extracted but not
-    stored);[^26]
 3.  `n` is less than one or `n - 1` characters are stored (in which case
     the function calls `setstate(failbit)`).
-These conditions are tested in the order shown.[^27]
 If the function extracts no characters, it calls `setstate(failbit)`
-(which may throw `ios_base::failure` ([[iostate.flags]])).[^28]
 In any case, if `n` is greater than zero, it then stores a null
 character (using `charT()`) into the next successive location of the
 array.
 *Returns:* `*this`.
 ``` cpp
 #include <iostream>
 int main() {
   using namespace std;
@@ -170,27 +167,28 @@ int main() {
     cout << " (" << count << " chars): " << buffer << endl;
   }
 }
 ```
 ``` cpp
 basic_istream<charT, traits>& getline(char_type* s, streamsize n);
 ```
 *Returns:* `getline(s, n, widen(’\n’))`
 ``` cpp
-basic_istream<charT,traits>&
-    ignore(streamsize n = 1, int_type delim = traits::eof());
 ```
 *Effects:* Behaves as an unformatted input function (as described
-in  [[istream.unformatted]], paragraph 1). After constructing a sentry
-object, extracts characters and discards them. Characters are extracted
-until any of the following occurs:
-- `n != numeric_limits<streamsize>::max()` ([[limits]]) and `n`
   characters have been extracted so far
 - end-of-file occurs on the input sequence (in which case the function
   calls `setstate(eofbit)`, which may throw
   `ios_base::failure` ([[iostate.flags]]));
 - `traits::eq_int_type(traits::to_int_type(c), delim)` for the next
@@ -204,27 +202,26 @@ until any of the following occurs:
 ``` cpp
 int_type peek();
 ```
 *Effects:* Behaves as an unformatted input function (as described
-in  [[istream.unformatted]], paragraph 1). After constructing a sentry
-object, reads but does not extract the current input character.
 *Returns:* `traits::eof()` if `good()` is `false`. Otherwise, returns
 `rdbuf()->sgetc()`.
 ``` cpp
 basic_istream<charT, traits>& read(char_type* s, streamsize n);
 ```
 *Effects:* Behaves as an unformatted input function (as described
-in  [[istream.unformatted]], paragraph 1). After constructing a sentry
-object, if `!good()` calls `setstate(failbit)` which may throw an
-exception, and return. Otherwise extracts characters and stores them
-into successive locations of an array whose first element is designated
-by `s`.[^29] Characters are extracted and stored until either of the
-following occurs:
 - `n` characters are stored;
 - end-of-file occurs on the input sequence (in which case the function
   calls `setstate(failbit | eofbit)`, which may throw
   `ios_base::failure` ([[iostate.flags]])).
@@ -234,17 +231,16 @@ following occurs:
 ``` cpp
 streamsize readsome(char_type* s, streamsize n);
 ```
 *Effects:* Behaves as an unformatted input function (as described
-in  [[istream.unformatted]], paragraph 1). After constructing a sentry
-object, if `!good()` calls `setstate(failbit)` which may throw an
-exception, and return. Otherwise extracts characters and stores them
-into successive locations of an array whose first element is designated
-by `s`. If `rdbuf()->in_avail() == -1`, calls `setstate(eofbit)` (which
-may throw `ios_base::failure` ([[iostate.flags]])), and extracts no
-characters;
 - If `rdbuf()->in_avail() == 0`, extracts no characters
 - If `rdbuf()->in_avail() > 0`, extracts `min(rdbuf()->in_avail(), n))`.
 *Returns:* The number of characters extracted.
@@ -252,86 +248,87 @@ characters;
 ``` cpp
 basic_istream<charT, traits>& putback(char_type c);
 ```
 *Effects:* Behaves as an unformatted input function (as described
-in  [[istream.unformatted]], paragraph 1), except that the function
-first clears `eofbit`. After constructing a sentry object, if `!good()`
-calls `setstate(failbit)` which may throw an exception, and return. If
-`rdbuf()` is not null, calls `rdbuf->sputbackc()`. If `rdbuf()` is null,
-or if `sputbackc()` returns `traits::eof()`, calls `setstate(badbit)`
-(which may throw `ios_base::failure` ([[iostate.flags]])). This
-function extracts no characters, so the value returned by the next call
-to `gcount()` is 0.
 *Returns:* `*this`.
 ``` cpp
 basic_istream<charT, traits>& unget();
 ```
 *Effects:* Behaves as an unformatted input function (as described
-in  [[istream.unformatted]], paragraph 1), except that the function
-first clears `eofbit`. After constructing a sentry object, if `!good()`
-calls `setstate(failbit)` which may throw an exception, and return. If
-`rdbuf()` is not null, calls `rdbuf()->sungetc()`. If `rdbuf()` is null,
-or if `sungetc()` returns `traits::eof()`, calls `setstate(badbit)`
-(which may throw `ios_base::failure` ([[iostate.flags]])). This
-function extracts no characters, so the value returned by the next call
-to `gcount()` is 0.
 *Returns:* `*this`.
 ``` cpp
 int sync();
 ```
 *Effects:* Behaves as an unformatted input function (as described
-in  [[istream.unformatted]], paragraph 1), except that it does not count
-the number of characters extracted and does not affect the value
-returned by subsequent calls to `gcount()`. After constructing a sentry
-object, if `rdbuf()` is a null pointer, returns -1 . Otherwise, calls
-`rdbuf()->pubsync()` and, if that function returns -1 calls
-`setstate(badbit)` (which may throw
 `ios_base::failure` ([[iostate.flags]]), and returns `-1`. Otherwise,
 returns zero.
 ``` cpp
 pos_type tellg();
 ```
 *Effects:* Behaves as an unformatted input function (as described
-in  [[istream.unformatted]], paragraph 1), except that it does not count
-the number of characters extracted and does not affect the value
-returned by subsequent calls to `gcount()`.
 *Returns:* After constructing a sentry object, if `fail() != false`,
 returns `pos_type(-1)` to indicate failure. Otherwise, returns
 `rdbuf()->pubseekoff(0, cur, in)`.
 ``` cpp
 basic_istream<charT, traits>& seekg(pos_type pos);
 ```
 *Effects:* Behaves as an unformatted input function (as described
-in  [[istream.unformatted]], paragraph 1), except that the function
-first clears `eofbit`, it does not count the number of characters
-extracted, and it does not affect the value returned by subsequent calls
-to `gcount()`. After constructing a sentry object, if `fail() != true`,
-executes `rdbuf()->pubseekpos(pos, ios_base::in)`. In case of failure,
-the function calls `setstate(failbit)` (which may throw
 `ios_base::failure`).
 *Returns:* `*this`.
 ``` cpp
 basic_istream<charT, traits>& seekg(off_type off, ios_base::seekdir dir);
 ```
 *Effects:* Behaves as an unformatted input function (as described
-in  [[istream.unformatted]], paragraph 1), except that it does not count
-the number of characters extracted and does not affect the value
 returned by subsequent calls to `gcount()`. After constructing a sentry
 object, if `fail() != true`, executes
 `rdbuf()->pubseekoff(off, dir, ios_base::in)`. In case of failure, the
 function calls `setstate(failbit)` (which may throw
 `ios_base::failure`).

 Each unformatted input function begins execution by constructing an
 object of class `sentry` with the default argument `noskipws` (second)
 argument `true`. If the `sentry` object returns `true`, when converted
 to a value of type `bool`, the function endeavors to obtain the
 requested input. Otherwise, if the sentry constructor exits by throwing
+an exception or if the sentry object returns `false`, when converted to
+a value of type `bool`, the function returns without attempting to
+obtain any input. In either case the number of extracted characters is
+set to 0; unformatted input functions taking a character array of
+nonzero size as an argument shall also store a null character (using
+`charT()`) in the first location of the array. If an exception is thrown
+during input then `ios::badbit` is turned on[^23] in `*this`’s error
+state. (Exceptions thrown from `basic_ios<>::clear()` are not caught or
 rethrown.) If `(exceptions()&badbit) != 0` then the exception is
 rethrown. It also counts the number of characters extracted. If no
 exception has been thrown it ends by storing the count in a member
 object and returning the value specified. In any event the `sentry`
 object is destroyed before leaving the unformatted input function.
 ``` cpp
 streamsize gcount() const;
 ```
 *Effects:* None. This member function does not behave as an unformatted
+input function (as described above).
 *Returns:* The number of characters extracted by the last unformatted
 input member function called for the object.
 ``` cpp
 int_type get();
 ```
 *Effects:* Behaves as an unformatted input function (as described
+above). After constructing a sentry object, extracts a character `c`, if
+one is available. Otherwise, the function calls `setstate(failbit)`,
+which may throw `ios_base::failure` ([[iostate.flags]]),
 *Returns:* `c` if available, otherwise `traits::eof()`.
 ``` cpp
 basic_istream<charT, traits>& get(char_type& c);
 ```
 *Effects:* Behaves as an unformatted input function (as described
+above). After constructing a sentry object, extracts a character, if one
+is available, and assigns it to `c`.[^24] Otherwise, the function calls
+`setstate(failbit)` (which may throw
+`ios_base::failure` ([[iostate.flags]])).
 *Returns:* `*this`.
 ``` cpp
+basic_istream<charT, traits>& get(char_type* s, streamsize n, char_type delim);
 ```
 *Effects:* Behaves as an unformatted input function (as described
+above). After constructing a sentry object, extracts characters and
+stores them into successive locations of an array whose first element is
+designated by `s`.[^25] Characters are extracted and stored until any of
+the following occurs:
 - `n` is less than one or `n - 1` characters are stored;
 - end-of-file occurs on the input sequence (in which case the function
   calls `setstate(eofbit)`);
 - `traits::eq(c, delim)` for the next available input character `c` (in
 ``` cpp
 basic_istream<charT, traits>& get(char_type* s, streamsize n);
 ```
+*Effects:* Calls `get(s, n, widen(’\n’))`.
 *Returns:* Value returned by the call.
 ``` cpp
+basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb, char_type delim);
 ```
 *Effects:* Behaves as an unformatted input function (as described
+above). After constructing a sentry object, extracts characters and
+inserts them in the output sequence controlled by `sb`. Characters are
+extracted and inserted until any of the following occurs:
 - end-of-file occurs on the input sequence;
 - inserting in the output sequence fails (in which case the character to
   be inserted is not extracted);
 - `traits::eq(c, delim)` for the next available input character `c` (in
 ``` cpp
 basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb);
 ```
+*Effects:* Calls `get(sb, widen(’\n’))`.
 *Returns:* Value returned by the call.
 ``` cpp
+basic_istream<charT, traits>& getline(char_type* s, streamsize n, char_type delim);
 ```
 *Effects:* Behaves as an unformatted input function (as described
+above). After constructing a sentry object, extracts characters and
+stores them into successive locations of an array whose first element is
+designated by `s`.[^26] Characters are extracted and stored until one of
+the following occurs:
 1.  end-of-file occurs on the input sequence (in which case the function
     calls `setstate(eofbit)`);
 2.  `traits::eq(c, delim)` for the next available input character `c`
     (in which case the input character is extracted but not
+    stored);[^27]
 3.  `n` is less than one or `n - 1` characters are stored (in which case
     the function calls `setstate(failbit)`).
+These conditions are tested in the order shown.[^28]
 If the function extracts no characters, it calls `setstate(failbit)`
+(which may throw `ios_base::failure` ([[iostate.flags]])).[^29]
 In any case, if `n` is greater than zero, it then stores a null
 character (using `charT()`) into the next successive location of the
 array.
 *Returns:* `*this`.
+[*Example 1*:
 ``` cpp
 #include <iostream>
 int main() {
   using namespace std;
     cout << " (" << count << " chars): " << buffer << endl;
   }
 }
 ```
+— *end example*]
 ``` cpp
 basic_istream<charT, traits>& getline(char_type* s, streamsize n);
 ```
 *Returns:* `getline(s, n, widen(’\n’))`
 ``` cpp
+basic_istream<charT, traits>& ignore(streamsize n = 1, int_type delim = traits::eof());
 ```
 *Effects:* Behaves as an unformatted input function (as described
+above). After constructing a sentry object, extracts characters and
+discards them. Characters are extracted until any of the following
+occurs:
+- `n != numeric_limits<streamsize>::max()` ([[numeric.limits]]) and `n`
   characters have been extracted so far
 - end-of-file occurs on the input sequence (in which case the function
   calls `setstate(eofbit)`, which may throw
   `ios_base::failure` ([[iostate.flags]]));
 - `traits::eq_int_type(traits::to_int_type(c), delim)` for the next
 ``` cpp
 int_type peek();
 ```
 *Effects:* Behaves as an unformatted input function (as described
+above). After constructing a sentry object, reads but does not extract
+the current input character.
 *Returns:* `traits::eof()` if `good()` is `false`. Otherwise, returns
 `rdbuf()->sgetc()`.
 ``` cpp
 basic_istream<charT, traits>& read(char_type* s, streamsize n);
 ```
 *Effects:* Behaves as an unformatted input function (as described
+above). After constructing a sentry object, if `!good()` calls
+`setstate(failbit)` which may throw an exception, and return. Otherwise
+extracts characters and stores them into successive locations of an
+array whose first element is designated by `s`.[^30] Characters are
+extracted and stored until either of the following occurs:
 - `n` characters are stored;
 - end-of-file occurs on the input sequence (in which case the function
   calls `setstate(failbit | eofbit)`, which may throw
   `ios_base::failure` ([[iostate.flags]])).
 ``` cpp
 streamsize readsome(char_type* s, streamsize n);
 ```
 *Effects:* Behaves as an unformatted input function (as described
+above). After constructing a sentry object, if `!good()` calls
+`setstate(failbit)` which may throw an exception, and return. Otherwise
+extracts characters and stores them into successive locations of an
+array whose first element is designated by `s`. If
+`rdbuf()->in_avail() == -1`, calls `setstate(eofbit)` (which may throw
+`ios_base::failure` ([[iostate.flags]])), and extracts no characters;
 - If `rdbuf()->in_avail() == 0`, extracts no characters
 - If `rdbuf()->in_avail() > 0`, extracts `min(rdbuf()->in_avail(), n))`.
 *Returns:* The number of characters extracted.
 ``` cpp
 basic_istream<charT, traits>& putback(char_type c);
 ```
 *Effects:* Behaves as an unformatted input function (as described
+above), except that the function first clears `eofbit`. After
+constructing a sentry object, if `!good()` calls `setstate(failbit)`
+which may throw an exception, and return. If `rdbuf()` is not null,
+calls `rdbuf->sputbackc()`. If `rdbuf()` is null, or if `sputbackc()`
+returns `traits::eof()`, calls `setstate(badbit)` (which may throw
+`ios_base::failure` ([[iostate.flags]])).
+[*Note 1*: This function extracts no characters, so the value returned
+by the next call to `gcount()` is 0. — *end note*]
 *Returns:* `*this`.
 ``` cpp
 basic_istream<charT, traits>& unget();
 ```
 *Effects:* Behaves as an unformatted input function (as described
+above), except that the function first clears `eofbit`. After
+constructing a sentry object, if `!good()` calls `setstate(failbit)`
+which may throw an exception, and return. If `rdbuf()` is not null,
+calls `rdbuf()->sungetc()`. If `rdbuf()` is null, or if `sungetc()`
+returns `traits::eof()`, calls `setstate(badbit)` (which may throw
+`ios_base::failure` ([[iostate.flags]])).
+[*Note 2*: This function extracts no characters, so the value returned
+by the next call to `gcount()` is 0. — *end note*]
 *Returns:* `*this`.
 ``` cpp
 int sync();
 ```
 *Effects:* Behaves as an unformatted input function (as described
+above), except that it does not count the number of characters extracted
+and does not affect the value returned by subsequent calls to
+`gcount()`. After constructing a sentry object, if `rdbuf()` is a null
+pointer, returns `-1`. Otherwise, calls `rdbuf()->pubsync()` and, if
+that function returns `-1` calls `setstate(badbit)` (which may throw
 `ios_base::failure` ([[iostate.flags]]), and returns `-1`. Otherwise,
 returns zero.
 ``` cpp
 pos_type tellg();
 ```
 *Effects:* Behaves as an unformatted input function (as described
+above), except that it does not count the number of characters extracted
+and does not affect the value returned by subsequent calls to
+`gcount()`.
 *Returns:* After constructing a sentry object, if `fail() != false`,
 returns `pos_type(-1)` to indicate failure. Otherwise, returns
 `rdbuf()->pubseekoff(0, cur, in)`.
 ``` cpp
 basic_istream<charT, traits>& seekg(pos_type pos);
 ```
 *Effects:* Behaves as an unformatted input function (as described
+above), except that the function first clears `eofbit`, it does not
+count the number of characters extracted, and it does not affect the
+value returned by subsequent calls to `gcount()`. After constructing a
+sentry object, if `fail() != true`, executes
+`rdbuf()->pubseekpos(pos, ios_base::in)`. In case of failure, the
+function calls `setstate(failbit)` (which may throw
 `ios_base::failure`).
 *Returns:* `*this`.
 ``` cpp
 basic_istream<charT, traits>& seekg(off_type off, ios_base::seekdir dir);
 ```
 *Effects:* Behaves as an unformatted input function (as described
+above), except that the function first clears `eofbit`, does not count
+the number of characters extracted, and does not affect the value
 returned by subsequent calls to `gcount()`. After constructing a sentry
 object, if `fail() != true`, executes
 `rdbuf()->pubseekoff(off, dir, ios_base::in)`. In case of failure, the
 function calls `setstate(failbit)` (which may throw
 `ios_base::failure`).

Diff to HTML by rtfpessoa