C++属性 - nodiscard

程序员的园

发布于 2024-10-29 18:53:43

960

在软件开发中，有时某些函数、类型或枚举的返回值对程序的正确性至关重要。比如，内存分配、文件处理、网络请求等操作的结果都需要检查，以确保操作成功。忽视这些关键返回值可能导致未捕获的错误或未定义的行为。然而，由于 C++ 不强制使用返回值，开发者可能会不小心忽略这些返回值。

为了应对这些问题，C++17中引入的 [[nodiscard]] 属性，用以表明某些值很重要，不可忽略。通过该关键字可以显式告知编译器这些值必须被使用，如果忽略这些值，编译器会发出警告或错误，提醒开发者可能存在未处理的关键信息。合理使用 [[nodiscard]] 可以帮助捕获潜在的错误，避免因忽略返回值而导致的问题。

本文将介绍 [[nodiscard]] 的适用对象、标准要求及使用注意事项，并结合实例代码展示如何在代码中有效地使用该属性。

1. 走近[[nodiscard]]

[[nodiscard]] 是一种属性，用于标记那些不应被忽略的返回值。当被标记为 [[nodiscard]] 的函数、类型或枚举返回的值被忽略时，编译器会产生警告或错误。C++20 进一步增强了 [[nodiscard]] 的应用，允许开发者在属性后添加自定义消息，以便提供更详细的提示信息。

[[nodiscard]] 可以应用于以下几种实体：

函数声明：标记返回值不可忽略的函数，特别适用于那些返回错误码、状态码等的函数
类型声明：标记不可忽略的自定义类型（如类和结构体）
枚举声明：标记不可忽略的枚举类型

为确保被 [[nodiscard]] 标记的返回值不被忽略，C++ 标准要求编译器在以下场景中鼓励报错或警告：

调用 [[nodiscard]] 函数的返回值未被使用，且未转换为 void 类型
按值的形式返回标记为 [[nodiscard]] 的枚举或类
显示转换或 static_cast 的形式调用声明为 [[nodiscard]] 的构造函数
显式类型转换或 static_cast 的形式构造声明为 [[nodiscard]] 枚举或类的对象

通过这些规则，[[nodiscard]] 能有效提醒开发者避免忽视这些重要的返回值，从而减少潜在的运行时错误。

2. 代码示例

为了帮助理解 [[nodiscard]] 的具体应用，以下是一些典型的实例代码，展示如何将 [[nodiscard]] 应用于函数、类型和枚举，以及可能产生的编译器警告或错误。

2.1 标记函数

标记函数为 [[nodiscard]] 是最常见的用法。特别是在那些返回错误状态的函数中，忽略返回值可能导致未处理的错误。

#include<iostream>
[[nodiscard]] bool isFileValid(const std::string& filePath) {
 // 假设这里执行文件检查逻辑
 return !filePath.empty();
}
int main() {
 isFileValid("sample.txt"); // 忽略返回值，编译器会产生警告
 if (isFileValid("sample.txt")) { // 正确使用，编译器不会警告
 std::cout << "File is valid." << std::endl;
 }
 return 0;
}

在这个例子中，isFileValid 函数被标记为 [[nodiscard]]，因此如果调用 isFileValid 而不使用其返回值，编译器将发出警告，提醒开发者可能忽视了重要的检查结果。

2.2 标记类型

对于自定义类型（如类、结构体）来说，返回值也不应被忽略。例如，返回一个状态或结果类时可以标记为 [[nodiscard]]，避免在重要场景下忽略状态信息。

#include<iostream>
class [[nodiscard]] Status {
public:
 Status(bool success) : m_success(success) {}
 bool isSuccess() const { return m_success; }
private:
 bool m_success;
};

Status checkConnection() {
 // 模拟连接检查
 return Status(false); // 返回一个失败状态
}

int main() {
 checkConnection(); // 忽略返回值，编译器会产生警告
 Status status = checkConnection(); // 正确使用
 if (!status.isSuccess()) {
 std::cout << "Connection failed." << std::endl;
 }
 static_cast(true);//转换，编译器产生警告
 return 0;
}

在这个示例中，Status 类型被标记为 [[nodiscard]]，任何返回 Status 类型的调用如果忽略返回值，编译器会发出警告。这种方式可以有效防止错误信息被忽略。

2.3 标记枚举

[[nodiscard]] 也可以应用于枚举，特别是用于表示错误状态的枚举，忽略这些返回值可能导致程序在未处理错误状态的情况下继续运行。

#include<iostream>
enum class [[nodiscard]] ErrorCode {
 Success,
 FileNotFound,
 PermissionDenied
};

ErrorCode readFile(const std::string& filename) {
 // 模拟文件读取操作
 if (filename.empty()) return ErrorCode::FileNotFound;
 return ErrorCode::Success;
}

int main() {
 readFile(""); // 忽略返回值，编译器会产生警告
 ErrorCode result = readFile("sample.txt"); // 正确使用
 if (result == ErrorCode::FileNotFound) {
 std::cout << "File not found." << std::endl;
 }
 return 0;
}

在这个示例中，ErrorCode 枚举类型被标记为 [[nodiscard]]。如果调用 readFile 函数并忽略返回的 ErrorCode，编译器会发出警告，提醒开发者可能忽视了文件读取的结果。

2.4 使用带自定义消息的 [[nodiscard]]

C++20 增加了自定义消息的支持，开发者可以在 [[nodiscard]] 后添加一条消息，以便在编译器警告中提供更详细的提示信息，帮助开发者理解为何不可忽略。

#include<iostream>
[[nodiscard("The result of saveData should be checked to ensure successful save.")]]
bool saveData(const std::string& data) {
 // 假设数据保存逻辑
 return !data.empty();
}

int main() {
 saveData(""); // 忽略返回值，编译器会显示自定义警告信息
 if (!saveData("Important data")) { // 正确使用，编译器不会警告
 std::cout << "Failed to save data." << std::endl;
 }
 return 0;
}

在这个例子中，saveData 函数被标记为 [[nodiscard]] 并附带自定义信息。当返回值被忽略时，编译器会发出警告并显示“The result of saveData should be checked to ensure successful save.”，让开发者更清楚为什么不能忽略该返回值。

3.使用原则

为了有效使用 [[nodiscard]] 属性，以下是一些推荐的使用原则：