30 Input/output library [input.output]

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.

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().

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.311 Otherwise, the function calls setstate(failbit) (which may throw ios_­base​::​failure ([iostate.flags])).

Returns: *this.

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.312 Characters are extracted and stored until any of the following occurs:

• (8.1)

  n is less than one or n - 1 characters are stored;

• (8.2)

  end-of-file occurs on the input sequence (in which case the function calls setstate(eofbit));

• (8.3)

  traits​::​eq(c, delim) for the next available input character c (in which case c is not extracted).

If the function stores no characters, it calls setstate(failbit) (which may throw ios_­base​::​​failure ([iostate.flags])). In any case, if n is greater than zero it then stores a null character into the next successive location of the array.

Returns: *this.

Effects: Calls get(s, n, widen('\n')).

Returns: Value returned by the call.

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:

• (13.1)

  end-of-file occurs on the input sequence;

• (13.2)

  inserting in the output sequence fails (in which case the character to be inserted is not extracted);

• (13.3)

  traits​::​eq(c, delim) for the next available input character c (in which case c is not extracted);

• (13.4)

  an exception occurs (in which case, the exception is caught but not rethrown).

If the function inserts no characters, it calls setstate(failbit), which may throw ios_­base​::​​failure ([iostate.flags]).

Returns: *this.

Effects: Calls get(sb, widen('\n')).

Returns: Value returned by the call.

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.313 Characters are extracted and stored until one of the following occurs:

1. 1.end-of-file occurs on the input sequence (in which case the function calls setstate(eofbit));

2. 2.traits​::​eq(c, delim) for the next available input character c (in which case the input character is extracted but not stored);314

3. 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.315

If the function extracts no characters, it calls setstate(failbit) (which may throw ios_­base​::​​failure ([iostate.flags])).316

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:

#include <iostream>

int main() {
  using namespace std;
  const int line_buffer_size = 100;

  char buffer[line_buffer_size];
  int line_number = 0;
  while (cin.getline(buffer, line_buffer_size, '\n') || cin.gcount()) {
    int count = cin.gcount();
    if (cin.eof())
      cout << "Partial final line";   // cin.fail() is false
    else if (cin.fail()) {
      cout << "Partial long line";
      cin.clear(cin.rdstate() & ~ios_base::failbit);
    } else {
      count--;                        // Don't include newline in count
      cout << "Line " << ++line_number;
    }
    cout << " (" << count << " chars): " << buffer << endl;
  }
}

 — end example ]

Returns: getline(s, n, widen('\n'))

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:

• (25.1)

  n != numeric_­limits<streamsize>​::​max() and n characters have been extracted so far

• (25.2)

  end-of-file occurs on the input sequence (in which case the function calls setstate(eofbit), which may throw ios_­base​::​failure ([iostate.flags]));

• (25.3)

  traits​::​eq_­int_­type(traits​::​to_­int_­type(c), delim) for the next available input character c (in which case c is extracted).

Remarks: The last condition will never occur if traits​::​eq_­int_­type(delim, traits​::​eof()).

Returns: *this.

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().

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.317 Characters are extracted and stored until either of the following occurs:

• (30.1)

  n characters are stored;

• (30.2)

  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])).

Returns: *this.

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;

• (32.1)

  If rdbuf()->in_­avail() == 0, extracts no characters

• (32.2)

  If rdbuf()->in_­avail() > 0, extracts min(rdbuf()->in_­avail(), n)).

Returns: The number of characters extracted.

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: This function extracts no characters, so the value returned by the next call to gcount() is 0.  — end note ]

Returns: *this.

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: This function extracts no characters, so the value returned by the next call to gcount() is 0.  — end note ]

Returns: *this.

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.

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).

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.

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).

Returns: *this.

Effects: Behaves as an unformatted input function, except that it does not count the number of characters extracted and does not affect the value returned by subsequent calls to is.gcount(). After constructing a sentry object extracts characters as long as the next available character c is whitespace or until there are no more characters in the sequence. Whitespace characters are distinguished with the same criterion as used by sentry​::​sentry. If ws stops extracting characters because there are no more available it sets eofbit, but not failbit.

Returns: is.

Effects: Equivalent to:

is >> std::forward<T>(x);
return is;

Remarks: This function shall not participate in overload resolution unless the expression is >> std​::​forward<T>(x) is well-formed.