basic_ostream Class
This class template describes an object that controls insertion of elements and encoded objects into a stream buffer with elements of type Elem, also known as char_type, whose character traits are determined by the class Tr, also known as traits_type.
template <class Elem, class Tr = char_traits<Elem>>
class basic_ostream : virtual public basic_ios<Elem, Tr>
Elem
A char_type.
Tr
The character traits_type.
Most of the member functions that overload operator<< are formatted output functions. They follow the pattern:
iostate state = goodbit;
const sentry ok(*this);
if (ok)
{try
{<convert and insert elements
accumulate flags in state> }
catch (...)
{try
{setstate(badbit);
}
catch (...)
{}
if ((exceptions()& badbit) != 0)
throw; }}
width(0);
// Except for operator<<(Elem)
setstate(state);
return (*this);
Two other member functions are unformatted output functions. They follow the pattern:
iostate state = goodbit;
const sentry ok(*this);
if (!ok)
state |= badbit;
else
{try
{<obtain and insert elements
accumulate flags in state> }
catch (...)
{try
{setstate(badbit);
}
catch (...)
{}
if ((exceptions()& badbit) != 0)
throw; }}
setstate(state);
return (*this);
Both groups of functions call setstate(badbit) if they encounter a failure while inserting elements.
An object of class basic_istream< Elem, Tr> stores only a virtual public base object of class basic_ios<Elem, Tr>.
See the example for basic_ofstream Class to learn more about output streams.
| Constructor | Description |
|---|---|
| basic_ostream | Constructs a basic_ostream object. |
| Member function | Description |
|---|---|
| flush | Flushes the buffer. |
| put | Puts a character in a stream. |
| seekp | Resets position in output stream. |
| sentry | The nested class describes an object whose declaration structures the formatted output functions and the unformatted output functions. |
| swap | Exchanges the values of this basic_ostream object for those of the provided basic_ostream object. |
| tellp | Reports position in output stream. |
| write | Puts characters in a stream. |
| Operator | Description |
|---|---|
| operator= | Assigns the value of the provided basic_ostream object parameter to this object. |
| operator<< | Writes to the stream. |
Header: <ostream>
Namespace: std
Constructs a basic_ostream object.
explicit basic_ostream(
basic_streambuf<Elem, Tr>* strbuf,
bool _Isstd = false);
basic_ostream(basic_ostream&& right);
strbuf
An object of type basic_streambuf.
_Isstd
true if this is a standard stream; otherwise, false.
right
An rvalue reference to an object of type basic_ostream.
The first constructor initializes the base class by calling init(strbuf). The second constructor initializes the base class by calling basic_ios::move(right).
See the example for basic_ofstream::basic_ofstream to learn more about output streams.
Flushes the buffer.
basic_ostream<Elem, Tr>& flush();
A reference to the basic_ostream object.
If rdbuf is not a null pointer, the function calls rdbuf->pubsync. If that returns -1, the function calls setstate(badbit). It returns *this.
// basic_ostream_flush.cpp
// compile with: /EHsc
#include <iostream>
int main( )
{
using namespace std;
cout << "test";
cout.flush();
}
test
Writes to the stream.
basic_ostream<Elem, Tr>& operator<<(
basic_ostream<Elem, Tr>& (* Pfn)(basic_ostream<Elem, Tr>&));
basic_ostream<Elem, Tr>& operator<<(
ios_base& (* Pfn)(ios_base&));
basic_ostream<Elem, Tr>& operator<<(
basic_ios<Elem, Tr>& (* Pfn)(basic_ios<Elem, Tr>&));
basic_ostream<Elem, Tr>& operator<<(basic_streambuf<Elem, Tr>* strbuf);
basic_ostream<Elem, Tr>& operator<<(bool val);
basic_ostream<Elem, Tr>& operator<<(short val);
basic_ostream<Elem, Tr>& operator<<(unsigned short val);
basic_ostream<Elem, Tr>& operator<<(int __w64 val);
basic_ostream<Elem, Tr>& operator<<(unsigned int __w64 val);
basic_ostream<Elem, Tr>& operator<<(long val);
basic_ostream<Elem, Tr>& operator<<(unsigned long __w64 val);
basic_ostream<Elem, Tr>& operator<<(long long val);
basic_ostream<Elem, Tr>& operator<<(unsigned long long val);
basic_ostream<Elem, Tr>& operator<<(float val);
basic_ostream<Elem, Tr>& operator<<(double val);
basic_ostream<Elem, Tr>& operator<<(long double val);
basic_ostream<Elem, Tr>& operator<<(const void* val);
Pfn
A function pointer.
strbuf
A pointer to a stream_buf object.
val
An element to write to the stream.
A reference to the basic_ostream object.
The <ostream> header also defines several global insertion operators. For more information, see operator<<.
The first member function ensures that an expression of the form ostr << endl calls endl(ostr), and then returns *this. The second and third functions ensure that other manipulators, such as hex, behave similarly. The remaining functions are all formatted output functions.
The function
basic_ostream<Elem, Tr>& operator<<(basic_streambuf<Elem, Tr>* strbuf);
extracts elements from strbuf, if strbuf is not a null pointer, and inserts them. Extraction stops on end of file, or if an extraction throws an exception (which is rethrown). It also stops, without extracting the element in question, if an insertion fails. If the function inserts no elements, or if an extraction throws an exception, the function calls setstate(failbit). In any case, the function returns *this.
The function
basic_ostream<Elem, Tr>& operator<<(bool val);
converts _Val to a Boolean field and inserts it by calling use_facet<num_put<Elem, OutIt>(getloc). put(OutIt(rdbuf), *this, getloc, val). Here, OutIt is defined as ostreambuf_iterator<Elem, Tr>. The function returns *this.
The functions
basic_ostream<Elem, Tr>& operator<<(short val);
basic_ostream<Elem, Tr>& operator<<(unsigned short val);
basic_ostream<Elem, Tr>& operator<<(int val);
basic_ostream<Elem, Tr>& operator<<(unsigned int __w64 val);
basic_ostream<Elem, Tr>& operator<<(long val);
basic_ostream<Elem, Tr>& operator<<(unsigned long val);
basic_ostream<Elem, Tr>& operator<<(long long val);
basic_ostream<Elem, Tr>& operator<<(unsigned long long val);
basic_ostream<Elem, Tr>& operator<<(const void* val);
each convert val to a numeric field and insert it by calling use_facet<num_put<Elem, OutIt>(getloc). put(OutIt(rdbuf), *this, getloc, val). Here, OutIt is defined as ostreambuf_iterator<Elem, Tr>. The function returns *this.
The functions
basic_ostream<Elem, Tr>& operator<<(float val);
basic_ostream<Elem, Tr>& operator<<(double val);
basic_ostream<Elem, Tr>& operator<<(long double val);
each convert val to a numeric field and insert it by calling use_facet<num_put<Elem, OutIt>(getloc). put(OutIt(rdbuf), *this, getloc, val). Here, OutIt is defined as ostreambuf_iterator<Elem, Tr>. The function returns *this.
// basic_ostream_op_write.cpp
// compile with: /EHsc
#include <iostream>
#include <string.h>
using namespace std;
ios_base& hex2( ios_base& ib )
{
ib.unsetf( ios_base::dec );
ib.setf( ios_base::hex );
return ib;
}
basic_ostream<char, char_traits<char> >& somefunc(basic_ostream<char, char_traits<char> > &i)
{
if (i == cout)
{
i << "i is cout" << endl;
}
return i;
}
class CTxtStreambuf : public basic_streambuf< char, char_traits< char > >
{
public:
CTxtStreambuf(char *_pszText)
{
pszText = _pszText;
setg(pszText, pszText, pszText + strlen(pszText));
};
char *pszText;
};
int main()
{
cout << somefunc;
cout << 21 << endl;
hex2(cout);
cout << 21 << endl;
CTxtStreambuf f("text in streambuf");
cout << &f << endl;
}
Assigns values for the provided basic_ostream object parameter to this object.
basic_ostream& operator=(basic_ostream&& right);
right
An rvalue reference to a basic_ostream object.
The member operator calls swap (right).
Puts a character in a stream.
basic_ostream<Elem, Tr>& put(char_type _Ch);
_Ch
A character.
A reference to the basic_ostream object.
The unformatted output function inserts the element _Ch. It returns *this.
// basic_ostream_put.cpp
// compile with: /EHsc
#include <iostream>
int main( )
{
using namespace std;
cout.put( 'v' );
cout << endl;
wcout.put( L'l' );
}
v
l
Reset position in output stream.
basic_ostream<Elem, Tr>& seekp(pos_type _Pos);
basic_ostream<Elem, Tr>& seekp(off_type _Off, ios_base::seekdir _Way);
_Pos
The position in the stream.
_Off
The offset relative to _Way.
_Way
One of the ios_base::seekdir enumerations.
A reference to the basic_ostream object.
If fail is false, the first member function calls newpos = rdbuf-> pubseekpos(_Pos), for some pos_type temporary object newpos. If fail is false, the second function calls newpos = rdbuf-> pubseekoff(_Off, _Way). In either case, if (off_type)newpos == (off_type)(-1) (the positioning operation fails), then the function calls istr.setstate(failbit). Both functions return *this.
// basic_ostream_seekp.cpp
// compile with: /EHsc
#include <fstream>
#include <iostream>
int main()
{
using namespace std;
ofstream x("basic_ostream_seekp.txt");
streamoff i = x.tellp();
cout << i << endl;
x << "testing";
i = x.tellp();
cout << i << endl;
x.seekp(2); // Put char in third char position in file
x << " ";
x.seekp(2, ios::end); // Put char two after end of file
x << "z";
}
0
7
The nested class describes an object whose declaration structures the formatted output functions and the unformatted output functions.
class sentry { public: explicit sentry(basic_ostream<Elem, Tr>& _Ostr); operator bool() const; ~sentry(); };
The nested class describes an object whose declaration structures the formatted output functions and the unformatted output functions. If ostr.good is true and ostr.tie is not a null pointer, the constructor calls ostr.tie->flush. The constructor then stores the value returned by ostr.good in status. A later call to operator bool delivers this stored value.
If uncaught_exception returns false and flags & unitbuf is nonzero, the destructor calls flush.
Exchanges the values of this basic_ostream object for the values of the provided basic_ostream.
void swap(basic_ostream& right);
right
A reference to a basic_ostream object.
The member function calls basic_ios::swap(right) to exchange the contents of this object for the contents of right.
Report position in output stream.
pos_type tellp();
Position in output stream.
If fail is false, the member function returns rdbuf-> pubseekoff(0, cur, in). Otherwise, it returns pos_type(-1).
See seekp for an example using tellp.
Put characters in a stream.
basic_ostream<Elem, Tr>& write(const char_type* str, streamsize count);
count
Count of characters to put into the stream.
str
Characters to put into the stream.
A reference to the basic_ostream object.
The unformatted output function inserts the sequence of count elements beginning at str.
See streamsize for an example using write.
Thread Safety in the C++ Standard Library
iostream Programming
iostreams Conventions