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:



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:

flagerror
eofbit-
failbitWhen used with a streambuf object as parameter, failbit is set on if no characters could be extracted from it.
badbitAn 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
template <class charT, class traits>
  basic_ostream<charT,traits>& operator<< (basic_ostream<charT,traits>& os, charT ch );

template <class charT, class traits>
  basic_ostream<charT,traits>& operator<< (basic_ostream<charT,traits>& os, char ch );

template <class charT, class traits>
  basic_ostream<charT,traits>& operator<< (basic_ostream<charT,traits>& os, const charT* str );

template <class charT, class traits>
  basic_ostream<charT,traits>& operator<< (basic_ostream<charT,traits>& os, const char* str );

// template specializations:

template <class traits>
  basic_ostream<char,traits>& operator<< (basic_ostream<char,traits>& os, char ch );

template <class traits>
  basic_ostream<char,traits>& operator<< (basic_ostream<char,traits>& os, signed char ch );

template <class traits>
  basic_ostream<char,traits>& operator<< (basic_ostream<char,traits>& os, unsigned char ch );

template <class traits>
  basic_ostream<char,traits>& operator<< (basic_ostream<char,traits>& os, const char* str );

template <class traits>
  basic_ostream<char,traits>& operator<< (basic_ostream<char,traits>& os, const signed char* str );

template <class traits>
  basic_ostream<char,traits>& operator<< (basic_ostream<char,traits>& os, const unsigned char* str );


See also