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). 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.- 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, width(0) is called to cancel the effects of std::setw, if any.
The behavior is undefined if s is a null pointer.Ostream
is a class type publicly and unambiguously derived from std::ios_base.Contents |
[edit] Parameters
os | - | output stream to insert data to |
ch | - | reference to a character to insert |
s | - | pointer to a character string to insert |
[edit] Return value
[edit] Notes
Before LWG issue 1203, code such as (std::ostringstream() << 1.2).str() does not compile.
[edit] Example
#include <iostream> #include <fstream> 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 !
[edit] 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 2534 | C++11 | overload for rvalue stream was not constrained | constrained |
[edit] 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> )
|