cppdraft_translate/cppdraft/ostream.md

[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 charT, class traits = char_traits<charT>>class basic_ostream : virtual public basic_ios<charT, traits> {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<char_type, traits>* 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<charT, traits>& (*pf)(basic_ios<charT, traits>&));
 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<char_type, traits>* 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<class charT, class traits> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&, charT); template<class charT, class traits> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&, char); template<class traits> basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, char); template<class traits> basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, signed char); template<class traits> basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, unsigned char); template<class traits> basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, wchar_t) = delete; template<class traits> basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, char8_t) = delete; template<class traits> basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, char16_t) = delete; template<class traits> basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, char32_t) = delete; template<class traits> basic_ostream<wchar_t, traits>&operator<<(basic_ostream<wchar_t, traits>&, char8_t) = delete; template<class traits> basic_ostream<wchar_t, traits>&operator<<(basic_ostream<wchar_t, traits>&, char16_t) = delete; template<class traits> basic_ostream<wchar_t, traits>&operator<<(basic_ostream<wchar_t, traits>&, char32_t) = delete; template<class charT, class traits> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&, const charT*); template<class charT, class traits> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&, const char*); template<class traits> basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, const char*); template<class traits> basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, const signed char*); template<class traits> basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, const unsigned char*); template<class traits> basic_ostream<char, traits>&operator<<(basic_ostream<char, traits>&, const wchar_t*) = delete; template<class traits> basic_ostream<char, traits>&operator<<(basic_ostream<char, traits>&, const char8_t*) = delete; template<class traits> basic_ostream<char, traits>&operator<<(basic_ostream<char, traits>&, const char16_t*) = delete; template<class traits> basic_ostream<char, traits>&operator<<(basic_ostream<char, traits>&, const char32_t*) = delete; template<class traits> basic_ostream<wchar_t, traits>&operator<<(basic_ostream<wchar_t, traits>&, const char8_t*) = delete; template<class traits> basic_ostream<wchar_t, traits>&operator<<(basic_ostream<wchar_t, traits>&, const char16_t*) = delete; template<class traits> basic_ostream<wchar_t, traits>&operator<<(basic_ostream<wchar_t, traits>&, 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<charT, traits>* sb);
`

[1](#cons-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L6120)

*Effects*: Initializes the base class subobject withbasic_ios<charT, traits>​::​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<charT, traits>​::​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<charT, traits>​::​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 {template<class charT, class traits>class basic_ostream<charT, traits>::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)