C++ 屬性：nodiscard （自 C++17 起）

 

C++

編譯器支援

自由（freestanding）與宿主（hosted）

語言

標準庫

標準庫標頭檔案

具名要求

特性測試宏 (C++20)

語言支援庫

概念庫 (C++20)

診斷庫

記憶體管理庫

超程式設計庫 (C++11)

通用工具庫

容器庫

迭代器庫

範圍庫 (C++20)

演算法庫

字串庫

文字處理庫

數值庫

日期和時間庫

輸入/輸出庫

檔案系統庫 (C++17)

併發支援庫 (C++11)

執行控制庫 (C++26)

技術規範

符號索引

外部庫

 

C++ 語言

通用主題
預處理器 註釋	關鍵詞 轉義序列
流程控制
條件執行語句
if	switch
迭代語句（迴圈）
for range-for （C++11）	while do-while
跳轉語句
continue - break	goto - return
函式
函式宣告
Lambda 函式表示式
inline 說明符
動態異常規範 (直到 C++17*)
noexcept 說明符 (C++11)
異常
throw 表示式 try 塊	catch 處理程式
名稱空間
名稱空間宣告	命名空間別名
型別
基本型別 列舉型別 函式型別	類/結構體型別 聯合型別
說明符
const/volatile decltype （C++11） auto （C++11）	constexpr （C++11） consteval （C++20） constinit （C++20）
儲存期說明符
初始化
預設初始化 值初始化 零初始化 複製初始化 直接初始化	聚合初始化 列表初始化 (C++11)   常量初始化 引用初始化

表示式
值類別 求值順序	運算子 運算子優先順序
替代表示
字面量
布林 - 整數 - 浮點
字元 - 字串 - nullptr （C++11）
使用者定義 (C++11)
工具
屬性 (C++11)
型別
typedef 宣告
類型別名宣告 (C++11)
型別轉換
隱式轉換 static_cast const_cast	顯式轉換 dynamic_cast reinterpret_cast
記憶體分配
new 表示式	delete 表示式
類
類宣告 建構函式 this 指標	訪問說明符 friend 說明符
類特有的函式屬性
虛擬函式 override 說明符 (C++11)   final 說明符 (C++11)	explicit （C++11） static
特殊成員函式
預設建構函式 複製建構函式 移動建構函式 (C++11)	複製賦值 移動賦值 (C++11) 解構函式
模板
類模板 函式模板	模板特化 引數包 (C++11)
雜項
內聯彙編	C++ 歷史

 

宣告

概覽 宣告語法 宣告說明符序列 宣告符 衝突宣告 說明符 typedef inline virtual 函式說明符 explicit 函式說明符 friend constexpr （C++11） consteval （C++20） constinit （C++20） 儲存類說明符 翻譯單元區域性 (C++20) class/struct union enum decltype （C++11） auto （C++11） alignas （C++11） constvolatile 包索引說明符 (C++26)     細化型別說明符 屬性 (C++11)

宣告符 引用 指標 陣列 塊宣告 簡單宣告   →結構化繫結宣告 (C++17) 別名宣告 (C++11) 命名空間別名定義 using 宣告 using 指令 static_assert 宣告 (C++11) asm 宣告 不透明列舉宣告 (C++11) 其他宣告 名稱空間定義 函式宣告 類模板宣告 函式模板宣告 顯式模板例項化 (C++11) 顯式模板特化 連結規範 屬性宣告 (C++11) 空宣告

 

屬性

assume （C++23）

carries_dependency (C++11)(直至 C++26)

deprecated （C++14）

fallthrough （C++17）

indeterminate （C++26）

likely （C++20）

maybe_unused （C++17）

nodiscard （C++17）

noreturn （C++11）

no_unique_address （C++20）

optimize_for_synchronized （TM TS）

unlikely （C++20）

 

如果一個被宣告為 `nodiscard` 的函式，或者一個返回被宣告為 `nodiscard` 的列舉或類的函式以值傳遞方式被從丟棄值表示式中呼叫（除了轉換為 void 的情況），編譯器應發出警告。

語法

[[nodiscard]]	(1)	(C++17 起)
[[nodiscard( string-literal )]]	(2)	(C++20 起)

字串字面量

-

一個未求值的字串字面量，可用於解釋不應丟棄結果的原因。

解釋

出現在函式宣告、列舉宣告或類宣告中。

如果，從一個丟棄值表示式中（除了轉換為 void 的情況）：

• 呼叫了被宣告為 `nodiscard` 的函式，或
• 呼叫了返回被宣告為 `nodiscard` 的列舉或類的函式（按值傳遞），或
• 透過顯式型別轉換或static_cast呼叫了被宣告為 `nodiscard` 的建構函式，或
• 透過顯式型別轉換或static_cast初始化了被宣告為 `nodiscard` 的列舉或類型別物件，

編譯器應發出警告。

如果指定了 string-literal，通常會包含在警告中。

(C++20 起)

示例

執行此程式碼

struct [[nodiscard]] error_info { /*...*/ };
 
error_info enable_missile_safety_mode() { /*...*/ return {}; }
 
void launch_missiles() { /*...*/ }
 
void test_missiles()
{
    enable_missile_safety_mode(); // compiler may warn on discarding a nodiscard value
    launch_missiles();
}
 
error_info& foo() { static error_info e; /*...*/ return e; }
 
void f1() { foo(); } // nodiscard type is not returned by value, no warning
 
// nodiscard( string-literal ) (since C++20):
[[nodiscard("PURE FUN")]] int strategic_value(int x, int y) { return x ^ y; }
 
int main()
{
    strategic_value(4, 2); // compiler may warn on discarding a nodiscard value
    auto z = strategic_value(0, 0); // OK: return value is not discarded
    return z;
}

可能的輸出

game.cpp:5:4: warning: ignoring return value of function declared with ⮠
 'nodiscard' attribute
game.cpp:17:5: warning: ignoring return value of function declared with ⮠
 'nodiscard' attribute: PURE FUN

標準庫 以下標準函式使用 `nodiscard` 屬性宣告： 擴充套件內容 分配函式 operator newoperator new[] 分配函式 （函式） allocate 分配未初始化的儲存 （std::allocator<T> 的公共成員函式） allocate [靜態] 使用分配器分配未初始化的儲存 （std::allocator_traits<Alloc> 的公共靜態成員函式） allocate 分配記憶體 （std::pmr::memory_resource 的公共成員函式） allocate 分配記憶體 （std::pmr::polymorphic_allocator<T> 的公共成員函式） allocate 使用外部分配器分配未初始化的儲存 （std::scoped_allocator_adaptor<OuterAlloc,InnerAlloc...> 的公共成員函式） 間接訪問 launder （C++17） 指標最佳化屏障 （函式模板） assume_aligned （C++20） 通知編譯器指標已對齊 （函式模板） 空值檢查函式 empty （C++17） 檢查容器是否為空 （函式模板） empty 檢查節點控制代碼是否為空 （node handle 的公共成員函式） empty 檢查容器是否為空 （std::array<T,N> 的公共成員函式） empty 檢查字串是否為空 （std::basic_string<CharT,Traits,Allocator> 的公共成員函式） empty 檢查檢視是否為空 （std::basic_string_view<CharT,Traits> 的公共成員函式） empty 檢查容器是否為空 （std::deque<T,Allocator> 的公共成員函式） empty 檢查容器是否為空 （std::forward_list<T,Allocator> 的公共成員函式） empty 檢查容器是否為空 （std::list<T,Allocator> 的公共成員函式） empty 檢查容器是否為空 （std::map<Key,T,Compare,Allocator> 的公共成員函式） empty 檢查匹配是否成功 （std::match_results<BidirIt,Alloc> 的公共成員函式） empty 檢查容器是否為空 （std::multimap<Key,T,Compare,Allocator> 的公共成員函式） empty 檢查容器是否為空 （std::multiset<Key,Compare,Allocator> 的公共成員函式） empty 檢查容器介面卡是否為空 （std::priority_queue<T,Container,Compare> 的公共成員函式） empty 檢查容器介面卡是否為空 （std::queue<T,Container> 的公共成員函式） empty 檢查容器是否為空 （std::set<Key,Compare,Allocator> 的公共成員函式） empty 檢查序列是否為空 （std::span<T,Extent> 的公共成員函式） empty 檢查容器介面卡是否為空 （std::stack<T,Container> 的公共成員函式） empty 檢查容器是否為空 （std::unordered_map<Key,T,Hash,KeyEqual,Allocator> 的公共成員函式） empty 檢查容器是否為空 （std::unordered_multimap<Key,T,Hash,KeyEqual,Allocator> 的公共成員函式） empty 檢查容器是否為空 （std::unordered_multiset<Key,Hash,KeyEqual,Allocator> 的公共成員函式） empty 檢查容器是否為空 （std::unordered_set<Key,Hash,KeyEqual,Allocator> 的公共成員函式） empty 檢查容器是否為空 （std::vector<T,Allocator> 的公共成員函式） empty 檢查路徑是否為空 （std::filesystem::path 的公共成員函式） 雜項 async （C++11） 非同步（可能在新執行緒中）執行一個函式並返回一個將儲存結果的 std::future （函式模板）

（直到 C++26）

缺陷報告

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

缺陷報告	應用於	釋出時的行為	正確的行為
P1771R1	C++17	建構函式上的 [[nodiscard]] 無效	如果構造的物件被丟棄，可能會導致警告

參考資料

• C++23 標準 (ISO/IEC 14882:2024)

• 9.12.9 Nodiscard 屬性 [dcl.attr.nodiscard]

• C++20 標準 (ISO/IEC 14882:2020)

• 9.12.8 Nodiscard 屬性 [dcl.attr.nodiscard]

• C++17 標準 (ISO/IEC 14882:2017)

• 10.6.7 Nodiscard 屬性 [dcl.attr.nodiscard]

另請參閱

ignore （C++11）	使用 tie 解包 tuple 時跳過元素的佔位符 （常量）
C 文件 for nodiscard