basic_ostream

Overview

basic_ostream are designed to publish outputs to various targets such as console, files and strings.

Details

The class template basic_ostream provides support for high level output operations on character streams. The supported operations include formatted output (e.g. integer values or whitespace-separated characters and characters strings) and unformatted output (e.g. raw characters and character arrays). 

Syntax

template<class CharT, class Traits = char_traits<CharT>> 
class basic_ostream: public basic_ios<CharT,Traits> 

where CharT can be char or wchar_t. It's derived from basic_ios class.

member types

Following properties are defined.

Name	Definition
char_type	char,wchar_t
traits_type	char_traits<char_type>
int_type	char_traits<char_type>::int_type
pos_type	char_traits<char_type>::pos_type
off_type	char_traits<char_type>::off_type

sentry class

sentry is a subclass that's constructed in local scope at the beginning of each member function of basic_ostream that performs output (both formatted and unformatted).

All member functions of basic_ostream that perform an output operation automatically construct an object of this class and then evaluate it using the bool operator function. Only if this object evaluates to true, the function attempts the input operation.

Constructor

Syntax

sentry( basic_istream& is, bool noskipws = false )

Its constructor prepares the input stream by doing the following:

• Checks if the stream is already in a failed state. If so returns.
• Flushes the tie()'d output streams.
• Performs other implementation-defined tasks if necessary.

All cleanup, if necessary, is performed in the destructor, so that it is guaranteed to happen if exceptions are thrown during input.

Method

Syntax

operator bool()

Checks if the preparation was successful or not. Returns true or false.

Example

struct rect
{
    int  h,w;
};

ostream& operator<<(ostream& os,  rect& r)
{
    ostream::sentry s(os);
    if (s) 
        os << r.h << " " << r.w << endl;
    return os;
}

    rect r{10,20};
    //prints:10 20
    cout << r;

Constructor

Name	Description
basic_ostream (basic_streambuf* sb)	Constructs an object of class basic_ostream, assigning initial values to its member objects by calling init(sb). If sb is a null pointer, the stream is placed in error state by setting its badbit. Example ostream os(cout.rdbuf());

Formatted Output

operator <<

The overloaded operator << which is applied to an output stream is known as insertion operator.
This is discussed in detail here.

Unformatted Output
Name
Description
basic_ostream& put
(char_type c)
After constructing the sentry object doing preliminary checks and actions, the object is checked using its boolean operator.
If it returns false the function returns.
Inserts character c into the stream.

Example
ostringstream src ("ABCDE GHIJLMNOPRSTUVWXYZ");

src.seekp(5, ios_base::beg);
//src:ABCDEFGHIJKLMNOPQRSTUVWXYZ
src.put('F');
basic_ostream& write
(char_type *s, streamsize n)
After constructing the sentry object doing preliminary checks and actions, the object is checked using its boolean operator.
If it returns false the function returns.

Inserts the first n characters of the array pointed by s into the stream.

Example
ostringstream src;
//src:ABCDEFGHIJKLMNOPQRSTUVWXYZ
src.write("ABCDEFGHIJKLMNOPQRSTUVWXYZ",26);    


Positioning
Name
Description
basic_ostream& seekp (streampos pos)
basic_ostream& seekp
(streamoff off,  ios_base::seekdir dir)
After constructing the sentry object and doing preliminary checks and actions, it's checked by calling boolean operator.
If it returns false then function returns.
The function clears the eofbit flag, if set before the call. Negative offsets are allowed.
Sets the position of the next character to be inserted into the output stream to pos from the absolute beginning of the stream (ios_base::beg).
Sets the position of the next character to be inserted into the output stream to off relative to dir. The constants are defined ios_base class.
streampos tellp()
After constructing the sentry object and doing preliminary checks and actions, it's checked by calling boolean operator.
If it returns false then function returns.
Returns the current position of the insertable character into the stream.
Works even if eofbit is set.
Example
ostringstream src ("ABCDE GHIJ LMNOP RSTUVWXYZ");

src.seekp(10);
//src:ABCDE GHIJKLMNOP RSTUVWXYZ
src.put('K');
//p:11
auto p = src.tellp();

src.seekp(-10, ios_base::end);
//src:ABCDE GHIJKLMNOPQRSTUVWXYZ
src.put('Q');
//p:17
p = src.tellp();

src.seekp(5, ios_base::beg);
//src:ABCDEFGHIJKLMNOPQRSTUVWXYZ
src.put('F');
//p:6
p = src.tellp();


Other
Name
Description
basic_ostream& flush()
After constructing the sentry object and doing preliminary checks and actions, it's checked using its boolean operator.
If it returns false the function returns.

Synchronizes the associated stream buffer with its controlled output sequence. Writes uncommitted changes to the underlying output sequence. 

A manipulator exists with the same name and behavior (see flush).

Example
ostream& delay(ostream& os)
{
    cout.flush();
    this_thread::sleep_for(200ms);
    clog << "stop\n";
    return os;
}


    /*prints
    start
    hello
    stop
    world
    */
    clog << "start\n";
    cout << "hello\n" << delay << "world" << endl;