From cppreference.com
Defined in header
basic_ostream and character
template<classCharT,classTraits>basic_ostream<CharT,Traits>&operator<<(basic_ostream<CharT,Traits>&os,CharTch);template<classCharT,classTraits>basic_ostream<CharT,Traits>&operator<<(basic_ostream<CharT,Traits>&os,charch);template<classTraits>basic_ostream<char,Traits>&operator<<(basic_ostream<char,Traits>&os,charch);template<classTraits>basic_ostream<char,Traits>&operator<<(basic_ostream<char,Traits>&os,signedcharch);template<classTraits>basic_ostream<char,Traits>&operator<<(basic_ostream<char,Traits>&os,unsignedcharch); (1) basic_ostream and character array
template<classCharT,classTraits>basic_ostream<CharT,Traits>&operator<<(basic_ostream<CharT,Traits>&os,constCharT*s);template<classCharT,classTraits>basic_ostream<CharT,Traits>&operator<<(basic_ostream<CharT,Traits>&os,constchar*s);template<classTraits>basic_ostream<char,Traits>&operator<<(basic_ostream<char,Traits>&os,constchar*s);template<classTraits>basic_ostream<char,Traits>&operator<<(basic_ostream<char,Traits>&os,constsignedchar*s);template<classTraits>basic_ostream<char,Traits>&operator<<(basic_ostream<char,Traits>&os,constunsignedchar*s); (2) basic_ostream rvalue
template<classOstream,classT>Ostream&&operator<<(Ostream&&os,constT&value); (3) (since C++11)Deleted overloads for basic_ostream and UTF character/array
template<classTraits>basic_ostream<char,Traits>&operator<<(basic_ostream<char,Traits>&os,wchar_tch)=delete;template<classTraits>basic_ostream<char,Traits>&operator<<(basic_ostream<char,Traits>&os,char8_tch)=delete;template<classTraits>basic_ostream<char,Traits>&operator<<(basic_ostream<char,Traits>&os,char16_tch)=delete;template<classTraits>basic_ostream<char,Traits>&operator<<(basic_ostream<char,Traits>&os,char32_tch)=delete;template<classTraits>basic_ostream<wchar_t,Traits>&operator<<(basic_ostream<wchar_t,Traits>&os,char8_tch)=delete;template<classTraits>basic_ostream<wchar_t,Traits>&operator<<(basic_ostream<wchar_t,Traits>&os,char16_tch)=delete;template<classTraits>basic_ostream<wchar_t,Traits>&operator<<(basic_ostream<wchar_t,Traits>&os,char32_tch)=delete;template<classTraits>basic_ostream<char,Traits>&operator<<(basic_ostream<char,Traits>&os,constwchar_t*s)=delete;template<classTraits>basic_ostream<char,Traits>&operator<<(basic_ostream<char,Traits>&os,constchar8_t*s)=delete;template<classTraits>basic_ostream<char,Traits>&operator<<(basic_ostream<char,Traits>&os,constchar16_t*s)=delete;template<classTraits>basic_ostream<char,Traits>&operator<<(basic_ostream<char,Traits>&os,constchar32_t*s)=delete;template<classTraits>basic_ostream<wchar_t,Traits>&operator<<(basic_ostream<wchar_t,Traits>&os,constchar8_t*s)=delete;template<classTraits>basic_ostream<wchar_t,Traits>&operator<<(basic_ostream<wchar_t,Traits>&os,constchar16_t*s)=delete;template<classTraits>basic_ostream<wchar_t,Traits>&operator<<(basic_ostream<wchar_t,Traits>&os,constchar32_t*s)=delete; (4) (since C++20)Inserts a character or a character string.
1) Behaves as a
. After constructing and checking the
object, inserts the character ch. If ch has type char and the
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
, if any.
2) Behaves as a
. 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<constchar*>(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
, 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
.
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
, code such as (std::ostringstream()<<1.2).str() does not compile.
Example
Run this code
#include<fstream>#include<iostream>voidfoo(){// error: operator<< (basic_ostream<char, _Traits>&, char8_t) is deleted// std::cout << u8'z' << '\n';}std::ostream&operator<<(std::ostream&os,char8_tconst&ch){returnos<<static_cast<char>(ch);}intmain(){std::cout<<"Hello, world"// uses `const char*` overload<<'\n';// uses `char` overloadstd::ofstream{"test.txt"}<<1.2;// uses rvalue overloadstd::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
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
C++11 overload for rvalue stream returned
lvalue reference to the base class returns rvalue reference
to the derived class
C++98 padding was determined by
determined by the operator itself
C++11 overload for rvalue stream was not constrained constrained See also