std::basic_istream<CharT,Traits>::sentry
| class sentry; |
||
An object of class basic_istream::sentry is constructed in local scope at the beginning of each member function of std::basic_istream that performs input (both formatted and unformatted). Its constructor prepares the input stream: checks if the stream is already in a failed state, flushes the tie()'d output streams, skips leading whitespace unless noskipws flag is set, and performs other implementation-defined tasks if necessary. All cleanup, if necessary, is performed in the destructor, so that it is guaranteed to happen if exceptions are thrown during input.
Contents |
[edit] Member types
traits_type
|
Traits
|
[edit] Member functions
| (constructor) |
constructs the sentry object. All the preparation tasks are done here (public member function) |
| (destructor) |
finalizes the stream object after formatted input or after exception, if necessary (public member function) |
| operator= [deleted] |
not copy assignable (public member function) |
| operator bool |
checks if the preparation of the stream object was successful (public member function) |
std::basic_istream::sentry::sentry
| explicit sentry( std::basic_istream<CharT, Traits>& is, bool noskipws = false ); |
||
Prepares the stream for formatted input.
If is.good() is false, calls is.setstate(std::ios_base::failbit) and returns. Otherwise, if is.tie() is not a null pointer, calls is.tie()->flush() to synchronize the output sequence with external streams. This call can be suppressed if the put area of is.tie() is empty. The implementation may defer the call to flush() until a call of is.rdbuf()->underflow() occurs. If no such call occurs before the sentry object is destroyed, it may be eliminated entirely.
If noskipws is zero and is.flags() & std::ios_base::skipws is nonzero, the function extracts and discards all whitespace characters until the next available character is not a whitespace character (as determined by the currently imbued locale in is). If is.rdbuf()->sbumpc() or is.rdbuf()->sgetc() returns traits::eof(), the function calls setstate(std::ios_base::failbit | std::ios_base::eofbit) (which may throw std::ios_base::failure).
Additional implementation-defined preparation may take place, which may call setstate(std::ios_base::failbit) (which may throw std::ios_base::failure).
If after preparation is completed, is.good() == true, then any subsequent calls to operator bool will return true.
Parameters
| is | - | input stream to prepare |
| noskipws | - | true if whitespace should not be skipped |
Exceptions
std::ios_base::failure if the end of file condition occurs when skipping whitespace.
std::basic_istream::sentry::~sentry
| ~sentry(); |
||
Does nothing.
std::basic_istream::sentry::operator bool
| explicit operator bool() const; |
||
Checks whether the preparation of the input stream was successful.
Parameters
(none)
Return value
true if the initialization of the input stream was successful, false otherwise.
[edit] Example
#include <iostream> #include <sstream> struct Foo { char n[5]; }; std::istream& operator>>(std::istream& is, Foo& f) { std::istream::sentry s(is); if (s) is.read(f.n, 5); return is; } int main() { std::string input = " abcde"; std::istringstream stream(input); Foo f; stream >> f; std::cout.write(f.n, 5); std::cout << '\n'; }
Output:
abcde
[edit] Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| LWG 195 | C++98 | it was unclear whether the constructor would set eofbit
|
made clear |
| LWG 419 | C++98 | the constructor did not set failbit if eofbit has been set
|
sets failbit in this case
|
[edit] See also
| extracts formatted data (public member function) | |
| extracts characters and character arrays (function template) |
