Requirements
A UnformattedOutputFunction is a stream output function that performs the following:
1) Constructs an object of type
basic_ostream::sentry with automatic storage duration, which performs the following:
- If
eofbitorbadbitare set on the output stream, sets thefailbitas well, and if exceptions onfailbitare enabled in this output stream's exception mask ((exceptions() & failbit) != 0), throwsios_base::failure. - Flushes the tie()'d output stream, if applicable.
2) Checks the status of the sentry by calling
sentry::operator bool(), which is equivalent to basic_ios::good.
- If the operator returns
falseor sentry's constructor throws an exception, no output takes place. - If the operator returns
true, attempts to perform the desired output by inserting the characters into the output stream as if by callingrdbuf()->sputc(). Other public members of std::basic_ostream may also be used, but virtual members ofrdbuf()exceptoverflow(),xsputn()andsync()will never be called.
- If an exception is thrown during output, sets
badbitin the output stream. If exceptions onbadbitare enabled in this stream's exception mask ((exceptions() & badbit) != 0), the exception is also rethrown. - If no exception was thrown, returns the value specified by the function.
- If an exception is thrown during output, sets
3) In any event, whether terminating by exception or returning, the sentry's destructor is called before leaving this function.
Standard library
The following standard library functions are UnformattedOutputFunctions.
-
basic_ostream::operator<<(basic_streambuf*) -
basic_ostream::put -
basic_ostream::write -
basic_ostream::flush
|
(since C++11) |
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 63 | C++98 | the exception-handling policy was missing | added |
| LWG 160 | C++98 | the process of determining whether the exception caught is rethrown mentioned a non-existing function exception()
|
corrected to exceptions()
|
| LWG 165 | C++98 | the only virtual member allowed to be called on rdbuf() was overflow()
|
also allowedxsputn() and sync()
|
Content from this page on cppreference.com, licensed under CC-BY-SA 3.0 and GFDL. Modified: restyled, site navigation removed, code windows added. Offline snapshot of 9 February 2025.