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> 的公共成員函式)