operator<<(std::basic_ostream)

 

C++

编译器支持

独立和宿主式

语言

标准库

标准库头文件

命名要求

特性测试宏 (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)	(since C++11)
为 basic_ostream 和 UTF 字符/数组 删除的重载
			(4)	(since 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。如果 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) 行为如同 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 是空指针，则行为未定义。

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 问题 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<<	插入格式化数据 (public member function)
print(std::ostream) (C++23)	输出参数的格式化表示 (function template)
widen	加宽字符 (public member function of std::basic_ios<CharT,Traits>)