Skip to main content

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.

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
}
Master C++ with Deep Grasping Methodology!Learn More