> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# C++ Nodiscard Attribute
The `[[nodiscard]]` attribute is a C++17 standard attribute used to indicate that the return value of a function, or an object of a specific type returned by value, should not be ignored by the caller. When the compiler detects that a `[[nodiscard]]` result is evaluated as a discarded-value expression, the C++ standard specifies as a recommended practice that the compiler should emit a diagnostic warning. It is not a strictly mandated diagnostic that makes the program ill-formed, but compilers are highly encouraged to report it.
## Syntax
The attribute can be applied in two forms, with C++20 introducing the ability to provide a custom diagnostic message.
```cpp theme={"dark"}
// C++17 standard syntax
[[nodiscard]] return_type function_name();
// C++20 syntax with a string literal diagnostic message
[[nodiscard("string_literal")]] return_type function_name();
```
## Application Targets
The attribute modifies compiler behavior depending on the entity it is applied to:
* **Functions:** When applied to a function declaration, any call to that specific function that discards the return value will trigger a warning.
* **Types (Classes, Structs, Enumerations):** When applied to a user-defined type, any function that returns that type *by value* implicitly becomes a `[[nodiscard]]` function. Returning the type by pointer or reference does not trigger the attribute's behavior.
* **Constructors (C++20):** When applied to a constructor, the compiler issues a warning if a temporary object is instantiated using that constructor but is immediately destroyed without being bound to a variable or reference.
## Code Visualization
```cpp theme={"dark"}
// 1. Applied to a function
[[nodiscard]] int calculate_offset();
// 2. Applied to a type
struct [[nodiscard]] StatusToken {
int code;
};
// Implicitly inherits [[nodiscard]] behavior because it returns StatusToken by value
StatusToken generate_token();
// Does NOT inherit [[nodiscard]] behavior (returns by reference)
StatusToken& get_cached_token();
// 3. Applied to a constructor (C++20)
struct Resource {
[[nodiscard]] Resource(int size);
};
```
## Evaluation and Suppression Rules
A warning is generated strictly when the expression evaluates to a discarded value. Binding the result to a variable, using it in a conditional statement, or passing it as an argument to another function satisfies the attribute.
If a developer needs to intentionally discard a `[[nodiscard]]` value and suppress the compiler warning, the standard mechanism is to explicitly cast the function call to `void`.
```cpp theme={"dark"}
void evaluate_nodiscard() {
calculate_offset(); // Warning: ignoring return value of function declared with 'nodiscard' attribute
int x = calculate_offset(); // OK: value is bound to 'x'
generate_token(); // Warning: ignoring return value of type 'StatusToken' declared with 'nodiscard' attribute
get_cached_token(); // OK: returns by reference, attribute does not apply
Resource(1024); // Warning: ignoring temporary object created by 'nodiscard' constructor
// Explicit suppression
(void)calculate_offset(); // OK: explicit cast to void suppresses the diagnostic
}
```
Tired of Poor C++ Skills? Fix That With Deep Grasping!
Learn More
