std::basic_ostream<CharT,Traits>::operator<<

 

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)

 

basic_ostream& operator<<(bool value );	(1)
basic_ostream& operator<<(long value );	(2)
basic_ostream& operator<<(unsignedlong value );	(3)
basic_ostream& operator<<(longlong value );	(4)	(C++11 起)
basic_ostream& operator<<(unsignedlonglong value );	(5)	(C++11 起)
basic_ostream& operator<<(double value );	(6)
basic_ostream& operator<<(longdouble value );	(7)
basic_ostream& operator<<(constvoid* value );	(8)
basic_ostream& operator<<(constvolatilevoid* value );	(9)	(C++23 起)
basic_ostream& operator<<(std::nullptr_t);	(10)	(C++17 起)
basic_ostream& operator<<(short value );	(11)
basic_ostream& operator<<(int value );	(12)
basic_ostream& operator<<(unsignedshort value );	(13)
basic_ostream& operator<<(unsignedint value );	(14)
basic_ostream& operator<<(float value );	(15)
basic_ostream& operator<<(/* 扩展浮点数类型 */ value );	(16)	(C++23 起)
basic_ostream& operator<<(std::basic_streambuf<CharT, Traits>* sb );	(17)
basic_ostream& operator<<(     std::ios_base&(*func)(std::ios_base&));	(18)
basic_ostream& operator<<(     std::basic_ios<CharT, Traits>&(*func)(std::basic_ios<CharT, Traits>&));	(19)
basic_ostream& operator<<(     std::basic_ostream<CharT, Traits>&(*func)         (std::basic_ostream<CharT, Traits>&));	(20)

将数据插入到流。

1-8) 插入 value。

此函数表现为有格式输出函数(FormattedOutputFunction) 。在构造并检查 sentry 对象后，通过调用 std::num_put::put() 插入值。如果在输出中遇到文件尾（put().failed()==true），那么就会设置 badbit。

9) 等价于 return operator<<(const_cast<constvoid*>(p));。

10) 等价于 return*this << s;，其中 s 是由实现定义的空终止字符类型字符串。

11) 插入来自 shortvalue 的值。

此函数表现为有格式输出函数(FormattedOutputFunction) 。在构造并检查 sentry 对象后，按 (2) 中的方式插入 long 值 lval，其中 lval：

• 在 flags()&std::ios_base::basefield 是 std::ios_base::oct 或 std::ios_base::hex 时是 static_cast<long>(static_cast<unsignedshort>(value))；
• 否则是 static_cast<long>(value)。

12) 插入来自 intvalue 的值。

此函数表现为有格式输出函数(FormattedOutputFunction) 。在构造并检查 sentry 对象后，按 (2) 中的方式插入 long 值 lval，其中 lval：

• 在 flags()&std::ios_base::basefield 是 std::ios_base::oct 或 std::ios_base::hex 时是 static_cast<long>(static_cast<unsignedint>(value))；
• 否则是 static_cast<long>(value)。

13,14) 插入来自 unsignedshort 或 unsignedintvalue 的值。

此函数表现为有格式输出函数(FormattedOutputFunction) 。在构造并检查 sentry 对象后，按 (3) 中的方式插入 static_cast<unsignedlong>(value)。

15) 插入来自 floatvalue 的值。

此函数表现为有格式输出函数(FormattedOutputFunction) 。在构造并检查 sentry 对象后，按 (6) 中的方式插入 static_cast<double>(value)。

16) 插入来自 value 的值。标准库提供所有以无 cv 限定的扩展浮点数类型作为参数 value 类型的重载。

此函数表现为有格式输出函数(FormattedOutputFunction) 。在构造并检查 sentry 对象后，检查 /* 扩展浮点数类型 */ 的浮点数转换等级：

• 如果该等级低于或等于 double 的等级，按 (6) 中的方式插入 static_cast<double>(value)。
• 否则，如果该等级低于或等于 longdouble 的等级，按 (7) 中的方式插入 static_cast<longdouble>(value)。
• 否则，对此重载的调用受条件性支持，并且语义由实现定义。

17) 表现为无格式输出函数(UnformattedOutputFunction) 。在构造并检查 sentry 对象后，检查 sb 是否为空指针。是的情况下执行 setstate(badbit) 并退出。否则，从 sb 控制的输入序列提取字符，并将它们插入到 *this，直到满足下列条件之一为止：

• 输入序列上出现文件尾；
• 插入输出序列失败（此时不会提取要被插入的字符）；
• 发生异常（此时异常会被捕获）。

如果没有插入字符，那么执行 setstate(failbit)。如果在提取中抛出异常，那么就会设置 failbit，而且如果在 exceptions() 设置里 failbit，那么就会重抛异常。

18-20) 调用 func(*this)。这些重载用于实现用于输出的输入/输出操纵符，例如 std::endl。

参数

value	-	要插入的整数、浮点数、布尔值或指针
func	-	要调用的函数
sb	-	指向要从之读取数据的流缓冲区的指针

返回值

1-19)*this

20)func(*this)

注解

没有对指向非静态数据成员指针、指向 volatile 指针(C++23 前)或函数指针（除了拥有 (18-20) 重载所接受之签名者）的重载。

• 试图输出这种对象会引发到 bool 的隐式转换，并对于任何非空指针值将打印值 1（除非设置了 boolalpha，此时会打印 true）。

字符与字符串实参（例如拥有 char 类型或 constchar* 类型者）由 operator<< 的非成员重载处理。

• 试图用成员函数调用语法输出字符（例如 std::cout.operator<<('c');）会调用重载 (2-5) 或 (11-14) 之一，并输出数字值。
• 试图用成员函数调用语法输出字符串会调用重载 (8) 而改为打印指针值。

重载 (10) 由 LWG 问题 2221的解决方案添加，但是没有任何标准库实现在 C++11/14 模式下实现它。

示例

运行此代码

#include <iomanip>#include <iostream>#include <sstream>   int fun(){return42;}   int main(){std::istringstream input(" \"Some text.\" ");double f =3.14;bool b =true;   std::cout<< fun()// int 重载 (12)<<' '// 非成员重载<<std::boolalpha// 函数重载 (18)<< b // bool 重载 (1)<<" "// 非成员重载<<std::fixed// 又是函数重载 (18)<< f // double 重载 (6)<< input.rdbuf()// streambuf 重载<< fun // bool 重载 (1)：没有 int(*)() 的重载<<std::endl;// 又是函数重载 (18)   int x =0;int* p1 =&x;volatileint* p2 =&x;std::cout<<"p1: "<< p1 <<'\n'// `const void*` 重载，打印地址<<"p2: "<< p2 <<'\n';// C++23 (P1147) 之前: bool 重载 :)// 因为其并不匹配 operator<<(const void*)，由于它舍弃了 `volatile` 限定符。// 为修正这点，C++23 添加了 `const volatile void*` 的重载 (9)，// 它按预期打印了地址。}

可能的输出：

42 true 3.140000 "Some text." true p1: 0x7ffcea766600 p2: 0x7ffcea766600

缺陷报告

下列更改行为的缺陷报告追溯地应用于以前出版的 C++ 标准。

缺陷报告	应用于	出版时的行为	正确行为
LWG 117	C++98	重载 (1-8,11-15) 通过 num_put::put 代理插入操作，但它没有为 short，unsignedshort，int，unsignedint 以及 float 重载	它们在传递到 num_put::put 之前会先进行转换
LWG 567	C++98	重载 (17) 因 LWG 问题 60 的解决方案而表现为 有格式输出函数(FormattedOutputFunction)	表现为 无格式输出函数(UnformattedOutputFunction)

参阅

operator<<(std::basic_ostream)	插入字符数据，或向右值流插入 (函数)
operator<<operator>>	执行字符串的流输入与输出 (函数模板)
operator<< (C++17)	进行字符串视图的流输出 (函数模板)
operator<<operator>>	执行 bitset 的流输入和输出 (函数)
operator<<operator>>	复数的序列化和反序列化 (函数模板)
operator<<operator>> (C++11)	执行伪随机数引擎的流输入和输出 (函数模板)
operator<<operator>> (C++11)	执行伪随机数分布的流输入和输出 (函数模板)
put	插入字符 (公开成员函数)
write	按区块插入字符 (公开成员函数)
to_chars (C++17)	转换整数或浮点数为字符序列 (函数)