operator<<(std::basic_ostream)

 

C++

编译器支持

独立式和托管式

语言

标准库

标准库头文件

命名要求

特性测试宏 (C++20)

语言支持库

概念库 (C++20)

元编程库 (C++11)

诊断库

通用工具库

字符串库

容器库

迭代器库

范围库 (C++20)

算法库

数值库

本地化库

输入/输出库

文件系统库 (C++17)

正则表达式库 (C++11)

并发支持库 (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，则填充字符放置在输出字符之后，否则放置在之前。

插入后，调用 os.width(0) 来取消 std::setw 的效果（如果有）。

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

插入后，调用 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<<	插入格式化数据 (公共成员函数)
print(std::ostream) (C++23)	输出参数的 格式化 表示形式 (函数模板)
widen	加宽字符 (std::basic_ios<CharT,Traits> 的公共成员函数)