[ostream] # 31 Input/output library [[input.output]](./#input.output) ## 31.7 Formatting and manipulators [[iostream.format]](iostream.format#ostream) ### 31.7.6 Output streams [[output.streams]](output.streams#ostream) #### 31.7.6.2 Class template basic_ostream [ostream] #### [31.7.6.2.1](#general) General [[ostream.general]](ostream.general) [1](#general-1) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L5921) When a function has a parameter type *extended-floating-point-type*, the implementation provides overloads for all cv-unqualified extended floating-point types ([[basic.fundamental]](basic.fundamental "6.9.2 Fundamental types"))[.](#general-1.sentence-1) [🔗](#lib:basic_ostream) namespace std {template>class basic_ostream : virtual public basic_ios {public:// types (inherited from [basic_ios](ios "31.5.4 Class template basic_­ios [ios]"))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; // [[ostream.cons]](#cons "31.7.6.2.2 Constructors"), constructor/destructorexplicit basic_ostream(basic_streambuf* sb); virtual ~basic_ostream(); // [[ostream.sentry]](#sentry "31.7.6.2.4 Class basic_­ostream​::​sentry"), prefix/suffixclass sentry; // [[ostream.formatted]](ostream.formatted "31.7.6.3 Formatted output functions"), formatted output basic_ostream& operator<<(basic_ostream& (*pf)(basic_ostream&)); basic_ostream& operator<<(basic_ios& (*pf)(basic_ios&)); basic_ostream& operator<<(ios_base& (*pf)(ios_base&)); basic_ostream& operator<<(bool n); basic_ostream& operator<<(short n); basic_ostream& operator<<(unsigned short n); basic_ostream& operator<<(int n); basic_ostream& operator<<(unsigned int n); basic_ostream& operator<<(long n); basic_ostream& operator<<(unsigned long n); basic_ostream& operator<<(long long n); basic_ostream& operator<<(unsigned long long n); basic_ostream& operator<<(float f); basic_ostream& operator<<(double f); basic_ostream& operator<<(long double f); basic_ostream& operator<<(*extended-floating-point-type* f); basic_ostream& operator<<(const void* p); basic_ostream& operator<<(const volatile void* p); basic_ostream& operator<<(nullptr_t); basic_ostream& operator<<(basic_streambuf* sb); // [[ostream.unformatted]](ostream.unformatted "31.7.6.4 Unformatted output functions"), unformatted output basic_ostream& put(char_type c); basic_ostream& write(const char_type* s, streamsize n); basic_ostream& flush(); // [[ostream.seeks]](#seeks "31.7.6.2.5 Seek members"), seeks pos_type tellp(); basic_ostream& seekp(pos_type); basic_ostream& seekp(off_type, ios_base::seekdir); protected:// [[ostream.cons]](#cons "31.7.6.2.2 Constructors"), copy/move constructor basic_ostream(const basic_ostream&) = delete; basic_ostream(basic_ostream&& rhs); // [[ostream.assign]](#assign "31.7.6.2.3 Assignment and swap"), assignment and swap basic_ostream& operator=(const basic_ostream&) = delete; basic_ostream& operator=(basic_ostream&& rhs); void swap(basic_ostream& rhs); }; // [[ostream.inserters.character]](ostream.inserters.character "31.7.6.3.4 Character inserter function templates"), character inserterstemplate basic_ostream& operator<<(basic_ostream&, charT); template basic_ostream& operator<<(basic_ostream&, char); template basic_ostream& operator<<(basic_ostream&, char); template basic_ostream& operator<<(basic_ostream&, signed char); template basic_ostream& operator<<(basic_ostream&, unsigned char); template basic_ostream& operator<<(basic_ostream&, wchar_t) = delete; template basic_ostream& operator<<(basic_ostream&, char8_t) = delete; template basic_ostream& operator<<(basic_ostream&, char16_t) = delete; template basic_ostream& operator<<(basic_ostream&, char32_t) = delete; template basic_ostream&operator<<(basic_ostream&, char8_t) = delete; template basic_ostream&operator<<(basic_ostream&, char16_t) = delete; template basic_ostream&operator<<(basic_ostream&, char32_t) = delete; template basic_ostream& operator<<(basic_ostream&, const charT*); template basic_ostream& operator<<(basic_ostream&, const char*); template basic_ostream& operator<<(basic_ostream&, const char*); template basic_ostream& operator<<(basic_ostream&, const signed char*); template basic_ostream& operator<<(basic_ostream&, const unsigned char*); template basic_ostream&operator<<(basic_ostream&, const wchar_t*) = delete; template basic_ostream&operator<<(basic_ostream&, const char8_t*) = delete; template basic_ostream&operator<<(basic_ostream&, const char16_t*) = delete; template basic_ostream&operator<<(basic_ostream&, const char32_t*) = delete; template basic_ostream&operator<<(basic_ostream&, const char8_t*) = delete; template basic_ostream&operator<<(basic_ostream&, const char16_t*) = delete; template basic_ostream&operator<<(basic_ostream&, const char32_t*) = delete;} [2](#general-2) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L6060) The class templatebasic_ostream defines a number of member function signatures that assist in formatting and writing output to output sequences controlled by a stream buffer[.](#general-2.sentence-1) [3](#general-3) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L6067) Two groups of member function signatures share common properties: the[*formatted output functions*](#def:formatted_output_functions) (or[*inserters*](#def:inserters)) and the[*unformatted output functions.*](#def:unformatted_output_functions.) Both groups of output functions generate (or[*insert*](#def:insert)) output[*characters*](#def:characters) by actions equivalent to callingrdbuf()->sputc(int_type)[.](#general-3.sentence-1) They may use other public members ofbasic_ostream except that they shall not invoke any virtual members ofrdbuf() exceptoverflow(),xsputn(), andsync()[.](#general-3.sentence-2) [4](#general-4) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L6091) If one of these called functions throws an exception, then unless explicitly noted otherwise the output function setsbadbit in the error state[.](#general-4.sentence-1) Ifbadbit is set inexceptions(), the output function rethrows the exception without completing its actions, otherwise it does not throw anything and proceeds as if the called function had returned a failure indication[.](#general-4.sentence-2) [5](#general-5) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L6105) [*Note [1](#general-note-1)*: The deleted overloads of operator<< prevent formatting characters as integers and strings as pointers[.](#general-5.sentence-1) — *end note*] #### [31.7.6.2.2](#cons) Constructors [[ostream.cons]](ostream.cons) [🔗](#lib:basic_ostream,constructor) `explicit basic_ostream(basic_streambuf* sb); ` [1](#cons-1) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L6120) *Effects*: Initializes the base class subobject withbasic_ios​::​init(sb) ([[basic.ios.cons]](basic.ios.cons "31.5.4.2 Constructors"))[.](#cons-1.sentence-1) [2](#cons-2) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L6125) *Postconditions*: rdbuf() == sb[.](#cons-2.sentence-1) [🔗](#lib:basic_ostream,constructor_) `basic_ostream(basic_ostream&& rhs); ` [3](#cons-3) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L6136) *Effects*: Move constructs from the rvalue rhs[.](#cons-3.sentence-1) This is accomplished by default constructing the base class and callingbasic_ios​::​move(rhs) to initialize the base class[.](#cons-3.sentence-2) [🔗](#lib:basic_ostream,destructor) `virtual ~basic_ostream(); ` [4](#cons-4) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L6150) *Remarks*: Does not perform any operations onrdbuf()[.](#cons-4.sentence-1) #### [31.7.6.2.3](#assign) Assignment and swap [[ostream.assign]](ostream.assign) [🔗](#lib:operator=,basic_ostream) `basic_ostream& operator=(basic_ostream&& rhs); ` [1](#assign-1) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L6164) *Effects*: Equivalent to swap(rhs)[.](#assign-1.sentence-1) [2](#assign-2) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L6168) *Returns*: *this[.](#assign-2.sentence-1) [🔗](#lib:swap,basic_ostream) `void swap(basic_ostream& rhs); ` [3](#assign-3) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L6179) *Effects*: Calls basic_ios​::​swap(rhs)[.](#assign-3.sentence-1) #### [31.7.6.2.4](#sentry) Class basic_ostream​::​sentry [[ostream.sentry]](ostream.sentry) [🔗](#lib:basic_ostream::sentry) namespace std {templateclass basic_ostream::sentry {bool *ok_*; // *exposition only*public:explicit sentry(basic_ostream& os); ~sentry(); explicit operator bool() const { return *ok_*; } sentry(const sentry&) = delete; sentry& operator=(const sentry&) = delete; };} [1](#sentry-1) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L6205) The classsentry defines a class that is responsible for doing exception safe prefix and suffix operations[.](#sentry-1.sentence-1) [🔗](#lib:basic_ostream::sentry,constructor) `explicit sentry(basic_ostream& os); ` [2](#sentry-2) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L6217) Ifos.good() is nonzero, prepares for formatted or unformatted output[.](#sentry-2.sentence-1) Ifos.tie() is not a null pointer, callsos.tie()->flush()[.](#sentry-2.sentence-2)[283](#footnote-283 "The call os.tie()->flush() does not necessarily occur if the function can determine that no synchronization is necessary.") [3](#sentry-3) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L6233) If, after any preparation is completed,os.good() istrue,*ok_* == true otherwise,*ok_* == false[.](#sentry-3.sentence-1) During preparation, the constructor may callsetstate(failbit) (which may throwios_base​::​​failure ([[iostate.flags]](iostate.flags "31.5.4.4 Flags functions")))[.](#sentry-3.sentence-2)[284](#footnote-284 "The sentry constructor and destructor can also perform additional implementation-dependent operations.") [🔗](#lib:basic_ostream::sentry,destructor) `~sentry(); ` [4](#sentry-4) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L6261) If(os.flags() & ios_base​::​unitbuf) && !uncaught_exceptions()&& os.good() istrue, callsos.rdbuf()->pubsync()[.](#sentry-4.sentence-1) If that function returns −1 or exits via an exception, sets badbit inos.rdstate() without propagating an exception[.](#sentry-4.sentence-2) [🔗](#lib:operator_bool,basic_ostream::sentry) `explicit operator bool() const; ` [5](#sentry-5) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L6279) *Effects*: Returns*ok_*[.](#sentry-5.sentence-1) [283)](#footnote-283)[283)](#footnoteref-283) The callos.tie()->flush() does not necessarily occur if the function can determine that no synchronization is necessary[.](#footnote-283.sentence-1) [284)](#footnote-284)[284)](#footnoteref-284) Thesentry constructor and destructor can also perform additionalimplementation-dependent operations[.](#footnote-284.sentence-1) #### [31.7.6.2.5](#seeks) Seek members [[ostream.seeks]](ostream.seeks) [1](#seeks-1) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L6287) Each seek member function begins execution by constructing an object of class sentry[.](#seeks-1.sentence-1) It returns by destroying the sentry object[.](#seeks-1.sentence-2) [🔗](#lib:tellp,basic_ostream) `pos_type tellp(); ` [2](#seeks-2) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L6297) *Returns*: Iffail() != false, returnspos_type(-1) to indicate failure[.](#seeks-2.sentence-1) Otherwise, returnsrdbuf()->​pubseekoff(​0, cur, out)[.](#seeks-2.sentence-2) [🔗](#lib:seekp,basic_ostream) `basic_ostream& seekp(pos_type pos); ` [3](#seeks-3) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L6314) *Effects*: Iffail() != true, executesrdbuf()->pubseekpos(pos, ios_base​::​out)[.](#seeks-3.sentence-1) In case of failure, the function callssetstate(failbit) (which may throwios_base​::​failure)[.](#seeks-3.sentence-2) [4](#seeks-4) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L6325) *Returns*: *this[.](#seeks-4.sentence-1) [🔗](#lib:seekp,basic_ostream_) `basic_ostream& seekp(off_type off, ios_base::seekdir dir); ` [5](#seeks-5) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L6336) *Effects*: Iffail() != true, executesrdbuf()->pubseekoff(off, dir, ios_base​::​out)[.](#seeks-5.sentence-1) In case of failure, the function calls setstate(failbit) (which may throw ios_base​::​failure)[.](#seeks-5.sentence-2) [6](#seeks-6) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L6345) *Returns*: *this[.](#seeks-6.sentence-1)