31 Input/output library [input.output]

31.11 Synchronized output streams [syncstream]

31.11.3 Class template basic_osyncstream [syncstream.osyncstream]

31.11.3.1 Overview [syncstream.osyncstream.overview]

namespace std { template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>> class basic_osyncstream : public basic_ostream<charT, traits> { public: using char_type = charT; using int_type = typename traits::int_type; using pos_type = typename traits::pos_type; using off_type = typename traits::off_type; using traits_type = traits; using allocator_type = Allocator; using streambuf_type = basic_streambuf<charT, traits>; using syncbuf_type = basic_syncbuf<charT, traits, Allocator>; // [syncstream.osyncstream.cons], construction and destruction basic_osyncstream(streambuf_type*, const Allocator&); explicit basic_osyncstream(streambuf_type* obuf) : basic_osyncstream(obuf, Allocator()) {} basic_osyncstream(basic_ostream<charT, traits>& os, const Allocator& allocator) : basic_osyncstream(os.rdbuf(), allocator) {} explicit basic_osyncstream(basic_ostream<charT, traits>& os) : basic_osyncstream(os, Allocator()) {} basic_osyncstream(basic_osyncstream&&) noexcept; ~basic_osyncstream(); // assignment basic_osyncstream& operator=(basic_osyncstream&&); // [syncstream.osyncstream.members], member functions void emit(); streambuf_type* get_wrapped() const noexcept; syncbuf_type* rdbuf() const noexcept { return const_cast<syncbuf_type*>(addressof(sb)); } private: syncbuf_type sb; // exposition only }; }

Allocator shall meet the Cpp17Allocator requirements ([allocator.requirements.general]).

[Example 1:

A named variable can be used within a block statement for streaming.

{ osyncstream bout(cout); bout << "Hello, "; bout << "World!"; bout << endl; // flush is noted bout << "and more!\n"; } // characters are transferred and cout is flushed — end example]

[Example 2:

A temporary object can be used for streaming within a single statement.

osyncstream(cout) << "Hello, " << "World!" << '\n';

In this example, cout is not flushed.

— end example]

31.11.3.2 Construction and destruction [syncstream.osyncstream.cons]

🔗

basic_osyncstream(streambuf_type* buf, const Allocator& allocator);

Effects: Initializes sb from buf and allocator.

Initializes the base class with basic_ostream<charT, traits>(addressof(sb)).

[Note 1:

The member functions of the provided stream buffer can be called from emit() while a lock is held, which might result in a deadlock if used incautiously.

— end note]

Postconditions: get_wrapped() == buf is true.

🔗

basic_osyncstream(basic_osyncstream&& other) noexcept;

Effects: Move constructs the base class and sb from the corresponding subobjects of other, and calls basic_ostream<charT, traits>::set_rdbuf(addressof(sb)).

Postconditions: The value returned by get_wrapped() is the value returned by other.get_wrapped() prior to calling this constructor.

nullptr == other.get_wrapped() is true.

31.11.3.3 Member functions [syncstream.osyncstream.members]

🔗

void emit();

Effects: Behaves as an unformatted output function ([ostream.unformatted]).

After constructing a sentry object, calls sb.emit().

If that call returns false, calls setstate(ios_base::badbit).

[Example 1:

A flush on a basic_osyncstream does not flush immediately: { osyncstream bout(cout); bout << "Hello," << '\n'; // no flush bout.emit(); // characters transferred; cout not flushed bout << "World!" << endl; // flush noted; cout not flushed bout.emit(); // characters transferred; cout flushed bout << "Greetings." << '\n'; // no flush } // characters transferred; cout not flushed

— end example]

[Example 2:

The function emit() can be used to handle exceptions from operations on the underlying stream.

{ osyncstream bout(cout); bout << "Hello, " << "World!" << '\n'; try { bout.emit(); } catch (...) { // handle exception } } — end example]

🔗

streambuf_type* get_wrapped() const noexcept;

Returns: sb.get_wrapped().

[Example 3:

Obtaining the wrapped stream buffer with get_wrapped() allows wrapping it again with an osyncstream.

For example, { osyncstream bout1(cout); bout1 << "Hello, "; { osyncstream(bout1.get_wrapped()) << "Goodbye, " << "Planet!" << '\n'; } bout1 << "World!" << '\n'; } produces the uninterleaved output

Goodbye, Planet!
Hello, World!

— end example]