class sentry; |
An object of class basic_ostream::sentry is constructed in local scope at the beginning of each member function of std::basic_ostream that performs output (both formatted and unformatted). Its constructor prepares the output stream: checks if the stream is already in a failed state, flushes the tie()'d output streams, and performs other implementation-defined tasks if necessary. Implementation-defined cleanup, as well as flushing of the output stream if necessary, is performed in the destructor, so that it is guaranteed to happen if exceptions are thrown during output.
| (constructor) | constructs the sentry object. All the preparation tasks are done here (public member function) |
| (destructor) | finalizes the stream object after formatted output or after exception, if necessary (public member function) |
| operator= | the assignment operator is deleted (public member function) |
| operator bool | checks if the preparation of the stream object was successful (public member function) |
explicit sentry( std::basic_ostream<CharT, Traits>& os ); |
Prepares the stream for formatted output.
If os.good() is false, returns. Otherwise, if os.tie() is not a null pointer, calls os.tie()->flush() to synchronize the output sequence with external streams. During preparation, the constructor may call setstate(failbit) (which may throw std::ios_base::failure).
If after preparation is completed, os.good() == true, then any subsequent calls to operator bool will return true.
| os | - | output stream to prepare |
std::ios_base::failure if the end of file condition occurs.
~sentry(); |
If (os.flags() & std::ios_base::unitbuf) && !std::uncaught_exception() && os.good()) is true, calls os.rdbuf()->pubsync(). If that function returns -1, sets badbit in os.rdstate() without propagating an exception.
explicit operator bool() const; |
Checks whether the preparation of the output stream was successful.
(none).
true if the preparation of the output stream was successful, false otherwise.
#include <iostream>
#include <sstream>
struct Foo
{
char n[6];
};
std::ostream& operator<<(std::ostream& os, Foo& f)
{
std::ostream::sentry s(os);
if (s)
os.write(f.n, 5);
return os;
}
int main()
{
Foo f = {"abcde"};
std::cout << f << '\n';
}Output:
abcde
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| LWG 397 | C++98 | the destructor might call os.flush(), which may throw exceptions | the exception is not propagated |
| LWG 442 | C++98 | operator bool was not declared const (it is const in the synopsis) | added const |
| LWG 835 | C++98 | if os sets unitbuf, the destructor would call os.flush(), whichis an UnformattedOutputFunction and creates another sentry object (whose destructor then creates another sentry object and so on) | callsos.rdbuf()->pubsync()in this case instead |
| inserts formatted data (public member function) |
© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/cpp/io/basic_ostream/sentry