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, signedchar ch );
template<class Traits > basic_ostream<char, Traits>&     operator<<( basic_ostream<char, Traits>& os, unsignedchar 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, constchar* s );
template<class Traits > basic_ostream<char, Traits>&     operator<<( basic_ostream<char, Traits>& os, constchar* s );
template<class Traits > basic_ostream<char, Traits>&     operator<<( basic_ostream<char, Traits>& os, constsignedchar* s );
template<class Traits > basic_ostream<char, Traits>&     operator<<( basic_ostream<char, Traits>& os, constunsignedchar* 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, constwchar_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, constchar16_t* s )= delete;
template<class Traits > basic_ostream<char, Traits>&     operator<<( basic_ostream<char, Traits>& os, constchar32_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, constchar16_t* s )= delete;
template<class Traits > basic_ostream<wchar_t, Traits>&     operator<<( basic_ostream<wchar_t, Traits>& os, constchar32_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<constchar*>(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(){// 错误：operator<< (basic_ostream<char, _Traits>&, char8_t) 被弃置// 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"// 使用 const char* 重载<<'\n';// 使用 char 重载std::ofstream("test.txt")<<1.2;// 使用右值重载   std::cout<< u8'!'<<'\n';// 使用程序定义的 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> 的公开成员函数)