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.
traits_type | Traits |
(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) |
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(failbit)
(since c++11) 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() & 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(failbit | eofbit)
(which may throw std::ios_base::failure
).
Additional implementation-defined preparation may take place, which may call setstate(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
.
is | - | input stream to prepare |
noskipws | - | true if whitespace should not be skipped |
std::ios_base::failure
if the end of file condition occurs when skipping whitespace.
~sentry(); |
Does nothing.
explicit operator bool() const; |
Checks whether the preparation of the input stream was successful.
(none).
true
if the initialization of the input stream was successful, false
otherwise.
#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
extracts formatted data (public member function) |
|
extracts characters and character arrays (function template) |
© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
http://en.cppreference.com/w/cpp/io/basic_istream/sentry