operator<<(std::basic_ostream)

Определён в заголовочном файле `<ostream>`
`basic_ostream` и символ
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 );	(1)
`basic_ostream` и массив символов
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 );	(2)
`basic_ostream` rvalue
template< class Ostream, class T > Ostream&& operator<<( Ostream&& os, const T& value );	(3)	(начиная с C++11)
Удалённые перегрузки для `basic_ostream` и символа/массива UTF
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;	(4)	(начиная с C++20)

Вставляет символ или строку символов.

1) Ведёт себя как функция форматированного вывода. После создания и проверки объекта sentry вставляет символ ch. Если ch имеет тип char, а тип контейнера символов для os не является char, вместо него будет вставлен os.widen(ch).

Заполнение определяется следующим образом:

Если os.width() > 1, то в выходную последовательность символов добавляются os.width() - 1 копий os.fill(), чтобы сформировать выходную последовательность символов.
Если (out.flags() & std::ios_base::adjustfield) == std::ios_base::left, символы заполнения помещаются после выходного символа, в противном случае — перед ним.

После вставки вызывается os.width(0) для отмены эффектов std::setw, если таковые имеются.

2) Ведёт себя как функция форматированного вывода. После создания и проверки объекта sentry вставляет последовательные символы из массива символов, на первый элемент которого указывает s.

Для первой и третьей перегрузок (где CharT соответствует типу ch) вставляется ровно traits::length(s) символов.
Для второй перегрузки вставляется ровно std::char_traits<char>::length(s) символов.
Для двух последних перегрузок вставляется ровно traits::length(reinterpret_cast<const char*>(s)).

Перед вставкой все символы сначала расширяются с помощью os.widen(), после чего заполнение определяется следующим образом:

Если число символов для вставки меньше os.width(), в последовательность символов добавляется достаточное количество копий os.fill(), чтобы её длина стала равна os.width().
Если (out.flags() & std::ios_base::adjustfield) == std::ios_base::left, символы заполнения добавляются в конец выходной последовательности, в противном случае — перед ней.

После вставки вызывается os.width(0) для отмены эффектов std::setw, если таковые имеются.

Если s является нулевым указателем, поведение не определено.

3) Вызывает соответствующий оператор вставки, получая rvalue-ссылку на объект выходного потока (эквивалентно os << value). Эта перегрузка участвует в разрешении перегрузки только в том случае, если выражение os << value корректно, а Ostream является типом класса, публично и однозначно производным от std::ios_base.

4) Перегрузки, принимающие char16_t, char32_t и т. д. (или завершающуюся нулём последовательность таких символов), удалены: std::cout << u'X' недопустимо. Ранее они выводили целочисленное значение или значение указателя.

Параметры

os	-	выходной поток, в который вставляются данные
ch	-	ссылка на символ для вставки
s	-	указатель на строку символов для вставки

Возвращаемое значение

1,2) os

3) std::move(os)

Примечания

До решения LWG 1203 код вида (std::ostringstream() << 1.2).str() не компилировался.

Пример

#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&)
}

Вывод:

Hello, world
!

Отчёты об ошибках

Следующие отчёты об ошибках, изменяющие поведение, были применены задним числом к ранее опубликованным стандартам C++.

DR	Применён к	Поведение согласно опубликованному стандарту	Корректное поведение
LWG 167	C++98	количество символов, вставляемых всеми перегрузками в (2), было `traits::length(s)`	обновлены значения для перегрузок, где `CharT` не соответствует типу `ch`
LWG 1203	C++11	перегрузка для rvalue-потока возвращала lvalue-ссылку на базовый класс	возвращает rvalue-ссылку на производный класс
LWG 2011	C++98	заполнение определялось `std::num_put::do_put()`	определяется самим оператором
LWG 2534	C++11	перегрузка для rvalue-потока не имела ограничений	имеет ограничения

См. также

operator<<	вставляет форматированные данные (открытая функция-член)
print(std::ostream) (C++23)	выводит форматированное представление аргументов (шаблон функции)
widen	расширяет символы (открытая функция-член `std::basic_ios<CharT,Traits>`)

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/cpp/io/basic_ostream/operator_ltlt2