C++ attribute: nodiscard (since C++17)
From cppreference.com
 
 
 < cpp | language | attributes 
 
 
 C++ 
 Feature test macros (C++20)
 Concepts library (C++20)
 Metaprogramming library (C++11)
 Ranges library (C++20)
 Filesystem library (C++17)
 Concurrency support library (C++11)
 Execution control library (C++26)
C++ language 
 Flow control  Conditional execution statements Iteration statements (loops) Jump statements Functions  Function declaration  Lambda function expression  Dynamic exception specifications (until C++17*) Exceptions Namespaces Types Specifiers Storage duration specifiers  Initialization  Alternative representations  Literals  Boolean - Integer - Floating-point  Character - String - nullptr (C++11) User-defined (C++11) Utilities Attributes (C++11) Types Type alias declaration (C++11) Casts Memory allocation Classes  Class-specific function properties Special member functions Templates  Miscellaneous 
 
 
 
 
 
 
 
 
 
 
 
 
  General topics
inline specifier noexcept specifier (C++11)typedef declaration Declarations 
 
 
 
 
 
 
 
 
 
  
 Overview
 Specifiers
(C++11)
(C++20)
(C++20)
 Translation-unit-local (C++20)
(C++11)
(C++11)
(C++11)
 Pack indexing specifier (C++26)    
 Attributes (C++11)
 Declarators
 Block declarations
   →Structured binding declaration (C++17)
 Alias declaration (C++11)
 static_assert declaration (C++11)
 Opaque enum declaration (C++11)
 Other declarations
 Explicit template instantiation (C++11)
 Attribute declaration (C++11)
Attributes 
 
 
 
 
 
 
 
 
 
 
 
 
(C++23)
(C++11)(until C++26)
(C++14)
(C++17)
(C++26)
(C++20)
(C++17)
nodiscard
(C++17)
(C++11)
(C++20)
(TM TS)
(C++20)
If a function declared nodiscard or a function returning an enumeration or class declared nodiscard by value is called from a discarded-value expression other than a cast to void, the compiler is encouraged to issue a warning.
Contents
[edit] Syntax
[[nodiscard]]
 (1)
 (since C++17)
[[nodiscard( string-literal )]]
 (2)
 (since C++20)
 string-literal
 -
 an unevaluated string literal that could be used to explain the rationale for why the result should not be discarded
[edit] Explanation
Appears in a function declaration, enumeration declaration, or class declaration.
If, from a discarded-value expression other than a cast to void,
-  a function declared nodiscardis called, or
-  a function returning an enumeration or class declared nodiscardby value is called, or
-  a constructor declared nodiscardis called by explicit type conversion or static_cast, or
-  an object of an enumeration or class type declared nodiscardis initialized by explicit type conversion or static_cast,
the compiler is encouraged to issue a warning.
The string-literal, if specified, is usually included in the warnings.
(since C++20)[edit] Example
Run this code
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; }
Possible output:
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
| Standard libraryThe following standard functions are declared with  
 | (until C++26) | 
[edit] Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
| DR | Applied to | Behavior as published | Correct behavior | 
|---|---|---|---|
| P1771R1 | C++17 | [[nodiscard]]on constructors has no effect | can cause a warning if the constructed object is discarded | 
[edit] References
- C++23 standard (ISO/IEC 14882:2024):
- 9.12.9 Nodiscard attribute [dcl.attr.nodiscard]
 
- C++20 standard (ISO/IEC 14882:2020):
- 9.12.8 Nodiscard attribute [dcl.attr.nodiscard]
 
- C++17 standard (ISO/IEC 14882:2017):
- 10.6.7 Nodiscard attribute [dcl.attr.nodiscard]
 
[edit] See also
C documentation  for nodiscard