operator<<(std::basic_ostream)

 

C++

编译器支持

自由（freestanding）与宿主（hosted）

语言

标准库

标准库头文件

具名要求

特性测试宏 (C++20)

语言支持库

概念库 (C++20)

诊断库

内存管理库

元编程库 (C++11)

通用工具库

容器库

迭代器库

范围库 (C++20)

算法库

字符串库

文本处理库

数值库

日期和时间库

输入/输出库

文件系统库 (C++17)

并发支持库 (C++11)

执行控制库 (C++26)

技术规范

符号索引

外部库

 

输入/输出库

I/O 操纵器

打印函数 (C++23)

C 风格 I/O

缓冲区

basic_streambuf

basic_filebuf

basic_stringbuf

basic_spanbuf (C++23)

strstreambuf (C++98/26*)

basic_syncbuf (C++20)

流

抽象

ios_base

basic_ios

basic_istream

basic_ostream

basic_iostream

文件 I/O

basic_ifstream

basic_ofstream

basic_fstream

字符串 I/O

basic_istringstream

basic_ostringstream

basic_stringstream

数组 I/O

basic_ispanstream (C++23)

basic_ospanstream (C++23)

basic_spanstream (C++23)

istrstream (C++98/26*)

ostrstream (C++98/26*)

strstream (C++98/26*)

同步输出

basic_osyncstream (C++20)

类型

streamoff

streamsize

fpos

错误类别接口

iostream_category (C++11)

io_errc (C++11)

 

std::basic_ostream

全局对象
coutwcout	cerrwcerr	clogwclog
成员函数
basic_ostream::basic_ostream
basic_ostream::~basic_ostream
basic_ostream::operator= (C++11)
格式化输出
basic_ostream::operator<<
非格式化输出
basic_ostream::put
basic_ostream::write
定位
basic_ostream::tellp
basic_ostream::seekp
杂项
basic_ostream::flush
basic_ostream::swap (C++11)
成员类
basic_ostream::sentry
非成员函数
operator<<(std::basic_ostream)
print(std::ostream) (C++23)
println(std::ostream) (C++23)
vprint_unicode(std::ostream) (C++23)
vprint_nonunicode(std::ostream) (C++23)

 

定义于头文件 <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) 表现为一个 格式化输出函数。在构造并检查 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，则填充字符放置在输出字符之后，否则放置在之前。

插入后，如果使用了 std::setw，则调用 os.width(0) 以取消其效果。

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，填充字符添加到输出序列的末尾，否则添加到输出序列之前。

插入后，如果使用了 std::setw，则调用 os.width(0) 以取消其效果。

如果 s 是空指针，则行为未定义。

3) 给定一个输出流对象的右值引用时，调用适当的插入运算符（等价于 os << value）。此重载仅在表达式 os << value 格式良好且 Ostream 是一个公开且明确地派生自 std::ios_base 的类类型时才参与重载决议。

4) 接受 char16_t、char32_t 等（或以 null 结尾的序列）的重载被删除：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++ 标准。

缺陷报告	应用于	发布时的行为	正确的行为
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> 的公共成员函数)