operator<<(std::basic_ostream)

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

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

1) Ведёт себя как FormattedOutputFunction. После создания и проверки объекта sentry, вставляет символ ch. Если тип символа не CharT, он сначала преобразуется с помощью 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) Ведёт себя как FormattedOutputFunction. После создания и проверки объекта 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 является указателем на null, поведение неопределено.

3) Вызывает соответствующий оператор вставки, учитывая ссылку правого значения на объект потока вывода (эквивалентно 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 issue 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	перегрузка для потока правого значения возвращала ссылку на левое значение на базовый класс	возвращает ссылку правого значения на производный класс
LWG 2011	C++98	выравнивание определялось по `std::num_put::do_put()`	определяется самим оператором
LWG 2534	C++11	перегрузка для потока правого значения не была ограничена	ограничена

См. также

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/w/cpp/io/basic_ostream/operator_ltlt2