public member function
<ostream> <iostream>

std::operator<< (basic_ostream)

single character (1)
template<class charT, class traits>basic_ostream<charT,traits>& operator<< (basic_ostream<charT,traits>& os, charT c);template<class charT, class traits>basic_ostream<charT,traits>& operator<< (basic_ostream<charT,traits>& os, char c);template<class traits>basic_ostream<char,traits>& operator<< (basic_ostream<char,traits>& os, char c);template<class traits>basic_ostream<char,traits>& operator<< (basic_ostream<char,traits>& os, signed char c);template<class traits>basic_ostream<char,traits>& operator<< (basic_ostream<char,traits>& os, unsigned char c);
character sequence (2)
template<class charT, class traits>basic_ostream<charT,traits>& operator<< (basic_ostream<charT,traits>& os, const charT* s);template<class charT, class traits>basic_ostream<charT,traits>& operator<< (basic_ostream<charT,traits>& os, const char* s);template<class traits>basic_ostream<char,traits>& operator<< (basic_ostream<charT,traits>& os, const char* s);template<class traits>basic_ostream<char,traits>& operator<< (basic_ostream<charT,traits>& os, const signed char* s);template<class traits>basic_ostream<char,traits>& operator<< (basic_ostream<charT,traits>& os, const unsigned char* s);
single character (1)
template<class charT, class traits>basic_ostream<charT,traits>& operator<< (basic_ostream<charT,traits>& os, charT c);template<class charT, class traits>basic_ostream<charT,traits>& operator<< (basic_ostream<charT,traits>& os, char c);template<class traits>basic_ostream<char,traits>& operator<< (basic_ostream<char,traits>& os, char c);template<class traits>basic_ostream<char,traits>& operator<< (basic_ostream<char,traits>& os, signed char c);template<class traits>basic_ostream<char,traits>& operator<< (basic_ostream<char,traits>& os, unsigned char c);
character sequence (2)
template<class charT, class traits>basic_ostream<charT,traits>& operator<< (basic_ostream<charT,traits>& os, const charT* s);template<class charT, class traits>basic_ostream<charT,traits>& operator<< (basic_ostream<charT,traits>& os, const char* s);template<class traits>basic_ostream<char,traits>& operator<< (basic_ostream<charT,traits>& os, const char* s);template<class traits>basic_ostream<char,traits>& operator<< (basic_ostream<charT,traits>& os, const signed char* s);template<class traits>basic_ostream<char,traits>& operator<< (basic_ostream<charT,traits>& os, const unsigned char* s);
rvalue insertion (3)
template<class charT, class traits, class T>basic_ostream<charT,traits>& operator<< (basic_ostream<charT,traits>&& os, const T& val);
Insert characters
This operator (<<) applied to an output stream is known as insertion operator, and performs formatted output:

(1) single character
Inserts the character c into os.
(2) character sequence
Inserts the C-string s into os.
The terminating null character is not inserted into os.
The length of the c-string is determined beforehand by using the length member of the proper traits class.
(3) rvalue insertion
Allows inserting into rvalue basic_ostream objects, with the same effect as to lvalues: It effectively calls: os<<val.

The function inserts at least os.width() characters into os: if the characters to insert are less, they are padded with fill characters inserted before c or s, unless os's adjustfield setting is left (in this case, the fill characters are inserted after c or s).

Internally, the function accesses the output sequence by first constructing a sentry object. Then (if good), it inserts the characters described above into its associated stream buffer object as if calling its member function sputc. It then resets the field width to zero, and finally destroys the sentry object before returning.

Parameters

os
Output stream object where characters are inserted.
c
Character to insert.
If this is of type char, and this type is different from charT (the character type handled by os), the character inserted is os.widen(c).
s
Pointer to a null-terminated sequence of characters.
If these are of type char, and this type is different from charT (the character type handled by os), each character inserted is widened using os.widen.
val
ValueObject inserted.
T shall be a type supported as right-hand side argument either by this function or by os's member function operator<<.
charT and traits are the class template parameters of os (see basic_ostream).

Return Value

The basic_ostream object (os).

Errors are signaled by modifying the internal state flags:
flagerror
eofbit-
failbitThe function failed while formatting the output (it may also be set if the construction of sentry failed).
badbitEither the insertion on the stream failed, or some other error happened (such as when this function catches an exception thrown by an internal operation).
When set, the integrity of the stream may have been affected.
Multiple flags may be set by a single operation.

If the operation sets an internal state flag on os that was registered with its member exceptions, the function throws an exception of its failure member type.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// example on insertion
#include <iostream>     // std::cout

int main () {

  const char str[] = "Example string";
  char ch = 'X';

  std::cout << str << '\n';     // Insert string

  std::cout.width(5);
  std::cout.fill('*');

  std::cout << ch << '\n';      // Insert single character

  return 0;
}

Output:
Example string
****X


Data races

Accesses s (2). Modifies os.
Concurrent access to the same stream object may cause data races, except for the standard stream objects (cout, cerr, clog, wcout, wcerr and wclog) when these are synchronized with stdio (in this case, no data races are initiated, although no guarantees are given on the order in which characters from multiple threads are inserted).

Exception safety

Basic guarantee: if an exception is thrown, all objects involved are in valid states.
It throws an exception of member type failure if the resulting error state flag for is is not goodbit and member exceptions was set to throw for that state in os.
Any exception thrown by an internal operation is caught and handled by the function, setting is's badbit flag. If badbit was set on the last call to exceptions for is, the function rethrows the caught exception.

If s does not point to a null terminated character sequence, it causes undefined behavior.

See also