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.

// 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

// 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.

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

Functions

Templates

Constructors

Destructors

Class Types

Class Variants

Lambdas

Coroutines

Pointers & References

Variables

Member Variables

Structured Bindings

Parameters

Error Handling

Enumerations

Namespaces

Selection Statements

Loops

Modules

Attributes

Fundamental Types

Include Directives

Comments

Memory Operators

Type Cast Operators

Access Operators

Increment & Decrement Operators

Unary Operators

Comparison Operators

Logical Operators

Conditional & Comma Operators

Arithmetic Operators

Assignment Operators

Bitwise Operators

C++ Nodiscard Attribute

Syntax

Application Targets

Code Visualization

Evaluation and Suppression Rules

​Syntax

​Application Targets

​Code Visualization

​Evaluation and Suppression Rules

Syntax

Application Targets

Code Visualization

Evaluation and Suppression Rules