C++ named requirements: FormattedOutputFunction

 

C++

Compiler support

Freestanding and hosted

Language

Standard library

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Metaprogramming library (C++11)

Diagnostics library

General utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Concurrency support library (C++11)

Technical specifications

Symbols index

External libraries

 

C++ named requirements

Basic
DefaultConstructible CopyAssignable	CopyConstructible MoveAssignable (C++11)	MoveConstructible (C++11) Destructible
Type properties
ScalarType TriviallyCopyable (C++11)	StandardLayoutType (C++11) PODType	TrivialType (C++11) ImplicitLifetimeType
Library-Wide
EqualityComparable LessThanComparable Swappable ValueSwappable (C++11)	NullablePointer (C++11) Hash (C++11) Allocator FunctionObject	Callable Predicate BinaryPredicate Compare
Container
Container SequenceContainer ContiguousContainer (C++17)	ReversibleContainer AssociativeContainer AllocatorAwareContainer	UnorderedAssociativeContainer (C++11)
Container Elements
DefaultInsertable (C++11) CopyInsertable (C++11)	MoveInsertable (C++11) EmplaceConstructible (C++11)	Erasable (C++11)
Iterator
LegacyIterator LegacyOutputIterator LegacyInputIterator	LegacyForwardIterator LegacyBidirectionalIterator LegacyRandomAccessIterator	LegacyContiguousIterator (C++17) ConstexprIterator (C++20)
Stream I/O
FormattedInputFunction UnformattedInputFunction	FormattedOutputFunction	UnformattedOutputFunction
Formatters
BasicFormatter (C++20)	Formatter (C++20)
Random Numbers
SeedSequence (C++11) RandomNumberEngine (C++11)	RandomNumberDistribution (C++11) UniformRandomBitGenerator (C++11)	RandomNumberEngineAdaptor (C++11)
Concurrency
BasicLockable (C++11) Lockable (C++11) TimedLockable (C++11)	SharedLockable (C++14) SharedTimedLockable (C++14) Mutex (C++11)	TimedMutex (C++11) SharedMutex (C++17) SharedTimedMutex (C++14)
Ranges
RangeAdaptorObject (C++20)	RangeAdaptorClosureObject (C++20)
Other
CharTraits RegexTraits (C++11) BitmaskType LiteralType (C++11)	NumericType UnaryTypeTrait (C++11) BinaryTypeTrait (C++11) TransformationTrait (C++11)	Clock (C++11) TrivialClock (C++11)

 

Requirements

A FormattedOutputFunction is a stream output function that performs the following:

• Constructs an object of type basic_ostream::sentry with automatic storage duration, which performs the following

• if eofbit or badbit are set on the output stream, sets the failbit as well, and if exceptions on failbit are enabled in this output stream's exception mask ((exceptions() & failbit) != 0), throws ios_base::failure.
• flushes the tie()'d output stream, if applicable.

• Checks the status of the sentry by calling sentry::operator bool(), which is equivalent to basic_ios::good.
• If the sentry returned false or sentry's constructor threw an exception, no output takes place
• If the sentry returned true, attempts to perform the desired output by inserting the characters into the output stream as if by calling rdbuf()->sputc(). Other public members of std::basic_ostream may also be used, but virtual members of rdbuf() except overflow(), xsputn() and sync() will never be called.

• If the output could not be generated, sets failbit. If exceptions on failbit are enabled in this stream's exception mask ((exceptions() & failbit) != 0), throws ios_base::failure.
• if an exception is thrown during output, sets badbit in the output stream. If exceptions on badbit are enabled in this stream's exception mask ((exceptions() & badbit) != 0), the exception is also rethrown.
• If no exception was thrown, returns *this.

• In any event, whether terminating by exception or returning, the sentry's destructor is called before leaving this function.

Padding

Formatted output functions determine padding according to std::num_put::do_put() stage 3.

(until C++14)

If a formatted output function of a stream os determines padding, it does so as follows. Given a CharT character sequence seq where CharT is the character type of os, if the length of seq is less than os.width(), then enough copies of os.fill() are added to this sequence as necessary to pad to a width of os.width() characters. If (os.flags() & std::ios_base::adjustfield) == std::ios_base::left is true, the fill characters are placed after the character sequence; otherwise, they are placed before the character sequence.

(since C++14)

Standard library

The following standard library functions are FormattedOutputFunctions.

• basic_ostream::operator<<(std::basic_ostream&, int / long / double / void* / bool)
• operator<<(std::basic_ostream&, char)
• operator<<(std::basic_ostream&, char*)
• operator<<(std::basic_ostream&, const std::bitset&)
• operator<<(std::basic_ostream&, const std::basic_string&)
• operator<< , when called on the return value of std::put_money

operator<<(std::basic_ostream&, std::basic_string_view)

(since C++17)

print(std::ostream&, std::format_string<Args...>, Args&&...), println(std::ostream&, std::format_string<Args...>, Args&&...), vprint_unicode(std::ostream&, std::string_view, std::format_args), vprint_nonunicode(std::ostream&, std::string_view, std::format_args), except that (given os is an output stream object): any exception thrown by the call to std::vformat is propagated without regard to the value of os.exceptions() and without turning on ios_base::badbit in the error state of os; if inserting into os fails, calls os.setstate(ios_base::badbit) (which may throw ios_base::failure).

(since C++23)

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 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 allowed xsputn() and sync()