operator<<(std::basic_ostream)
Defined in header <ostream>
|
||
basic_ostream and character |
||
(1) | ||
template< class CharT, class Traits > basic_ostream<CharT, Traits>& |
||
template< class CharT, class Traits > basic_ostream<CharT, Traits>& |
||
template< class Traits > basic_ostream<char, Traits>& |
||
template< class Traits > basic_ostream<char, Traits>& |
||
template< class Traits > basic_ostream<char, Traits>& |
||
basic_ostream and character array |
||
(2) | ||
template< class CharT, class Traits > basic_ostream<CharT, Traits>& |
||
template< class CharT, class Traits > basic_ostream<CharT, Traits>& |
||
template< class Traits > basic_ostream<char, Traits>& |
||
template< class Traits > basic_ostream<char, Traits>& |
||
template< class Traits > basic_ostream<char, Traits>& |
||
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>& |
||
template< class Traits > basic_ostream<char, Traits>& |
||
template< class Traits > basic_ostream<char, Traits>& |
||
template< class Traits > basic_ostream<char, Traits>& |
||
template< class Traits > basic_ostream<wchar_t, Traits>& |
||
template< class Traits > basic_ostream<wchar_t, Traits>& |
||
template< class Traits > basic_ostream<wchar_t, Traits>& |
||
template< class Traits > basic_ostream<char, Traits>& |
||
template< class Traits > basic_ostream<char, Traits>& |
||
template< class Traits > basic_ostream<char, Traits>& |
||
template< class Traits > basic_ostream<char, Traits>& |
||
template< class Traits > basic_ostream<wchar_t, Traits>& |
||
template< class Traits > basic_ostream<wchar_t, Traits>& |
||
template< class Traits > basic_ostream<wchar_t, Traits>& |
||
Inserts a character or a character string.
CharT
, it is first converted with os.widen(ch).- 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.
- 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.
- 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.
Ostream
is a class type publicly and unambiguously derived from std::ios_base.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
Notes
Before LWG issue 1203, code such as (std::ostringstream() << 1.2).str() does not compile.
Example
#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 |
See also
inserts formatted data (public member function) | |
(C++23) |
outputs formatted representation of the arguments (function template) |
widens characters (public member function of std::basic_ios<CharT,Traits> ) |