Reference
C Library
IOstream Library
Strings library
STL Containers
STL Algorithms
Miscellaneous

IOstream Library
manipulators
classes:
filebuf
fstream
ifstream
ios
iostream
ios_base
istream
istringstream
ofstream
ostream
ostringstream
streambuf
stringbuf
stringstream
objects:
cerr
cin
clog
cout
types:
fpos
streamoff
streampos
streamsize

ostream
ostream::ostream
ostream::~ostream
member classes:
ostream::sentry
member functions:
ostream::flush
ostream::operator<<
ostream::put
ostream::seekp
ostream::tellp
ostream::write

ostream::operator<<

public member function

ostream& operator<< (bool& val );
ostream& operator<< (short& val );
ostream& operator<< (unsigned short& val );
ostream& operator<< (int& val );
ostream& operator<< (unsigned int& val );
ostream& operator<< (long& val );
ostream& operator<< (unsigned long& val );
ostream& operator<< (float& val );
ostream& operator<< (double& val );
ostream& operator<< (long double& val );
ostream& operator<< (const void* val );
 
ostream& operator<< (streambuf* sb );
 
ostream& operator<< (ostream& ( *pf )(ostream&));
ostream& operator<< (ios& ( *pf )(ios&));
ostream& operator<< (ios_base& ( *pf )(ios_base&));
 
*** the following functions are not members but GLOBAL functions:
 
ostream& operator<< (ostream& out, char c );
ostream& operator<< (ostream& out, signed char c );
ostream& operator<< (ostream& out, unsigned char c );
 
ostream& operator<< (ostream& out, const char* s );
ostream& operator<< (ostream& out, const signed char* s );
ostream& operator<< (ostream& out, const unsigned char* s );

Insert data with format

This operator (<<) applied to an input stream is known as insertion operator. It performs an output operation on a stream generally involving some sort of formatting of the data (like for example writing a numerical value as a sequence of characters).

Three groups of member functions and one group of global functions overload this "insertion operator" (<<) applied to ostream objects:

The first group of member functions are arithmetic inserters. These write a numerical or boolean value formatting it as a sequence of characters.
The streambuf version copies as many characters as possible from the stream buffer object used as right-hand parameter, either until an error happens or until there are no more characters to copy.
Those in the last group of member functions have a pointer to a function as parameter. These are designed to be used with manipulator functions.
Manipulator functions are functions specifically designed to be easily used with this operator.
The global functions overload the operator when the parameter is either a character or a c-string, and, as expected they insert either one character or a sequence of characters to the output stream.

See the description of the parameters for more details on how each group of functions work.

Because these functions are operator overloading functions, the usual way in which they are called is:

strm << value;

Where strm is the identifier of a ostream object and value is an object of any type supported as right parameter. It is also possible to call a succession of insertion operations as:

strm << value1 << value2 << value3; //...

which is the same as performing successive insertions on the same object strm.

The standard manipulators which have an effect when used on ostream objects are:

boolalpha

Alphanumerical bool values (manipulator function)

dec

Use decimal base (manipulator function)

endl

Insert newline and flush (manipulator function)

ends

Insert null character (manipulator function)

fixed

Use fixed-point notation (manipulator function)

flush

Flush stream buffer (manipulator function)

hex

Use hexadecimal base (manipulator function)

internal

Adjust field by inserting characters at an internal position (manipulator function)

left

Adjust output to the left (manipulator function)

noboolalpha

No alphanumerical bool values (manipulator function)

noshowbase

Do not show numerical base prefixes (manipulator function)

noshowpoint

Do not show decimal point (manipulator function)

noshowpos

Do not show positive signs (manipulator function)

nounitbuf

Do not force flushes after insertions (manipulator function)

nouppercase

Do not generate upper case letters (manipulator function)

oct

Use octal base (manipulator function)

right

Adjust output to the right (manipulator function)

scientific

Use scientific notation (manipulator function)

showbase

Show numerical base prefixes (manipulator function)

showpoint

Show decimal point (manipulator function)

showpos

Show positive signs (manipulator function)

unitbuf

Flush buffer after insertions (manipulator function)

uppercase

Generate upper-case letters (manipulator function)

Other manipulators may be applied, but have no effect on standard ostream objects.

Parameters

val: Inserts a representation of the value of the val parameter as a sequence of human-readable characters. The specific way in which the data is formatted depends on the manipulators previously inserted on the stream and on its associated locale.
sb: Inserts characters from sb and writes them to the output sequence until the End-Of-File is reached (in which case this last character is not extracted).
pf: Calls pf(*this), which generally is a manipulator function.
c: A single character is inserted.
s: Inserts a sequence characters coming from a c-string, i.e. s is a pointer to the first character of the sequence to be inserted. Insertion ends when the next character is either a valid whitespace or the terminating null character of the c-string, or if the End-Of-File is reached.
After a call to this version of the insertion operation, the value of the field width is automatically reset to zero.
out: stream object on which the action is performed. This is the first parameter of the global functions, and represents the object to the left of the operator, i.e. the object on which the extraction operation is performed.

Return Value

The object itself (*this).

Errors are signaled by modifying the internal state flags:

flag	error
`eofbit`	-
`failbit`	When used with a streambuf object as parameter, `failbit` is set on if no characters could be extracted from it.
`badbit`	An error other than the above happened.

(see ios_base::iostate for more info on these)

Additionaly, in any of these cases, if the appropriate flag has been set with member function ios::exceptions, an exception of type ios_base::failure is thrown.

If some error happens during the output operation, the stream's badbit flag is set, and if the appropriate flag has been set with ios::exceptions, an exception is thrown.

Example

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

// example on insertion
#include <iostream>
using namespace std;
int main () {
  char str[] = "Test sentence";
  int val = 65;
  char ch = 'A';
  cout << str << endl;     // Insert string
  cout << ch << endl;      // Insert single character
  cout.width (10);
  cout << right;           // Insert manipulator
  cout << val << endl;     // Insert integer
  return 0;
}

The source demonstrates the use of some of the overloaded operator<< functions shown above using the ostream standard object cout.

Basic template member declarations

( basic_ostream<charT,traits> )

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

basic_ostream& operator<< (bool& val );
basic_ostream& operator<< (short& val );
basic_ostream& operator<< (unsigned short& val );
basic_ostream& operator<< (int& val );
basic_ostream& operator<< (unsigned int& val );
basic_ostream& operator<< (long& val );
basic_ostream& operator<< (unsigned long& val );
basic_ostream& operator<< (float& val );
basic_ostream& operator<< (double& val );
basic_ostream& operator<< (long double& val );
basic_ostream& operator<< (void*& val );
basic_ostream& operator<< (basic_streambuf<charT,traits>* sb );
basic_ostream& operator<< (basic_ostream& ( *pf )(istream&));
basic_ostream& operator<< (basic_ios<charT,traits>& ( *pf )(basic_ios<charT,traits>&));
basic_ostream& operator<< (ios_base& ( *pf )(ios_base&));

Basic template global functions

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31