operator<<(std::basic_ostream)

Defined in header `<ostream>`
basic_ostream and character
	(1)
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 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 );
basic_ostream and character array
		(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<char, Traits>& os, const char* s );
template< class Traits > basic_ostream<char, Traits>& operator<<( basic_ostream<char, Traits>& os, const signed char* s );
template< class Traits > basic_ostream<char, Traits>& operator<<( basic_ostream<char, Traits>& os, const unsigned char* s );
basic_ostream rvalue
template< class Ostream, class T > Ostream&& operator<<( Ostream&& os, const T& value );			(3)	(since C++11)
deleted overloads for basic_ostream and UTF character/array
			(4)	(since C++20)
template< class Traits > basic_ostream<char, Traits>& operator<<( basic_ostream<char, Traits>& os, wchar_t ch ) = delete;
template< class Traits > basic_ostream<char, Traits>& operator<<( basic_ostream<char, Traits>& os, char8_t ch ) = delete;
template< class Traits > basic_ostream<char, Traits>& operator<<( basic_ostream<char, Traits>& os, char16_t ch ) = delete;
template< class Traits > basic_ostream<char, Traits>& operator<<( basic_ostream<char, Traits>& os, char32_t ch ) = delete;
template< class Traits > basic_ostream<wchar_t, Traits>& operator<<( basic_ostream<wchar_t, Traits>& os, char8_t ch ) = delete;
template< class Traits > basic_ostream<wchar_t, Traits>& operator<<( basic_ostream<wchar_t, Traits>& os, char16_t ch ) = delete;
template< class Traits > basic_ostream<wchar_t, Traits>& operator<<( basic_ostream<wchar_t, Traits>& os, char32_t ch ) = delete;
template< class Traits > basic_ostream<char, Traits>& operator<<( basic_ostream<char, Traits>& os, const wchar_t* s ) = delete;
template< class Traits > basic_ostream<char, Traits>& operator<<( basic_ostream<char, Traits>& os, const char8_t* s ) = delete;
template< class Traits > basic_ostream<char, Traits>& operator<<( basic_ostream<char, Traits>& os, const char16_t* s ) = delete;
template< class Traits > basic_ostream<char, Traits>& operator<<( basic_ostream<char, Traits>& os, const char32_t* s ) = delete;
template< class Traits > basic_ostream<wchar_t, Traits>& operator<<( basic_ostream<wchar_t, Traits>& os, const char8_t* s ) = delete;
template< class Traits > basic_ostream<wchar_t, Traits>& operator<<( basic_ostream<wchar_t, Traits>& os, const char16_t* s ) = delete;
template< class Traits > basic_ostream<wchar_t, Traits>& operator<<( basic_ostream<wchar_t, Traits>& os, const char32_t* s ) = delete;

Inserts a character or a character string.

1) Behaves as a FormattedOutputFunction. After constructing and checking the sentry object, inserts the character ch. If ch has type char and the character container type of os is not char, os.widen(ch) will be inserted instead.

Padding is determined as follows:

If os.width() > 1, then os.width() - 1 copies of os.fill() are added to the output character to form the output character sequence.
If (out.flags() & std::ios_base::adjustfield) == std::ios_base::left, the fill characters are placed after the output character, otherwise before.

After insertion, os.width(0) is called to cancel the effects of std::setw, if any.

2) Behaves as a FormattedOutputFunction. After constructing and checking the sentry object, inserts successive characters from the character array whose first element is pointed to by s.

For the first and third overloads (where CharT matches the type of ch), exactly traits::length(s) characters are inserted.
For the second overload, exactly std::char_traits<char>::length(s) characters are inserted.
For the last two overloads, exactly traits::length(reinterpret_cast<const char*>(s)) are inserted.

Before insertion, first, all characters are widened using os.widen(), then padding is determined as follows:

If the number of characters to insert is less than os.width(), then enough copies of os.fill() are added to the character sequence to make its length equal os.width().
If (out.flags() & std::ios_base::adjustfield) == std::ios_base::left, the fill characters are added at the end of the output sequence, otherwise they are added before the output sequence.

After insertion, os.width(0) is called to cancel the effects of std::setw, if any.

If s is a null pointer, the behavior is undefined.

3) Calls the appropriate insertion operator, given an rvalue reference to an output stream object (equivalent to os << value). This overload participates in overload resolution only if the expression os << value is well-formed and Ostream is a class type publicly and unambiguously derived from std::ios_base.

4) Overloads that accept char16_t, char32_t etc (or null terminated sequence thereof) are deleted: std::cout << u'X' is not allowed. Previously, these would print an integer or pointer value.

Parameters

os	-	output stream to insert data to
ch	-	reference to a character to insert
s	-	pointer to a character string to insert

Return value

1,2) os

3) std::move(os)

Notes

Before LWG issue 1203, code such as (std::ostringstream() << 1.2).str() does not compile.

Example

Run this code

#include <fstream>
#include <iostream>
 
void foo()
{
    // error: operator<< (basic_ostream<char, _Traits>&, char8_t) is deleted
//  std::cout << u8'z' << '\n';
}
 
std::ostream& operator<<(std::ostream& os, char8_t const& ch)
{
    return os << static_cast<char>(ch);
}
 
int main()
{
    std::cout << "Hello, world" // uses `const char*` overload
              << '\n';          // uses `char` overload
    std::ofstream{"test.txt"} << 1.2; // uses rvalue overload
 
    std::cout << u8'!' << '\n'; // uses program-defined operator<<(os, char8_t const&)
}

Output:

Hello, world
!

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR	Applied to	Behavior as published	Correct behavior
LWG 167	C++98	the number of characters inserted for all overloads in (2) was traits::length(s)	updated the numbers for the overloads where `CharT` does not match the type of ch
LWG 1203	C++11	overload for rvalue stream returned lvalue reference to the base class	returns rvalue reference to the derived class
LWG 2011	C++98	padding was determined by std::num_put::do_put()	determined by the operator itself
LWG 2534	C++11	overload for rvalue stream was not constrained	constrained

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Execution support library (C++26)
Technical specifications
Symbols index
External libraries

I/O manipulators
Print functions (C++23)
C-style I/O
Buffers
basic_streambuf
basic_filebuf
basic_stringbuf
basic_spanbuf (C++23)
strstreambuf (C++98/26*)
basic_syncbuf (C++20)
Streams
Abstractions
ios_base
basic_ios
basic_istream
basic_ostream
basic_iostream
File I/O
basic_ifstream
basic_ofstream
basic_fstream
String I/O
basic_istringstream
basic_ostringstream
basic_stringstream
Array I/O
basic_ispanstream (C++23)
basic_ospanstream (C++23)
basic_spanstream (C++23)
istrstream (C++98/26*)
ostrstream (C++98/26*)
strstream (C++98/26*)
Synchronized Output
basic_osyncstream (C++20)
Types
streamoff
streamsize
fpos
Error category interface
iostream_category (C++11)
io_errc (C++11)

operator<<	inserts formatted data (public member function)
print(std::ostream) (C++23)	outputs formatted representation of the arguments (function template)
widen	widens characters (public member function of `std::basic_ios<CharT,Traits>`)