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