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

 

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)

 

basic_ostream& operator<<( bool value );	(1)
basic_ostream& operator<<( long value );	(2)
basic_ostream& operator<<( unsigned long value );	(3)
basic_ostream& operator<<( long long value );	(4)	(C++11 起)
basic_ostream& operator<<( unsigned long long value );	(5)	(C++11 起)
basic_ostream& operator<<( double value );	(6)
basic_ostream& operator<<( long double value );	(7)
basic_ostream& operator<<( const void* value );	(8)
basic_ostream& operator<<( const volatile void* 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<<( unsigned short value );	(13)
basic_ostream& operator<<( unsigned int value );	(14)
basic_ostream& operator<<( float value );	(15)
basic_ostream& operator<<( /* extended-floating-point-type */ 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 行為。構造並檢查守衛物件後，透過呼叫 std::num_put::put() 插入值。如果在輸出期間遇到檔案尾條件 (put().failed() == true)，則設定 badbit。

9) 等價於 return operator<<(const_cast<const void*>(p));。

10) 等價於 return *this << s;，其中 s 是實現定義的以空字元結尾的字元型別字串。

11) 插入 short value 的值。

此函式作為 FormattedOutputFunction 行為。構造並檢查守衛物件後，插入 long 值 lval，如同在 (2) 中一樣，其中 lval 是

• static_cast<long>(static_cast<unsigned short>(value))，如果 flags() & std::ios_base::basefield 是 std::ios_base::oct 或 std::ios_base::hex，或
• static_cast<long>(value)，否則。

12) 插入 int value 的值。

此函式作為 FormattedOutputFunction 行為。構造並檢查守衛物件後，插入 long 值 lval，如同在 (2) 中一樣，其中 lval 是

• static_cast<long>(static_cast<unsigned int>(value))，如果 flags() & std::ios_base::basefield 是 std::ios_base::oct 或 std::ios_base::hex，或
• static_cast<long>(value)，否則。

13,14) 插入 unsigned short 或 unsigned int value 的值。

此函式作為 FormattedOutputFunction 行為。構造並檢查守衛物件後，插入 static_cast<unsigned long>(value)，如同在 (3) 中一樣。

15) 插入 float value 的值。

此函式作為 FormattedOutputFunction 行為。構造並檢查守衛物件後，插入 static_cast<double>(value)，如同在 (6) 中一樣。

16) 插入 value 的值。庫為所有 cv 非限定 擴充套件浮點型別 提供過載，作為引數值的型別。

此函式作為 FormattedOutputFunction 行為。構造並檢查守衛物件後，檢查 /* extended-floating-point-type */ 的 浮點轉換等級

• 如果等級小於或等於 double 的等級，則插入 static_cast<double>(value)，如同在 (6) 中一樣。
• 否則，如果等級小於或等於 long double 的等級，則插入 static_cast<long double>(value)，如同在 (7) 中一樣。
• 否則，此過載的呼叫是條件支援的，其語義由實現定義。

17) 此函式作為 UnformattedOutputFunction 行為。構造並檢查守衛物件後，檢查 sb 是否為空指標。如果是，則執行 setstate(badbit) 並退出。否則，從 sb 控制的輸入序列中提取字元並插入到 *this，直到滿足以下條件之一：

• 輸入序列上發生檔案尾；
• 輸出序列中插入失敗（在這種情況下，要插入的字元不會被提取）；
• 發生異常（在這種情況下，異常被捕獲）。

如果沒有插入任何字元，則執行 setstate(failbit)。如果在提取時丟擲異常，則設定 failbit，並且如果 exceptions() 中設定了 failbit，則重新丟擲異常。

18-20) 呼叫 func(*this)。這些過載用於實現輸出 I/O 操作器，例如 std::endl。

引數

value	-	要插入的整型、浮點型、布林型或指標值
func	-	要呼叫的函式
sb	-	指向要從中讀取資料的流緩衝區的指標

返回值

1-19) *this

20) func(*this)

注意

沒有針對指向非靜態成員的指標、指向 volatile 的指標，(直到 C++23) 或函式指標（除了 (18-20) 過載接受的簽名）的過載。

• 嘗試輸出此類物件會呼叫隱式轉換為 bool，對於任何非空指標值，都會列印值 1（除非設定了 boolalpha，在這種情況下會列印 true）。

字元和字串引數（例如，型別為 char 或 const char*）由 operator<< 的非成員過載處理。

• 嘗試使用成員函式呼叫語法輸出字元（例如，std::cout.operator<<('c');）將呼叫 (2-5) 或 (11-14) 中的一個過載並輸出數值。
• 嘗試使用成員函式呼叫語法輸出字串將呼叫過載 (8) 並列印指標值。

過載 (10) 是透過 LWG issue 2221 的決議新增的，但在任何 C++11/14 模式下的標準庫實現中從未實現過。

示例

執行此程式碼

#include <iomanip>
#include <iostream>
#include <sstream>
 
int fun() { return 42; }
 
int main()
{
    std::istringstream input(" \"Some text.\" ");
    double f = 3.14;
    bool b = true;
 
    std::cout
        << fun()          // int overload (12)
        << ' '            // non-member overload
        << std::boolalpha // function overload (18)
        << b              // bool overload (1)
        << " "            // non-member overload
        << std::fixed     // function overload (18) again
        << f              // double overload (6)
        << input.rdbuf()  // streambuf overload
        << fun            // bool overload (1): there's no overload for int(*)()
        << std::endl;     // function overload (18) again
 
    int x = 0;
    int* p1 = &x;
    volatile int* p2 = &x;
    std::cout
        << "p1: " << p1 << '\n'  // `const void*` overload, prints address
        << "p2: " << p2 << '\n'; // before C++23 (P1147): bool overload :), because
            // operator<<(const void*) is not a match, as it discards the `volatile`
            // qualifier. To fix this, C++23 adds `const volatile void*` overload (9),
            // that prints the address as expected.
}

可能的輸出

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

缺陷報告

下列更改行為的缺陷報告追溯地應用於以前出版的 C++ 標準。

缺陷報告	應用於	釋出時的行為	正確的行為
LWG 117	C++98	過載 (1-8,11-15) 將插入操作委託給 num_put::put，但它沒有針對 short、 unsigned short、int、unsigned int 和 float 的過載。	它們在傳遞給 num_put::put 之前 被轉換
LWG 567	C++98	過載 (17) 曾作為 FormattedOutputFunction 行為 由於 LWG issue 60 的決議	它現在作為 UnformattedOutputFunction（非格式化輸出函式）

參閱

operator<<(std::basic_ostream)	插入字元資料或插入到右值流中 (函式模板)
operator<<operator>>	對字串執行流輸入和輸出 (函式模板)
operator<< (C++17)	對 string_view 執行流輸出 (函式模板)
operator<<operator>>	執行位集的流輸入和輸出 (函式模板)
operator<<operator>>	序列化和反序列化複數 (函式模板)
operator<<operator>> (C++11)	對偽隨機數引擎執行流輸入和輸出 (函式模板)
operator<<operator>> (C++11)	對偽隨機數分佈執行流輸入和輸出 (函式模板)
put	插入一個字元 (公共成員函式)
write	插入字元塊 (公共成員函式)
to_chars (C++17)	將整數或浮點值轉換為字元序列 (函式)